Webhelp - Add extra text to title

[uprichard]

How can I add extra text to the top header area of Webhelp? I want to add 2 other values that come from the ditamap data values and 1 item that comes from the ANT build script.

With the PDF transformation I used the customization directory to apply the changes to xsl files etc, does Webhelp have anything like that? I don't want to have to change the files in the actual Oxygen Framework

I know I can use a different css to change some items, but how can I get other values in the header.

[sorin_ristache]

Hello,

Unfortunately the DITA Webhelp transformation cannot be customized or extended yet in the same way as the PDF one, by grouping the customizations in a different directory that is set as parameter in the DITA transformation.

The top header area is displayed by the Webhelp output file index.html which is generated by the ANT task called "create-main-files" in the ANT file [Oxygen-install-dir]\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\build_dita.xml.

If the custom values come from the DITA map and from the ANT build file you have to customize the XSLT stylesheets because that is the place where the DITA map values can be most conveniently fetched and processed by the transformation. The values that come from the ANT build file should be passed to the XSLT stylesheet as parameters in the ANT task "create-main-files". That means the stylesheet you have to customize is:

[Oxygen-install-dir]\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\xsl\createMainFiles.xsl

You should customize the XSLT template called "create-toc-common-file" and check in this template if the value of the withFrames parameter is false(). When the value of the withFrames parameter is true() the file that is generated is called index_frames.html and is the version of the Webhelp with frameset.

For extracting the values from the DITA map you should pass to this stylesheet createMainFiles.xsl an XSLT parameter with the value of the file path of the map file, which is ${dita.temp.dir}/${user.input.file}, for example:

Code: Select all

  <param name="INPUT_MAP" expression="${dita.temp.dir}/${user.input.file}"/>

Regards,
Sorin

[uprichard]

I don't exactly understand.

I cannot point to any ditamap, I need to use values from the processed ditamap as the values are dependent on the ditval rules applied to the ditamap. For example, in the ditamap I have a "document" data value that changes depending on the "audience" tag value that is used in the ditval file., I need to show that value in the header / title of the Webhelp output

[sorin_ristache]

The file path that I showed above ${dita.temp.dir}/${user.input.file} is exactly what you need because it is the processed DITA map, after applying the DITAVAL rules, after expanding any references to sub-maps, etc. The temporary map ${dita.temp.dir}/${user.input.file} has all the content that will go in the Content tree, which is the Table of Contents of the Webhelp.

If you want to extract values from this temporary map you just need to locate the XML element elements and attributes that you want using an XPath expression. The XSLT template that I mentioned above (called "create-toc-common-file") is the place where you should do this extraction, because that is the template that creates the main header area of the index.html output file.


Regards,
Sorin

[uprichard]

Sorry, still cannot get it to work. Would it be possible to send me a copy of the files that you mention with changes that would get a data value from the ditamap and use that for the title displayed at the top of the webhelp page?

[sorin_ristache]

Hi,

Please note that this customization requires some XSLT stylesheet development skills and also some familiarity with the ANT build tool.

Please open for editing the XSLT stylesheet that I mentioned and that needs to be customized for modifying the text displayed in the main header area (the title area), which is:

[Oxygen-15.0-install-dir]\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\xsl\createMainFiles.xsl

You just need to modify the template called "create-toc-common-file", which in Oxygen 15.0 starts at line 189, as in the following:

Code: Select all

<xsl:template name="create-toc-common-file">

    <xsl:param name="toc"/>

    <xsl:param name="title" as="node()"/>

    <xsl:param name="fileName"/>

    <!-- toc.xml pt frame-uri, index.html pentru no frames.-->

    <xsl:param name="withFrames" as="xs:boolean"/>

    <!--true pentru frame-uri, false pentru no frames. -->

    

    <xsl:variable name="skinName" select="oxygen:getSkinName($withFrames)"/>

    

    <xsl:result-document href="{$fileName}" method="xhtml" indent="no" encoding="UTF-8"

       . . .

For example if you want to read from the DITA map and add in the main header area of the index.html output file the content of the element map/topicmeta/prodinfo/prodname (which usually holds the product name) and the content of the attribute map/topicmeta/prodinfo/vrmlist/vrm/@version (which holds the product version), the template should extract these values from the map using XPath expressions, for example adding the following in the template called "create-toc-common-file":

Code: Select all

    <html xmlns="http://www.w3.org/1999/xhtml">

        <head>

          <xsl:if test="$withFrames">

            <base target="contentwin"/>

          </xsl:if>

          <title>

            <xsl:value-of select="document($INPUT_MAP)/map/topicmeta/prodinfo/prodname"/>

            <xsl:text>  </xsl:text>

            <xsl:value-of select="document($INPUT_MAP)/map/topicmeta/prodinfo/vrmlist/vrm/@version"/>

          </title>

Also you have to add the following INPUT_MAP parameter at line 203 in the ANT file [Oxygen-15.0-install-dir]\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\build_dita.xml:

Code: Select all

<param name="INPUT_MAP" expression="${dita.temp.dir}/${user.input.file}"/>

These are all the modifications you need to apply for this example, which extracts the product name and product version from the DITA map and adds them in the main header area of the Webhelp output.


Regards,
Sorin

[uprichard]

Still cannot get it to work

Line 203 does not look correct for

Code: Select all

<param name="INPUT_MAP" expression="${dita.temp.dir}/${user.input.file}"/>

So I tried putting it at line 183, but I get the following error:

