WebHelp Responsive macros

You can use the whc:macro layout component to specify a macro value (a variable that will be expanded when the output files are generated).

A macro has the following syntax:

${macro-name}

${macro-name(macro-parameter)}

A macro name can accept any alphanumeric characters, as well as the following characters: - (minus), _ (underscore), . (dot), : (colon). The value of a parameter may contain any character except the } (close curly bracket) character.

Implementations

The following macros are supported:

i18n

For localizing a string.

${i18n(string.id)}

param

Returns the value of a transformation parameter.

${param(webhelp.show.main.page.tiles)}

env

Returns the value of an environment variable.

${env(JAVA_HOME)}

system-property

Returns the value of a system property.

${system-property(os.name)}

timestamp

Can be used to format the current date and time. Accepts a string (as a parameter) that determines how the date and time will be formatted (format string or picture string as it is known in the XSLT specification). The format string must comply with the rules of the XSLT format-dateTime function specification.

${timestamp([h1]:[m01] [P] [M01]/[D01]/[Y0001])}

path

Returns the path associated with the specified path ID. The following paths IDs are supported:

oxygen-webhelp-output-dir - The path to the output directory. The path is relative to the current HTML file.
oxygen-webhelp-assets-dir - The path to the oxygen-webhelp subdirectory from the output directory. The path is relative to the current HTML file.
oxygen-webhelp-template-dir - The path to the template directory. The path is relative to the current HTML file.
```
${path(oxygen-webhelp-template-dir)} 
```

Note: New paths IDs can be added by overriding the wh-macro-custom-path template from com.oxygenxml.webhelp.responsive\xsl\template\macroExpander.xsl:

<!-- Extension template for expanding a custom path macro. -->
										<xsl:template name="wh-macro-custom-path">
										<xsl:param name="pathId"/>
										<xsl:value-of select="$pathId"/>
										</xsl:template>

map-xpath

Can be used to execute an XPath expression over the DITA map file from the temporary directory.

Tip: Available in all template layout HTML pages.

${map-xpath(/map/title)}

map-xpath

Can be used to execute an XPath expression over the current topic.

Tip: Available only in the topic HTML page template (wt_topic.html).

${topic-xpath(string-join(//shortdesc//text(), ' '))}

oxygen-webhelp-build-number

Returns the current WebHelp distribution ID (build number).

${oxygen-webhelp-build-number}

Extensibility

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.

<!-- Extension template for expanding custom macro constructs -->
<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="$contextNode instance of attribute()">
            <xsl:value-of select="$matchedString"/>
        </xsl:when>
        <xsl:otherwise>
            <xsl:message>Cannot expand macro: 
                [<xsl:value-of select="$matchedString"/>]</xsl:message>
            <xsl:copy-of select="$contextNode"/>
        </xsl:otherwise>
    </xsl:choose>
</xsl:template>

The wh-macro-extension template has the following parameters:

name - The name of the current macro.
params - List of parameters of the current macro as string sequence. The current macros parsing mechanism only allows macros with a maximum of one parameter. Consequently, this list will contain at most one element.
contextNode - The current element or attribute where the macro was declared.
matchedString - The entire value of the matched macro as specified in the HTML template page.