Automatically show audience metadata in a published topic

[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

[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

[davenz]

Hi Alin,

That's brilliant, thanks so much. Exactly what I'm after and it work fine.

Cheers!
Dave

[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

[alin]

Hi Dave,

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

[davenz]

Hi Alin,

That's awesome—works great. Thanks again!

Cheers,
Dave

[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

[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