Passing product attribute value to webhelp topics

[kmank]

Hello, I have a need to pass the value of the product attribute from the DITA files to the resulting transformed webhelp topics.

For example, if an img like this:
<image placement="break" href="../images/Parties.png" id="image_ulm_3kb_lk" product="blue"/>

I need the resulting webhelp topic to transform like this:
<img class="image" id="image_ulm_3kb_lk" src="../images/Parties.png" prod="blue" height="308" width="600"/>

What would be the method for pushing this value? Thanks in advance!

[sorin_ristache]

Hi,

Do you want that only for the image element? Or maybe you want that more generally for the content of topics, more precisely to filter the content of a topic based on the value of the product attribute, and have several sets of output files based on different values of the product attribute (blue, red, yellow, etc)? I am asking this because product is a DITA profiling attribute, and maybe this is what you really want to obtain in the output.

If you want only to add the prod or product attribute in the output on the img element then you have to customize the XSLT stylesheet that creates the img element in the output, which is [Oxygen-install-dir]\frameworks\dita\DITA-OT\xsl\xslhtml\dita2htmlImpl.xsl, starting with line 1664:

Code: Select all

  <img>

    <xsl:call-template name="commonattributes">

      <xsl:with-param name="default-output-class">

        <xsl:if test="@placement='break'"><!--Align only works for break-->

         <xsl:choose>

      . . .

If you want to use the product attribute for DITA profiling, that is filtering the topic content based on the value of this attribute, then you should create a profiling condition set in Oxygen and use it for both editing the DITA topics in Author mode and transforming the map to Webhelp or other output formats.


Regards,
Sorin

[kmank]

Thanks Sorin. Let me iterate what is exactly needed.

We are passing a variable with our URLs (ex. index.html?prod=blue&role=admin). prod and role could have other values. These values are used by many different elements (img, para, etc).

I need to retain all product and audience attribute values during transformation so that when the user accesses the pages we can implement code to filter out (display:none) what is not equal to the variable passed.

I hope I have provided enough background.

Cheers!

[sorin_ristache]

Hi,

So you need a kind of profiling on the content. That is one way of implementing profiling in the output of a DITA transformation: include the entire content in the output of the transformation, and filter out the content that does not match the current profile (the current selection of the content that is set by the attributes prod=blue&role=admin) with CSS code that hides the content outside the current profile (the content that has other values for the prod and role attributes than blue and admin). That is your own original way of implementing DITA profiling. If you want to choose this way, please just go ahead. Just keep in mind that you have to customize the XSLT stylesheets used in the DITA transformation, as I said above, for each element that you want to profile (image, ul, ol, table, p, etc). You cannot avoid these customizations which you have to do yourself and which seem quite tedious.

There is another way of implementing DITA profiling which is widely used by DITA content authors, is recommended by the DITA specification and is well supported by the Oxygen application for both editing in Author mode and transforming to any output format (Webhelp, PDF, Eclipse Help, etc): create multiple sets of output files from the same source files (DITA map + topics), one output set for each profile, by applying the same DITA transformation on the same map once for each profile (and changing only the values of the profiling attributes between the DITA transformations), and display the appropriate set of output files to the current user (admin user of blue product, or novice user of green product, or expert user of yellow product, etc). The big advantages of this recommended approach to DITA profiling is that you have the same DITA source files as in the first approach and that the heavy-lifting is already done for you for both the authoring stage (in the Author editing mode) and the transformation stage, so you won't need to customize the XSLT stylesheets yourself.


Best regards,
Sorin

[kmank]

Sorin, thanks again for your reply. We are definitely aware of transforming the output in the usual recommended way. In fact that is how we have been supplying the webhelp to date.

However, we now have applications that are being combined and the end user has access to one or more multiple applications. The role value is designed to indicate which application the user is accessing documentation from. Because of this we are needing to have all webhelp manuals transformed as a single manual and then filter the contents based on the prod value.

One thing I have not considered would be the possibility of transforming the webhelp in separate manuals as we do now and using the URL variable to redirect to the desired manual.

Thank you for the dialogue and help in providing options!

[sorin_ristache]

OK, I understand. Thank you for letting us know.


Regards,
Sorin

[kmank]

So then I guess I should ask again, in case I missed it. How would I change the transformation to pass the desired attributes to the webhelp output?

[sorin_ristache]

Hi,

Do you mean URL parameters, like index.html?prod=blue&role=admin? This is very unusual for a DITA transformation because this is not the way to pass parameters in a DITA transformation. The Parameters tab of the DITA transformation dialog box should be used instead. These parameters are handled in the XSLT stylesheets from the DITA-OT directory.

If you need to pass them as URL parameters, as I understood from the above discussion, then I guess you will need to inject your own custom code in the index.html file for handling the URL parameters. The index.html file is created in the stylesheet [Oxygen-15-install-dir]\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\xsl\createMainFiles.xsl, in the template called "create-toc-common-file", when the "withFrames" parameter has the value false().


Regards,
Sorin

[kmank]

Sorry, I'll back up a bit - perhaps I confused the matter.

As stated, we need to provide a single manual in webhelp format that has multiple user guides within the single ditamap. Within the topics of the ditamap we have many different elements that have been marked up with product attributes (blue, red, etc) and audience attributes (user, admin, etc).

The application itself contains a link to the help documentation, including product and role variables to indicate which product the user came from as well as their role:

Code: Select all

http://<...>/index.html?app=blue&role=admin

Normally during transformation (as you well know), any profiling attributes are stripped out as they are no longer needed in the transformed webhelp - the content is already customized based on the transformation scenario.

However, due to the nature of needing to profile when the webhelp content is live, I need to have the product and audience attributes remain intact within the webhelp content.

I hope this makes more sense now, and apologize for any frustration.

[sorin_ristache]

Hi,

I suggest changing the content of the index.html file almost completely so that it can redirect to the proper pages when invoked with URL parameters of the form index.html?app=blue&role=admin. The index.html file created by the builtin Webhelp transformation ignores the URL parameters like app=blue&role=admin but you can generate an entirely different content in this file if you want, in order to handle the URL parameters by redirecting the browser to the appropriate pages when invoked with URL parameters. The index.html file is created in the XSLT template called create-toc-common-file in the following XSLT stylesheet file, when the withFrames parameter has the value false():

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

So you should just re-write the content of the following template in this XSLT file createMainFiles.xsl and make sure that your custom XSLT code within this template is executed only when the value of the withFrames parameter is false():

Code: Select all

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

Regards,
Sorin