Edit online

How to Use XSLT Extension Points from a Publishing Template

This example demonstrates how to use WebHelp XSLT-import Extension Points from an Oxygen Publishing Template.

Use Case 1: Add Copyright Information Extracted from a DITA Bookmap

Suppose you want to customize the WebHelp Responsive main page by adding information about the legal rights associated with the book in the footer (for example, copyright dates and owner). This information is specified in the bookmap:
<bookrights>            
  <copyrfirst>
    <year>2002</year>
  </copyrfirst>
  <copyrlast>
    <year>2017</year>
  </copyrlast>
  <bookowner>
    <organization>SyncRO Soft SRL</organization>                
  </bookowner>
</bookrights>
Figure 1. Example: Copyright Information Added in the WebHelp Footer

The XSLT stylesheet that generates the main page is located in: DITA-OT-DIR\plugins\com.oxygenxml.webhelp.responsive\xsl\mainFiles\createMainPage.xsl. This XSLT stylesheet declares the copy_template mode that processes the main page template to expand its components. The main page template declares a component for the footer section that looks like this:

<div class=" footer-container text-center ">
  <whc:include_html href="${webhelp.fragment.footer}"/>
</div>

In the following example, the extension stylesheet will add a template that matches this component. It applies the default processing and adds the copyright information at the end.

<xsl:template match="*:div[contains(@class, 'footer-container')]" mode="copy_template">
  <!-- Apply the default processing -->
  <xsl:next-match/>
    
  <!-- Add a div containing the copyright information -->
  <div class="copyright_info">        
      <xsl:choose>
          <!-- Adds the start-end years if they are defined -->
          <xsl:when test="exists($toc/*:topicmeta/*:bookrights/*:copyrfirst) and 
                              exists($toc/*:topicmeta/*:bookrights/*:copyrlast)">
              <span class="copyright_years">
                 &#xa9;<xsl:value-of select="$toc/*:topicmeta/*:bookrights/*:copyrfirst"/>
                       -<xsl:value-of select="$toc/*:topicmeta/*:bookrights/*:copyrlast"/>
              </span>
          </xsl:when>
            
          <!-- Adds only the first year if last is not defined. -->
          <xsl:when test="exists($toc/*:topicmeta/*:bookrights/*:copyrfirst)">
              <span class="copyright_years">
                 &#xa9;<xsl:value-of select="$toc/*:topicmeta/*:bookrights/*:copyrfirst"/>
              </span>
          </xsl:when>
      </xsl:choose>
                    
        
      <xsl:if test="exists($toc/*:topicmeta/*:bookrights/*:bookowner/*:organization)">
          <span class="organization">
              <xsl:text> </xsl:text><xsl:value-of 
                   select="$toc/*:topicmeta/*:bookrights/*:bookowner/*:organization"/>
              <xsl:text>. All rights reserved.</xsl:text>
          </span>
      </xsl:if>
  </div>
</xsl:template>
To add this functionality using a Oxygen Publishing Template, follow these steps:
  1. If you have not already created a Publishing Template, see How to Create a Publishing Template.
  2. Link the folder associated with the publishing template to your current project in the Project Explorer view.

    Step Result: You should have the custom_footer_template folder linked in your project.

  3. Using the Project Explorer view, create an xslt folder inside the project root folder.

    Step Result: You should have the custom_footer_template/xsl folder in your project.

  4. Create your customization stylesheet (for example, custom_mainpage.xsl) in the custom_footer_template/xsl folder. Edit it to override the template that produces the footer section:
    <xsl:template match="*:div[contains(@class, 'footer-container')]" mode="copy_template">
  <!-- Apply the default processing -->
  <xsl:next-match/>

  <!-- Add a div containing the copyright information -->
  <div class="copyright_info">        
      <xsl:choose>
          <!-- Adds the start-end years if they are defined -->
          <xsl:when test="exists($toc/*:topicmeta/*:bookrights/*:copyrfirst) and 
                        exists($toc/*:topicmeta/*:bookrights/*:copyrlast)">
              <span class="copyright_years">
                 &#xa9;<xsl:value-of select="$toc/*:topicmeta/*:bookrights/*:copyrfirst"/>
                       -<xsl:value-of select="$toc/*:topicmeta/*:bookrights/*:copyrlast"/>
              </span>
          </xsl:when>
            
          <!-- Adds only the first year if last is not defined. -->
          <xsl:when test="exists($toc/*:topicmeta/*:bookrights/*:copyrfirst)">
              <span class="copyright_years">
                 &#xa9;<xsl:value-of select="$toc/*:topicmeta/*:bookrights/*:copyrfirst"/>
              </span>
          </xsl:when>
      </xsl:choose>
                    
        
      <xsl:if test="exists($toc/*:topicmeta/*:bookrights/*:bookowner/*:organization)">
          <span class="organization">
              <xsl:text> </xsl:text><xsl:value-of 
                   select="$toc/*:topicmeta/*:bookrights/*:bookowner/*:organization"/>
              <xsl:text>. All rights reserved.</xsl:text>
          </span>
      </xsl:if>
  </div>
</xsl:template>
  5. Open the template descriptor file associated with your publishing template and set the XSLT stylesheet created in the previous step with the com.oxygenxml.webhelp.xsl.createMainPage XSLT extension point.
    <publishing-template>
    ...
    <webhelp>
        ...        
        <xslt>
            <extension 
            file="xslt/customMainPage.xsl" 
            id="com.oxygenxml.webhelp.xsl.createMainPage"/>
  6. Open the DITA Map WebHelp Responsive transformation scenario.
  7. Click the Choose Custom Publishing Template link and select your template.
  8. Click OK to save the changes to the transformation scenario.
  9. Run the transformation scenario.

Use Case 2: Add Generation Time in the Output Footer

Another possible customization for the main page is to add the generation time in its footer. A transformation parameter is used to control whether or not this customization is active.

Figure 2. Generation Time Added in the WebHelp Footer
To add this functionality, follow these steps:
  1. In the customization stylesheet that you just created (for example, custom_mainpage.xsl), modify the template by adding the following XSLT code at the end.
    <xsl:if test="oxyf:getParameter('webhelp.footer.add.generation.time') = 'yes'">
  <div class="generation_time">
    Generation date: <xsl:value-of 
    select="format-dateTime(
                   current-dateTime(), 
                   '[h1]:[m01] [P] on [M01]/[D01]/[Y0001].')"/>
  </div>
</xsl:if>
    Note: You can read the value of a WebHelp transformation parameter from your XSLT extension stylesheets by using the getParameter(param.name) function from the http://www.oxygenxml.com/functions namespace.
  2. Open the template descriptor file associated with your publishing template and set the webhelp.footer.add.generation.time parameter to the default value.
    <publishing-template>
    ...    
    <webhelp>
      ...
      <parameters>
        <parameter 
          name="webhelp.footer.add.generation.time" 
          value="yes"/>
  3. Open the DITA Map WebHelp Responsive transformation scenario.
  4. In the Parameters tab, you can change the value of the webhelp.footer.add.generation.time parameter.
  5. Click OK to save the changes to the transformation scenario.
  6. Run the transformation scenario.