<resourceid>

A resource ID is an identifier that is designed for applications that need to use their own identifier scheme, such as context-sensitive help systems and databases.

Usage information

The @appid and @appname attributes work in combination to specify a specific ID for an application. Multiple @appid values can be associated with a single @appname value, and multiple @appname values can be associated with a single @appid value.Accordingly, each combination of values for the @appid and @appname attributes need to be unique within the context of the main map.

When the @appid-role attribute is set to deliverable-anchor, the value that it specifies contributes to deliverable anchors for a topic. According, certain limitations apply to the value of the @appid attribute:

  • It specifies only a single URI component.
  • It is limited to values that can contribute to the following URI components:
    • The last path component of a URI path
    • A fragment identifier
    • A query parameter
  • It should not specify components of URIs that are specific to a particular deliverable, such as a file extension.

Processing expectations

By design, the <resourceid> element will not apply to all processors in all situations. Processors can examine the @appname and @appid-role attributes to determine whether a given <resourceid> element is relevant to a specific deliverable; if @appname is not present, processors can assume that the element applies.

When @appid-role is set to deliverable-anchor, and the <resourceid> applies to a deliverable, processors SHOULD use the @appid value when constructing a URI for the delivered resource. Effective @appid values for this reflect the application of any prefix or suffix values from dvrKeyscopePrefix and dvrResourceSuffix. Actual delivery anchors depend on the rendered format; for example, the anchor can be the base part of an HTML file name, a PDF anchor name, or a URI fragment identifier. While anchors values will vary by deliverable, the resulting URI should reflect the specified anchor as much as possible.

When @appid-role is set to context-sensitive-help or another value, processors can optionally use the @appid value IDs to construct deliverable anchors. Deliverable components MAY have any number of anchors when the deliverable format allows.

Processors can use other properties of the referenced resource, or properties of the reference itself, when constructing full deliverable anchors. For example, key scope names, key names, or source file names can all be used with the resource ID when constructing unique anchor values.

Content model

( <data> | <sort-as> )**

Zero or more Zero or more

Attributes

The following attributes are available on this element: universal attributes and the attributes defined below.

@appname
Specifies a name for the external application.
@appid
Specifies an ID that can be used by an application to identify the topic.

When @app-role is set to deliverable-anchor, certain restrictions apply to the value of the @appid attribute. See Usage information.

@appid-role
Specifies the role that the @appid value plays for applications. The value is a single name token. The default value is context-sensitive-help. While applications can define their own values, the following values are defined by OASIS:
context-sensitive-help
Specifies that the value of the @appid attribute is used to connect the associated resource with applications that use the associated resource as context sensitive help.
deliverable-anchor
Specifies that the value of the @appid attribute is used to construct anchors for the associated resource.

When @app-role is set to deliverable-anchor, certain restrictions apply to the value of the @appid attribute. See Usage information.

@ux-context-string
Specifies the value of a user-assistance context-string that is used to identify the topic.
@ux-source-priority

Specifies precedence for handling <resourceid> definitions that exist in both a map and a topic. This attribute is only valid when used within a <topicref> element in a map. The following values are valid:

map-only
Use IDs from the map only.
map-takes-priority
Use the IDs from the map, if they exist. Otherwise, use IDs from the topic.
topic-and-map
Use IDs from both the topic and map.
topic-only
Use IDs from the topic only.
topic-takes-priority
Use the IDs from the topic, if they exist. Otherwise, use IDs from the map.
-dita-use-conref-target
See Using the -dita-use-conref-target value for more information.
@ux-windowref
References the @name attribute on the <ux-window> element that is used to display the topic when called from a help API.

The following attributes are available on this element: universal attributes and the attributes defined below.

@appid
Specifies an ID that can be used by an application to identify the topic.

When @app-role is set to deliverable-anchor, certain restrictions apply to the value of the @appid attribute. See Usage information.

@appid-role
Specifies the role that the @appid value plays for applications. The value is a single name token. The default value is context-sensitive-help. While applications can define their own values, the following values are defined by OASIS:
context-sensitive-help
Specifies that the value of the @appid attribute is used to connect the associated resource with applications that use the associated resource as context sensitive help.
deliverable-anchor
Specifies that the value of the @appid attribute is used to construct anchors for the associated resource.

When @app-role is set to deliverable-anchor, certain restrictions apply to the value of the @appid attribute. See Usage information.

