# helpKey Properties Files

A helpKey properties file defines the mapping of helpKey constants (property keys), either to actual help context IDs, or to context-specific help search expressions.

helpKey properties files are usually contributed in pairs, one for context IDs and one for search expressions.

The help context ID strings defined in a helpKey properties file cannot be fully-qualified context IDs. They must not include any blank space or period (.) characters. The DTP help-helper handles unqualified help context IDs defined in properties files to fully-qualify them, before it returns them to the UI control through the ContextProviderDelegate.

The following excerpt is from a helpKey properties file, which is contributed by the org.eclipse.datatools.doc.user.contexts plug-in to define concrete help context ID strings.

        ...
        #	CONTEXT_ID_CP_PROPERTY_PAGE =
        #	Basic profile name/description/auto-connect property page
        CONTEXT_ID_CP_PROPERTY_PAGE = CONNECTION_PROFILE_COMMON_PROPERTY_PAGE

        #	CONTEXT_ID_CP_WIZARD_PAGE =
        #	wizard selection page in New Connection Profile wizard
        CONTEXT_ID_CP_WIZARD_PAGE = NEW_CONNECTION_PROFILE_WIZARD

        #	CONTEXT_ID_INTRO_WIZARD_PAGE =
        #	Basic intro page for new connection profile wizard
        CONTEXT_ID_INTRO_WIZARD_PAGE = NEW_CONNECTION_PROFILE_WIZARD
        ...

Notice that two abstract help contexts (represented by the helpKey constants `CONTEXT_ID_CP_WIZARD_PAGE` and `CONTEXT_ID_INTRO_WIZARD_PAGE`) are mapped to one concrete help context ID (`NEW_CONNECTION_PROFILE_WIZARD`). This is an example of the flexibility afforded by abstract help contexts, allowing the UA component to combine multiple abstract help contexts in a single, concrete help context ID, which is independent of the help context implementation in the UI component.

The following example shows the mapping of a helpKey constant to a context-specific help search expression in a helpKey properties file.

        ...
        #	 * CONTEXT_ID_CP_PROPERTY_PAGE =
        #	 * Basic profile name/description/auto-connect property page
        CONTEXT_ID_CP_PROPERTY_PAGE = "connection profile" AND "properties"
        ...

Search expression strings must conform to the rules for Apache Lucene query parser syntax: http://lucene.apache.org/java/docs/queryparsersyntax.html

Note: The terms (keywords) in a search expression are not case sensitive, but the Boolean operators (for example, AND, NOT, OR) must be all upper case.

- helpKey Properties File Names
  Names of helpKey properties files are arbitrary (as long as they end with .properties). However, a context-sensitive help plug-in could contribute pairs of helpKey properties files for several UI plug-ins, and the files would need to have unique names, if they were located in the same directory.