Code: Select all

    [xslt] C:\Program Files\Oxygen XML Editor 15\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\xsl\createMainFiles.xsl:228:90: Fatal Error! Variable INPUT_MAP has not been declared (or its declaration is not in scope)

     [xslt] C:\Program Files\Oxygen XML Editor 15\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\xsl\createMainFiles.xsl:230:102: Fatal Error! Variable INPUT_MAP has not been declared (or its declaration is not in scope)

     [xslt] Failed to process C:\svn-docs\DITA\DITA_SOURCE\branches\3.3\out\webhelp\toc.xml

I am using XML Author 15.1, build 2013100313

[uprichard]

I have it building now and I can pass though params (not ditamap values) to the XSL from the xml to add to the title.

But I am still having issues pulling a value from the ditamap. I have an entry like the following that I want to get the value from the version. What should the select be for the xsl:value-of

Code: Select all

<?xml version="1.0" encoding="utf-8" ......... xtrf="c:\DITA\prod.ditamap">

    <data class="- topic/data " name="version" value="0.8.0" xtrc="data:1;4:41" xtrf="C:\DITA\prod.ditamap"/>

    <data class="- topic/data " name="platform" platform="win" value="Windows 2008 R2, 7, 8, 2012" xtrc="data:2;5:79" xtrf="C:\DITA\prod.ditamap"/>

</map>

Thanks for your help

[sorin_ristache]

Hello,

Please locate the template that you need to edit:

Code: Select all

<xsl:template name="create-toc-common-file">

in the file *[Oxygen-install-dir]\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\xsl\createMainFiles.xsl*, and in this file please locate the following code fragment:

Code: Select all

          <div id="header">

            <div id="lHeader">

              <xsl:if test="not($withFrames)">

                <div id="productTitle">

                  <h1>

                    <xsl:copy-of select="$title"/>

For example for adding to the title the version value and the platform name, you can add the following just after the code that I copy-and-pasted above:

Code: Select all

                      <xsl:text>  version: </xsl:text>

                      <xsl:value-of select="document($INPUT_MAP)/map/data[@name = 'version']/@value"/>

                      <xsl:text>  platform: </xsl:text>

                      <xsl:value-of select="document($INPUT_MAP)/map/data[@name = 'platform']/@platform"/>

Also you have to add the following line in the file [Oxygen-install-dir]\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\build_dita.xml inside the element <xslt processor="trax" in="${output.dir}/toc.xml" out="${output.dir}/dummy.html" style="${args.create.main.files.xsl}" force="yes" classpathref="dost.class.path">(there are other <param> elements there already, as an example):

Code: Select all

<param name="INPUT_MAP" expression="${input.map.url}"/>

and add the following line just before this <xslt processor="trax"> element in the same file build_dita.xml:

Code: Select all

<makeurl file="${dita.temp.dir}/${user.input.file}" property="input.map.url"/>

Regards,
Sorin

[RichH]

Hi,
has there been any update to this since 2013? Is it possible to customize the Webhelp title with the product & version number from a Ditamap without having to modify the code as described above?

Thanks
Rich

[bogdan_cercelaru]

Hello,

No, it is not possible to easily add the product & version number from a DITA Map to the WebHelp title.
You still need to modify the code as described above to add those information to the WebHelp output.
I've logged this request to our issue tracking system to be analyzed.

Regards,
Bogdan

[ckabstein]

Hi,

Since the introduction of responsive Webhelp I assume that there must have been a change now. I'm struggling to get vrm and prodinfo into the Webhelp, and I've tried out the way it is described in this thread, but I'm getting errors all the time. In the PDF, it works like a charm, because you find a lot of information about how things are done. I'm very thankful that SyncRO Soft is doing a LOT to help us users, and they are worth every cent we are spending, but it seems that documentation of the customization of Webhelp is somewhat neglected in the DITA world, or let's say, it seems to be written only for the XSL experts. But more and more companies turn towards the web, which is some kind of a dilemma.

I'm definitely not an expert in XSL, I know. I have already learned a lot, but it's impossible for me due to the complicated DITA OT structure, which is hard for XSL beginners, to identify where to make the changes.

If somebody could help me, I would be extremely grateful.

Thanks,
Christina

[ionela]

Hi Christina,

Unfortunately, this feature is not implemented in oXygen XML WebHelp Responsive either.
Our issue tracking system contains an improvement request to make this feature available for WebHelp Responsive. I have added your vote to this issue, but I would appreciate if you could tell us how do you see this functionality being implemented.

Regards,
Ionela

[ckabstein]

Hi Ionela,

Thank you for adding my vote to this feature request.

Even though it would be great if I could learn how to adjust the DITA OT re. the webhelp myself, I think this would be a great feature for the responsive webhelp transformation provided by oXygen.

What we need is something like the following added at a specified location on the webhelp pages: <prodname>_<vrm>-info (version, release, modification values)_xml:lang_<revised>-info (golive value), i. e. oXygen_19.0.1_en-US_2017-08-15.
One of the ideas that I have for this would be to repeat this information on every page in the webhelp, because if the user searches for help using a search engine, the user should see right away for which version a feature was implemented, for example. However, it might also be sufficient for some users to insert this information only on the webhelp start page.

Thanks,
Christina

[Radu]

Hi,

Linking here for completion to the similar discussion Christina started on the DITA Users List:

https://groups.yahoo.com/neo/groups/dit ... ages/42559

Regards,
Radu