WebHelp XSLT: Display metadata as visible content

Post by **Frank Ralf** » Wed Oct 10, 2018 5:15 pm

Hi,

I'm working on a WebHelp extension to display DITA metadata from the new Release Management domain as visible content. I've already had a look at DITA-OT\plugins\org.dita.xhtml\xsl\xslhtml\get-meta.xsl and managed to create templates for new metadata elements from the Release Management domain. However, the current processing flow seems to only create metadata elements in the <head> section of the generated XHTML. How can I create elements in the XHTML <body> instead? Any pointers welcome.

TIA
Frank

alin · Post by **alin** » Thu Oct 18, 2018 8:27 am

Hello,

I think that the Publishing Template's macros mechanism might help you. The macros are variables that you can use in the HTML Layout Files (https://www.oxygenxml.com/doc/versions/ ... aid-title4) or in the HTML Fragment Files (https://www.oxygenxml.com/doc/versions/ ... aid-title6). They will be expanded to their corresponding values in the WebHelp Responsive output files at generation time.
The available macros are described here: https://www.oxygenxml.com/doc/versions/ ... aid-title5

You can use the map-xpath or topic-xpath macros to extract metadata from the DITA Map or from the current topic and place it in the final HTML file.
You can have a look at the following Publishing Template Sample from our GitHub Repository: https://github.com/oxygenxml/oxygen-pub ... ith-macros
It uses the map-xpath macro to extract the Copyright metadata from a bookmap and inserts it in the footer section of each HTML output file (see https://github.com/oxygenxml/oxygen-pub ... footer.xml).

For example:

Code: Select all


 <div class="copyright_info">

        <span class="copyright_years">

            &#xa9;<whc:macro value="${map-xpath(/bookmap/bookmeta/bookrights/copyrfirst/year)}"/>-<whc:macro value="${map-xpath(/bookmap/bookmeta/bookrights/copyrlast/year)}"/>

        </span>

        <span class="organization">

            <whc:macro value="${map-xpath(/bookmap/bookmeta/bookrights/bookowner/organization)}"/>.

        </span>

        <span> All rights reserved.</span>

    </div>

Regards,
Alin

Post by **Frank Ralf** » Tue Oct 30, 2018 3:26 pm

Hi Alin,

Many thanks for this pointer. I wasn't aware of this mechanism. I will give it a try and report back.

Best regards,
Frank

Post by **Frank Ralf** » Tue Oct 30, 2018 8:00 pm

Hi Alin,

The macro mechanism helped indeed with another issue; thanks again.

What I want to do is creating release notes in WebHelp output, similar as https://github.com/doctales/org.doctales.release-notes does for PDF output. However, using the following XSLT variable on the top document level is easier with FO because there is an intermediate large XML file that contains the complete document content. I'm struggling with the problem to find the appropriate extension point for the WebHelp XSLT.

Any pointers welcome.

Best regards,
Frank

Code: Select all


 <!-- The variable change-items contains a list of all change-item elements. -->

    <xsl:variable

        name="change-items"

        select="//*[contains (@class, ' relmgmt-d/change-item ')] "

/>

Post by **Frank Ralf** » Thu May 16, 2019 2:40 pm

Hi,

We finally managed to extract version-related metadata from maps and topics by overriding com.oxygenxml.webhelp/xsl/macroExpander.xsl and defining the following variable:

Code: Select all

<xsl:variable name="ProductVersion">
    <xsl:choose>
      <xsl:when test="//topicmeta/metadata/prodinfo/vrmlist/vrm">
        <xsl:value-of select="
            //topicmeta/metadata/prodinfo/vrmlist/vrm/
            concat(@version, '.', @release, '.', @modification)" />
      </xsl:when>
      <xsl:when test="//prolog/metadata/prodinfo/vrmlist/vrm">
        <xsl:value-of select="
            //prolog/metadata/prodinfo/vrmlist/vrm/
            concat(@version, '.', @release, '.', @modification)" />
      </xsl:when>
    </xsl:choose>
  </xsl:variable>

In most cases this works as expected and we can use this variable to add revision information to the footer of each page of the WebHelp. However, we noticed a strange behavior with certain topics: The above variable isn't set when the topic doesn't contain a <metadata> element even if the version information is correctly pulled from the map for all other topics.

It looks like the behavior is related to the second expression which tests topic metadata:

Code: Select all

 <xsl:when test="//prolog/metadata/prodinfo/vrmlist/vrm">

If I deactivate this second expression in our macroExpander.xsl no version number from the map gets pulled. However, I cannot figure out why this happens and how to avoid it. So any pointers welcome.

Best regards,
Frank

raybiss · Post by **raybiss** » Sat Feb 01, 2020 5:37 am

Hi,

I'm also trying to access the release management domain metadata but I have not yet figured out how to override macroExpander.xsl.

I've been successful using a few macros in a template to get some metadata elements but it looks like overriding the macroExpander template is the only way to iterate over more elements.

https://www.oxygenxml.com/doc/versions/ ... tents.html
says "To add new macros, you can add an XSLT extension to overwrite the wh-macro-extension template from the com.oxygenxml.webhelp.responsive\xsl\template\macroExpander.xsl file."

Since https://www.oxygenxml.com/doc/versions/ ... mport.html
does not list such extension point, I guess I would need to create a plugin to do it.

Would you mind sharing how you you were able to override macroExpander.xsl?

TIA,
Raymond

alin · Post by **alin** » Mon Feb 03, 2020 5:27 pm

Hello,

raybiss wrote: ↑Sat Feb 01, 2020 5:37 am
https://www.oxygenxml.com/doc/versions/ ... tents.html
says "To add new macros, you can add an XSLT extension to overwrite the wh-macro-extension template from the com.oxygenxml.webhelp.responsive\xsl\template\macroExpander.xsl file."

The above statement refers to the fact that you have the possibility to add (implement) a custom named macro besides the ones already available (listed here: https://www.oxygenxml.com/doc/versions/ ... 2b__d75e47).

For example, the implementation for a macro named my-macro can look as follows (note that this is a dummy implementation for demo purposes):

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    exclude-result-prefixes="xs"
    version="2.0">
    
    <xsl:template name="wh-macro-extension">
        <xsl:param name="name"/>
        <xsl:param name="params"/>
        <xsl:param name="contextNode"/>
        <xsl:param name="matchedString"/>
        
        <xsl:choose>
            <xsl:when test="$name eq 'my-macro'">
                <p>This is an implementation for the <pre><xsl:value-of select="$name"/></pre> macro called with 
                <xsl:choose>
                    <!-- As the docs say, the $params sequence can contain maximum one parameter -->
                    <xsl:when test="count($params) > 0"> the following parameters:  <pre><xsl:value-of select="string-join($params, ',')"/></pre></xsl:when>
                    <xsl:otherwise> no parameters.</xsl:otherwise>
                </xsl:choose>
                </p>
            </xsl:when>
        </xsl:choose>
    </xsl:template>
</xsl:stylesheet>

raybiss wrote: ↑Sat Feb 01, 2020 5:37 am Since https://www.oxygenxml.com/doc/versions/ ... mport.html
does not list such extension point, I guess I would need to create a plugin to do it.

No, you do not have to create a new plugin. You can use the XSLT Extension support from the Publishing Template (https://www.oxygenxml.com/doc/versions/ ... ing_templa).
Depending on which page you want your macro implementation to be available in, you have to use the following extension points:

com.oxygenxml.webhelp.xsl.createMainPage - for the Main page (index.html)
com.oxygenxml.webhelp.xsl.dita2webhelp - for the pages generated from the DITA topics
com.oxygenxml.webhelp.xsl.createSearchPage - for the Search Results page
com.oxygenxml.webhelp.xsl.createIndexTermsPage - for the Index Terms page

Assuming that you want your macro to be available in all pages and you have saved the above XSLT content in a file named macro-implemetation.xsl located in the root directory of your Publishing Template (next to your template descriptor (OPT) file), you should add the following lines in your template descriptor:

Code: Select all

      <xslt>
            <extension file="macro-implemetation.xsl" id="com.oxygenxml.webhelp.xsl.createMainPage"/>
            <extension file="macro-implemetation.xsl" id="com.oxygenxml.webhelp.xsl.dita2webhelp"/>
            <extension file="macro-implemetation.xsl" id="com.oxygenxml.webhelp.xsl.createSearchPage"/>
            <extension file="macro-implemetation.xsl" id="com.oxygenxml.webhelp.xsl.createIndexTermsPage"/>
        </xslt>

As you can see I have linked my XSLT extension file to the XSLT extension points associated with each page type.

Next, you can use your custom my-macro macro in an HTML Fragment file as follows
(https://www.oxygenxml.com/doc/versions/ ... aid-title6):

Code: Select all

<div class="footer" xmlns:whc="http://www.oxygenxml.com/webhelp/components">
    <whc:macro value="${my-macro(my-macro-param)}"/>
</div>

In order to include the above content in the footer section of each page you can add the following lines in your Publishing Template descriptor file:

Code: Select all

        <html-fragments>
            <fragment file="footer-fragment.xml" placeholder="webhelp.fragment.footer"/>
        </html-fragments>

Again, I assumed that the HTML Fragment file is named footer-fragment.xml and it is located in your template's root directory.
The footer section will look as follows:

The Publishing Template containing the above resources can be found here: http://www.oxygenxml.com/forum/files/custom-macro.zip

Regards,
Alin

Post by **Frank Ralf** » Thu Feb 13, 2020 6:11 pm

Hi Alin,

Many thanks for this extensive explanation and the example!

Best regards,
Frank

WebHelp XSLT: Display metadata as visible content

WebHelp XSLT: Display metadata as visible content

Re: WebHelp XSLT: Display metadata as visible content

Re: WebHelp XSLT: Display metadata as visible content

Re: WebHelp XSLT: Display metadata as visible content

Re: WebHelp XSLT: Overriding "macroExpander.xsl"

Re: WebHelp XSLT: Display metadata as visible content

Re: WebHelp XSLT: Display metadata as visible content

Re: WebHelp XSLT: Display metadata as visible content