Page 1 of 1
Automatically show audience metadata in a published topic
Posted: Wed Aug 18, 2021 6:17 am
by davenz
Hi all,
I'm using Oxygen XML 22.1 and WebHelp output. Some of my topics are for administrators only. I want to automatically put a suitable note in each published item of applicable documentation--something like "Audience: Administrators only".
I figure there is a way to extract the value of the audience metadata from a topic's prolog element and combine it with CSS to get what I want. Is this possible and if so, any pointers about where to start?
Thanks,
Dave
Re: Automatically show audience metadata in a published topic
Posted: Wed Aug 18, 2021 3:10 pm
by alin
Hello,
WebHelp Responsive allows you to
insert custom HTML fragments in the output HTML pages.
Such an HTML fragment can use special
Macros that allow you to execute XPath expressions on the input DITA documents (map or topics).
For example:
Considering the following
prolog content available in a DITA topic:
Code: Select all
<prolog>
<metadata>
<audience audience="administrator"/>
</metadata>
</prolog>
You can use the following HTML Fragment:
Code: Select all
<div class="audience ${topic-xpath(/topic/prolog/metadata/audience[1]/@audience)}"/>
You can associate the above fragment with the
webhelp.fragment.before.body placeholder
Then the HTML output file will contain the following
div element as the first child of the
body element:
Code: Select all
<div class="audience administrator"></div>
You can
contribute a custom CSS file that styles the HTML page content based on the above
div.
This way you can display the
Audience: Administrators only static content below the topic title:
Code: Select all
.audience.administrator ~ #wh_topic_container .topictitle1::after{
display: block;
content: "Audience: Administrators only";
font-size: .4em;
font-style: italic;
}
For the complete example please see the sample Publishing Template available here:
https://github.com/oxygenxml/oxygen-pub ... ta-in-body
Regards,
Alin
Re: Automatically show audience metadata in a published topic
Posted: Mon Aug 23, 2021 2:14 am
by davenz
Hi Alin,
That's brilliant, thanks so much. Exactly what I'm after and it work fine.
Cheers!
Dave
Re: Automatically show audience metadata in a published topic
Posted: Mon Aug 23, 2021 4:35 pm
by davenz
Hi Alin,
One other question--can I show the same metadata content in a concept? I've tried and I can't get this to work for concepts. The fragment I'm using:
Code: Select all
<div class="audience ${topic-xpath(/concept/prolog/metadata/audience[1]/@type)}"/>
The @type attribute of the concept's audience metadata is set correctly. A <div> element for the metadata is inserted into the WebHelp output but it doesn't contain the value set for @type. So it looks like my XPath macro fails to get the metadata or is incorrect.
Do you have any suggestions please? Thanks!
Dave
Re: Automatically show audience metadata in a published topic
Posted: Tue Aug 24, 2021 11:04 pm
by alin
Hi Dave,
davenz wrote: ↑Mon Aug 23, 2021 4:35 pm
One other question--can I show the same metadata content in a concept? I've tried and I can't get this to work for concepts. The fragment I'm using:
Code: Select all
<div class="audience ${topic-xpath(/concept/prolog/metadata/audience[1]/@type)}"/>
Yes you can show the same metadata in concept topics. I have tested the above fragment using <oXygen/> WebHelp Responsive 23.1 and it worked on my side.
Below you can find:
- The DITA input and the HTML fragment:

- The resulted WebHelp Responsive output:

If you want your XPath expression to match any topic type (e.g.: topic, task, concept, etc.) you can adjust it as follows:
Code: Select all
/*/prolog/metadata/audience[1]/@type
Regards,
Alin
Re: Automatically show audience metadata in a published topic
Posted: Mon Sep 06, 2021 2:36 am
by davenz
Hi Alin,
That's awesome—works great. Thanks again!
Cheers,
Dave
Re: Automatically show audience metadata in a published topic
Posted: Wed Nov 02, 2022 11:09 am
by davenz
Hi Alin,
A follow-up since last posting this. One topic could have more than one audience element when the content is applicable to more than one audience. For example, administrators and staff could be the audiences for one topic:
Code: Select all
<prolog>
<metadata>
<audience type="administrator"/>
<audience type="staff"/>
</metadata>
</prolog>
In this example, do you have a recommended method please for how to show both labels in the published output of the one document?
And a related question (appreciating that this is a forum for Oxygen XML Editor). We use DITA-OT to also publish HTML5 output in parallel to different systems (Oxygen WebHelp is what we use for a staff intranet). Do you have a suggested starting point for showing the same audience labels in HTML5 output using DITA-OT?
Grateful for any information -- thanks!
Dave
Re: Automatically show audience metadata in a published topic
Posted: Mon Nov 21, 2022 1:57 pm
by alin
Hi Dave,
One topic could have more than one audience element when the content is applicable to more than one audience.
I have adjusted the initial template to handle multiple audience values. You can find it here:
https://github.com/oxygenxml/oxygen-pub ... ta-in-body
Do you have a suggested starting point for showing the same audience labels in HTML5 output using DITA-OT?
Such a customization for the HTML5 output might require a custom DITA-OT extension plugin. You can find more details about how to customize the DITA-OT's generated output in their documentation:
https://www.dita-ot.org/dev/topics/custom-plugins.html
Regards,
Alin