Can I customize the WebHelp "Main Page" to point to a DITA topic?

[chrispitude]

Per the WebHelp documentation at

Layout of the Responsive Page Types

there are four WebHelp page types:

• Main page
• Topic page
• Search page
• Index terms page

Is it possible to completely replace the main page from the WebHelp output with a topic that goes directly to a specific topic page in the content navigation hierarchy?

My team is asking because product groups would like to provide their own landing page (as the first map topic) that has a structure not based on the first-level navigation hierarchy. This landing page would provide common usage-oriented links into the documentation, support and marketing links, while the left-side TOC would provide content-oriented access to the documentation:

image.png (67.55 KiB) Viewed 518 times

The concern is that if there is also a tiles/tree main page, then

• We would essentially have two landing pages.
• The default user experience would be controlled by level 1 headings instead of by the product group.
• The home button at the top would not go to the product group's landing page.
• The customer would only see the product group's landing page when that particular link is created from the main page.

Testcase (publish the "project.xml" file):

webhelp_no_main_page_question.zip

(8.74 KiB) Downloaded 13 times

[radu_pisoi]

Hi,
We don't have a standard procedure for this use case that allow you to skip or replace the generation of the main page.

The main page, index.html, is generated from the whr-create-main-page processing step by applying an XSLT transformation. So, based on this fact I think there are two solutions:

1. Skip main page generation
Override the whr-create-main-page ANT step from a custom WebHelp plugin and do nothing to skip the main page generation. Also, you can create a DITA topic on the first level of your publication with name index.dita. This will produce a index.html file in the output directory root.

2. Replace the main page generation
Override the whr-create-main-page ANT step from a custom WebHelp plugin and generate the main page in other form. You can do this by applying a custom XSLT transformation for instance.

[chrispitude]

Hi Radu,

Approach #1 sounds interesting! And indeed, the goal is to generate the main page from a DITA topic, using the approach described here. This allows my writers to work with their product groups to create landing pages in a format they are familiar with.

Unfortunately I cannot place the "index.html" file in the map root directory. Our file structure looks like this:

Code: Select all

dita/
  _warehouse/
  book1/
  book2/
  book3/
  olh1/
    index.dita
  olh2/
    index.dita
  olh3/
    index.dita
  book1.ditamap
  book2.ditamap
  book3.ditamap
  olh1.ditamap
  olh2.ditamap
  olh13ditamap

All our *.ditamap files are in the dita/ directory. Each .ditamap file has a same-named directory that contains its content. We have a good amount of content reuse across books, and changing this structure now would be nearly impossible.

I will look into using a DITA-OT rewrite rule to move "*/index.dita" back to "index.dita" and see if that works, then follow up here.

[chrispitude]

Hi Radu,

Rewrite rules show some promise! I am able to rename my <MAPDIR>/landing_page.dita file upward to an index.dita in the root directory:

Code: Select all

<!-- rename */topic.dita to topic_renamed.dita -->
<xsl:template match="file[@format = 'dita']/@result[ends-with(., 'landing_page.dita')]">
  <xsl:attribute name="{local-name()}" select="'index.dita'"/>
</xsl:template>

Unfortunately, the WebHelp-specific content does not reflect the write-rule change. Here's a testcase:

webhelp_topic_main_page_rewrite.zip

(49.11 KiB) Downloaded 10 times

If you publish "project.xml", then run this command:

Code: Select all

diff out/landing_page.html out/landing_page_renamed.html

you will see that the @href references in the top menu, publication TOC, WebHelp CSS files, and various other places are not adjusted. But the DITA topic content itself is adjusted.

Using ditaot_save_preprocessing.pl, I saved the .dita files from the end of preprocess, and they are constructed correctly:

webhelp_topic_main_page_temp_files.zip

(35.67 KiB) Downloaded 9 times

So somehow WebHelp is processing the files as if they were in their original locations, not as they are actually constructed in the temporary directory.

It would be extremely useful if WebHelp would work with rewrite rules. Not only would it solve the landing page problem elegantly, but we could also use it to rename our DITA "_warehouse/" directory to something more customer-friendly in topic URLs:

