2.2.4.7 Context hooks and window metadata for user assistance

Context hook information specified in the <resourceid> element in the DITA map or in a DITA topic enables processors to generate the header, map, alias and other types of support files that are required to integrate the user assistance with the application. Some user assistance topics might need to be displayed in a specific window or viewport, and this windowing metadata can be defined in the DITA map within the <ux-window> element.

Context hook and windowing information is ignored if the processor does not support this metadata.

User interfaces for software application often are linked to user assistance (such as help systems and tool tips) through context hooks. Context hooks are identifiers that associate a part of the user interface with the location of a help topic. Context hooks can be direct links to URIs, but more they are indirect links (numeric context identifiers and context strings) that can be processed into external resource files. Context hooks can be direct links to URIs, but more often they are indirect links (numeric context identifiers and context strings) that can processed into external resource files. These external resource and mapping files are then used directly by context-sensitive help systems and other downstream tream applications.

Context hooks can define either one-to-one or one-to-many relationships between user interface controls and target help content.

The metadata that is available in <resourceid> and <ux-window> provides flexibility for content developers:

• You can overload maps and topics with all the metadata needed to support multiple target help systems. This supports single-sourcing of help content and help metadata.
• You can choose whether to add <resourceid> metadata to <topicref> elements, <prolog> elements, or both. Context-dependent metadata might be best be kept with maps, while persistent, context-independent metadata might best stay with topics in <prolog> elements

Context hook information is defined within DITA topics and DITA maps through attributes of the <resourceid> element:

@appid

Specifies an identifier that is used by an application to identify the topic.

@ux-context-string

Contains the value of a user-assistance context string that is used to identify the topic.

@ux-source-priority

(For <resourcid> elements within maps) Contains a value that indicates the precedence of context hooks in the map and context hooks in the topic. This makes it possible to avoid problems where context hooks defined in the DITA map potentially conflict with those defined in the topics; the values of the @ux-source-priority attribute indicate how potential conflicts should be resolved.

(For <resourcid> elements within topics) This usage is undefined and reserved for future use. Processors should ignore the @ux-source-priority attribute.

@ux-windowref

References the name of the window to be used to display the help topic. The window characteristics are separately defined in a <ux-window> element in the DITA map.

In some help systems, a topic might need to be displayed in a specifically sized or featured window. For example, a help topic might need to be displayed immediately adjacent to the user interface control that it supports in a window of a specific size that always remains on top, regardless of the focus within the operating system. Windowing metadata can be defined in the DITA map within the <ux-window> element.

The <ux-window> element provides the @top, @left, @height, @width, @on-top, @features, @relative, and @full-screen attributes.