Additional page layout templates?

[dbarr]

Is it possible to define additional html layout templates for Webhelp Responsive output?
My company relies on a customization of your Webhelp Responsive framework to publish static HTML documentation for our products.
Our technical writers often deal with fairly granular content collections, which can result in overwhelming navigational experiences.

We have received a request for a 2-tier navigation setup combining both the tile and table of content formats of the index page (configured by the webhelp.show.main.page.tiles and webhelp.show.main.page.toc parameters). The user flow would be:
- The index.html page of the collection presents a tile-based layout showing the L1 nodes in their ditamap
- After clicking on a tile, a chapter_index.html page shows a TOC-based layout showing the children of the L1 node that has been clicked
- Clicking on an individual topic would bring our current topic layout, with document and page side-TOCs.

This would seem to require defining an additional html layout template (chapter_index) — is that supported by your Webhelp Responsive framework?
If so, do you have any resources that we could use? Your documentation has been extremely useful in our efforts to customize the framework, but I couldn’t find any information about additional page layout templates. Thank you!

[dbarr]

Update: We have identified that the

Code: Select all

page-layout-file

element is defined in the file

Code: Select all

publishing-template-descriptor.xsd

file within the

Code: Select all

com.oxygenxml.common/lib/oxygen-publishing-template.jar

library.

Could you please confirm if the only way to enable additional page layouts involves customizing/overriding your com.oxygenxml.common plugin?
Alternatively, what other mechanisms we could leverage to produce an additional "chapter-index" page?

[alin]

Hello,

Unfortunately, we do not have a procedure that would enable you to create an additional HTML Page Layout file.

However, the WebHelp Responsive output contains a component named Child Links, which lists the links to the child topics of the current topic. For each child topic its short description (if it exists) will also be displayed.
You must set the webhelp.show.child.links transformation parameter to yes in order to have the Child Links component generated in the topic pages.

Next, you can create a set of custom CSS rules to display the links to sub topics as tiles. You can use the following Publishing Template as a starting point: https://github.com/oxygenxml/oxygen-publishing-template-samples/tree/master/templates/topic-with-tiles.



Regards,
Alin

[dbarr]

Thank you for your reply, Alin
I think I can see how the customization of topic pages you proposed could result in a similar flow as I described above by doing some adjustments to the structure of our maps. Unfortunately we have a requirement that this "two-tier" index navigation should be available without making modifications to map structure.
I have noticed that it is possible to render both tiles and tree TOCs in the index page, and I am testing a small javascript module that would manipulate the page DOM to show either Tiles or Tree sub-sections. This has trggered another question:

The webhelp_main_page_toc component of the main/index page only shows the top two navigation levels.
We would be interested in this tree behaving similarly to the webhelp_publication_toc component of the topic page.

Is there a way either to reconfigure the webhelp_main_page_toc component, or to add the webhelp_publication_toc to the main page?

If we add the webhelp_publication_toc element to our main page template, it seems to be ignored during publishing.

Best,
Daniel

[alin]

Hello,

If we add the webhelp_publication_toc element to our main page template, it seems to be ignored during publishing.

The webhelp_publication_toc element is ignored when included in the HTML Page Layout file for the main page. The stylesheet that processes this component is not applied over this layout file. It is only applied over the layout file used to generate the topic pages.


The structure of the webhelp_publication_toc component is generated by processing the content of the {WH_TEMP_DIR}/toc.xml file.
You can access to the content of this file by referencing the $toc XSL variable in a XSLT extension file registered on the com.oxygenxml.webhelp.xsl.createMainPage extension point.
This means you need to have the following declaration in your Publishing Template's descriptor file:

Code: Select all

        <xslt>
            <extension file="xsl/publication-toc-in-main-page.xsl" id="com.oxygenxml.webhelp.xsl.createMainPage"/>
        </xslt>

For example, the {PT-ROOT_DIR}/xsl/publication-toc-in-main-page.xsl file could contain the following templates to insert the TOC in the content area section of the main page:

Code: Select all

 <xsl:template match="*:div[contains(@class, 'wh_content_flex_container')]" mode="copy_template">
        <xsl:call-template name="generatePublicationTocComponent"/>
        <xsl:next-match/>
    </xsl:template>

(*) {PT-ROOT_DIR} = Publishing Template Root Directory


In addition to this you can use the following XSL templates to generate the structure of the TOC:

Code: Select all

    <xsl:template name="generatePublicationTocComponent">
        <nav id="wh_publication_toc" 
            aria-label="Table of Contents Container">
            <div id="wh_publication_toc_content">
                <div class=" wh_publication_toc ">
                    <xsl:apply-templates select="$toc" mode="create-toc"/>
                </div>
            </div>
        </nav>
    </xsl:template>
    
    <xsl:template match="toc:topic" mode="create-toc">
        <xsl:call-template name="generateTocEntry"/>
        <xsl:apply-templates select="toc:topic" mode="create-toc"/>
    </xsl:template>
    <xsl:template name="generateTocEntry">
        <li>
            <div data-tocid="{@wh-toc-id}">
                <xsl:attribute name="class">
                    <xsl:value-of select="'topicref'"/>
                    <xsl:if test="@outputclass">
                        <xsl:value-of select="concat(' ', @outputclass)"/>
                    </xsl:if>
                </xsl:attribute>
                <!-- WH-1820 Copy the Ditaval "pass through" attributes. -->
                <xsl:copy-of select="@*[starts-with(local-name(), 'data-')]"/>
                <xsl:variable name="hrefValue">
                    <xsl:call-template name="computeHrefAttr"/>
                </xsl:variable>
                <div class="title">
                    <a href="{$hrefValue}" id="{@wh-toc-id}-link">
                        <xsl:if test="@scope = 'external'">
                            <!-- Mark the current link as being external to the DITA map. -->
                            <xsl:attribute name="data-scope">external</xsl:attribute>
                        </xsl:if>
                        <xsl:copy-of select="toc:title/node()"/>
                    </a>
                    <xsl:apply-templates select="toc:shortdesc" mode="topic2html"/>
                </div>
            </div>
        </li>
    </xsl:template>
    
    
    <xsl:variable name="VOID_HREF" select="'javascript:void(0)'"/>
    <!-- Compute the href attribute to be used when compute link to topic  -->
    <xsl:template name="computeHrefAttr">
        <xsl:choose>
            <xsl:when test="@href and @href != $VOID_HREF">
                <xsl:value-of select="@href"/>
            </xsl:when>
            <xsl:otherwise>
                <!-- Select the href of the first descendant topic ref -->
                <xsl:value-of select="descendant::toc:topic[@href and @href != $VOID_HREF][1]/@href"/>
            </xsl:otherwise>
        </xsl:choose>
    </xsl:template>
    

NOTE: The above code only generates the structure of the TOC and inserts it in the main page. You will have to contribute your own JS that would implement the expand/collapse functionality of the TOC entries.

Regards,
Alin

[dbarr]

Thank you so much for the detailed explanation, Alin.
I will follow your hints and report back.

By the way, it was really nice to see you and the rest of the oXygen team during XML Prague!