Code: Select all

<xsl:template match="file/@result[contains(., '/_warehouse/')]">
  <xsl:attribute name="{local-name()}" select="replace(., '/_warehouse/', '/common/')"/>
</xsl:template>

Could you please file an enhancement to support DITA-OT rewrite rules in a WebHelp transformation? This would be extremely useful for us!

[radu_pisoi]

Hi,
Indeed, the DITA-OT rewriting rules have some issues in WebHelp transformation. If you change the location of an HTML resource the path to CSS resources is generated wrong.

I have added an issue in our internal issue tracker to be fixed in a future version.

[chrispitude]

Thanks Radu! Can you please let me know the issue ID for rewrite rules support in WebHelp so we can track it on our side?

This would be a particularly powerful feature of WebHelp with some additional enhancements from the DITA-OT side:

#3957: Include @keyscope and @outputclass in the rewrite-rules file list

Thanks!

[radu_pisoi]

Hi Chris,

The issue ID for rewrite rules support in WebHelp is WH-2976.

[chrispitude]

Hi everyone,

I think I have a "good enough" solution for this.

To define a custom landing page, just add outputclass="landing_page" to a topic in your WebHelp map:

Code: Select all

<map>
  <topicref href="olh/my_landing_page.dita" outputclass="landing_page"/>
  ...

This topic will become the new "main page" of the help collection. The topic can be located anywhere in the map. Then, apply the XSLT file from the provided testcase to the four WebHelp extension points:

Code: Select all

<xslt>
    <extension id="com.oxygenxml.webhelp.xsl.createMainPage"       file="xsl/change-home-page.xsl"/>
    <extension id="com.oxygenxml.webhelp.xsl.dita2webhelp"         file="xsl/change-home-page.xsl"/>
    <extension id="com.oxygenxml.webhelp.xsl.createSearchPage"     file="xsl/change-home-page.xsl"/>
    <extension id="com.oxygenxml.webhelp.xsl.createIndexTermsPage" file="xsl/change-home-page.xsl"/>
</xslt>

The XSLT file makes use of two existing variables that the WebHelp processing already defines:

• $toc - contains the contents of the toc.xml file
• $PATH2PROJ - contains the relative path from the current HTML file back to the root output directory

From $toc, I get the landing page @href path by taking advantage of the fact that @outputclass propagates into the toc.xml file:

Code: Select all

<xsl:variable
  name="landing-page-href"
  select="($toc//*[contains-token(@outputclass, 'landing_page')])[1]/@href"
  as="xs:string?"/>

Then, additional templates replace @href references to "index.html" with the desired landing page:

Code: Select all

<!-- change header map title link -->
<xsl:template match="div[contains-token(@class, 'wh_publication_title')]/a/@href" mode="change-home-page">
    <xsl:attribute name="href" select="$PATH2PROJ || $landing-page-href"/>
</xsl:template>

<!-- change header "Home" link -->
<xsl:template match="div[contains-token(@class, 'wh_breadcrumb')]/ol/li[1]/span[contains-token(@class, 'home')]/a/@href" mode="change-home-page">
    <xsl:attribute name="href" select="$PATH2PROJ || $landing-page-href"/>
</xsl:template>

This changes the following links:

image.png (53.22 KiB) Viewed 167 times

Another template replaces the index.html file with a redirect to the landing page:

Code: Select all

<!-- completely replace the main page with a redirect to the landing page -->
<xsl:template match="html[body[contains-token(@class, 'wh_main_page')]][$landing-page-href]" mode="copy_template">
  <xsl:copy>
    <xsl:sequence select="@*"/>
    <head>
      <meta http-equiv="refresh" content="0; url='{$landing-page-href}'" />
    </head>
    <body>
      <p>Please follow <a href="{$landing-page-href}">this link</a>.</p>
    </body>
  </xsl:copy>
</xsl:template>

There is a visible transition when the redirect occurs, but this is a reasonably good solution until DITA-OT rewrite rule support allows the index.html file to be truly replaced by the landing page.

Testcase:

webhelp_custom_landing_page.zip

(34.55 KiB) Downloaded 2 times