<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
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.
<resourceid>
element
in a map to generate hooks for online helpIn 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>
<resourceid>
element
in a topic to generate hooks for online helpIn 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>
<resourceid>
element
to XXXIn 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
andreplace_widgetA_model_02
would be available as anchors within the PDF.