@appname
Specifies a name for the external application.
@ux-context-string
Specifies the value of a user-assistance context-string that is used to identify the topic.
@ux-source-priority

Specifies precedence for handling <resourceid> definitions that exist in both a map and a topic. This attribute is only valid when used within a <topicref> element in a map. The following values are valid:

map-only
Use IDs from the map only.
map-takes-priority
Use the IDs from the map, if they exist. Otherwise, use IDs from the topic.
topic-and-map
Use IDs from both the topic and map.
topic-only
Use IDs from the topic only.
topic-takes-priority
Use the IDs from the topic, if they exist. Otherwise, use IDs from the map.
-dita-use-conref-target
See Using the -dita-use-conref-target value for more information.
@ux-windowref
References the @name attribute on the <ux-window> element that is used to display the topic when called from a help API.

Examples

This section is non-normative.

This section contains examples of how the <resourceid> element can be used.

Example 1. Example: Using a <resourceid> element in a map to generate hooks for online help

In the following code sample, user-assistance context hooks are applied to three topics that are referenced from a DITA map. The second topic has two hooks for the same topic.

<map>
 <title>Widget Help</title>
 <topicref href="file_ops.dita">
   <topicref href="saving.dita">
     <topicmeta>
     <resourceid appname="ua" appid="1234" ux-context-string="idh_filesave"
     ux-source-priority="topic-only"/>
     </topicmeta>
   </topicref>
   <topicref href="deleting.dita">
     <topicmeta>
      <resourceid appname="ua" 
           appid="2345" ux-context-string="idh_filedelete" />
      <resourceid appname="ua" 
           appid="6789" ux-context-string="idh_filekill" />
     </topicmeta>
   </topicref>
   <topicref href="editing.dita">
     <topicmeta>
       <resourceid appname="ua" 
            appid="5432" ux-context-string="idh_fileedit" ux-windowref="csh"  />
     </topicmeta>
   </topicref>
</topicref>
</map>
Example 2. Example: Using a <resourceid> element in a topic to generate hooks for online help

In the following code sample, a user-assistance context hook is defined in the prolog of a task topic. The context hook is made up of a context ID (value for @appid attribute) and a context string (value for @ux-context-string attribute). A user-assistance window profile is also referenced for this topic. 

<task id="fedt">
 <title>Editing a File</title>
 <prolog>
   <resourceid appname="ua" 
         appid="5432" ux-context-string="idh_fileedit" ux-windowref="csh" />
 </prolog>
 <taskbody>
  <context>After you have created a new file, you can edit it.</context> 
  <steps>
   <step><cmd>Open...</cmd></step>
   <step><cmd>Edit...</cmd></step>
   <step><cmd>Save...</cmd></step>
  </steps>
 </taskbody>
</task>
Example 3. Example: Using a <resourceid> element to XXX

In the following code sample, anchor components are defined for two different references to the same topic. Each use of the topic represents the documentation for a different model of the same base device.

<map>

  <!-- ... -->
  <keydef keys="topic-0014" href="replacing-widgetA.dita"/>
  <!-- ... -->

  <topicref keyscope="model-01">
    <!-- ... -->
    <topicref keys="replace-widgetA" keyref="topic-0014">
      <topicmeta>
        <resourceid appid="replace_widgetA_model_01" appid-role="deliverable-anchor"/>
      </topicmeta>
    </topicref>
    <!-- ... -->  
  </topicref>
  <topicref keyscope="model-02">
    <!-- ... -->
    <topicref keys="replace-widgetA" keyref="topic-0014">
      <topicmeta>
        <resourceid appid="replace_widgetA_model_02" appid-role="deliverable-anchor"/>
      </topicmeta>
    </topicref>
    <!-- ... -->
  </topicref>
  <!-- ... -->
</map>

The replacing-widgetA.dita topic is published twice, once in each scope. When the map is published, the following occurs:

  • An HTML deliverable might use the specified anchors to construct base file names for the resulting HTML. In this case, the copy in the first scope would use the name replace_widgetA_model_01.html, while the copy in the second scope uses the name replace_widgetA_model_02.
  • A PDF deliverable might simply add the application IDs as anchors for each instance of the topic, so that replace_widgetA_model_01 and replace_widgetA_model_02 would be available as anchors within the PDF.