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

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

[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

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

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

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

[DITAUser123]

Thank you very much for your solution, that was very helpful. The only issue we have now is, that the context-senstive webhelp system (https://www.oxygenxml.com/doc/versions/ ... %2Cwebhelp) doesn't work anymore. Do you (or someone else) have an idea, how I could integrate that into your customized main page?

Or is there by now a more official way to make your own main page or to custumize the existing one? We have a very large webhelp and the premade main page doesn't look very pretty with a huge amount of content on it.

[InspectorSpacetime]

Wouldn't one simple solution be using a JavaScript redirect in the main (tiles) page, inserted via the webhelp.fragment.before.main.content.area.main.page fragment? So that whenever the index.html page is opened, there's an immediate redirect to another page? This script seems to do the trick:

Code: Select all

<script>window.location.replace("topics/welcome.html")</script>

Just replace the topics/welcome.html with the URL of the page you want as a target.

[chrispitude]

Hi DITAUser123,

Context-sensitive help lookups should always use the cshelp.html file for the lookup, as described here:

Context-Sensitive Help System

This is true even if you aren't overriding the main page.


Hi InspectorSpacetime,

Is your JavaScript redirect identical in function to the <meta http-equiv="refresh"/> redirect? Part of the solution I shared is because I wanted the topic to be user-selectable in the DITA source instead of hardcoded, and the other part is to override the hardcoded references to the main page so that a redirect does not occur again if the main page links are followed. (There is a disable redirect and it is admittedly not very professional looking.)

[InspectorSpacetime]

Hi Chris,

You're right, the solution I suggested is a hard-coded redirect, and just provides a simple way to skip the main page and go directly to a specific topic.

For a more complex use case you're solution is far more suitable.

[chrispitude]

Hi InspectorSpacetime,

Thank you for suggesting other options! Sometimes in the heat of battle, we stop at the first working solution, where another more optimal solution exists. It is always good to evaluate alternatives.

[DITAUser123]

Hi chrispitude,

Hi DITAUser123,
Context-sensitive help lookups should always use the cshelp.html file for the lookup, as described here:
Context-Sensitive Help System
This is true even if you aren't overriding the main page.

Does that mean, that you can't have a custom main page and a context-sensitive help system?

Nevertheless thank you for your answers.

[chrispitude]

Hi DITAUser123,

You only use cshelp.html when performing a ?contextId= lookup as described here:

Context-Sensitive Help System

The cshelp.html file is a special page with no content whose only purpose is to perform the lookup and redirect cleanly, without temporarily displaying any content that would be distracting to the user.

Any customizations to change the main page (which is opened without specifying a ?contextId= component) would be independent of that.

[chrispitude]

Hi Syncro Soft,

To bring the conversation back to the original issue, the request is to disable the toc/tiles main page completely, and instead have the WebHelp's index.html page open to a default "landing page" DITA topic authored by the writers.

Right now we are using the "good enough" redirect-based method described here, but we are getting complaints that the redirect does not look professional.

To configure the desired behavior, an alternative to using rewrite rules to replace the index.html file would be to have a WebHelp parameter that disables the toc/tiles main page completely, so that the help "falls into" the first content topic in the map. But this still has the same underlying technical challenge of, how do you get index.html to somehow contain the first topic's content? A simple copy is not sufficient because the first topic is likely in a subdirectory and the relative links will break if the content is copied to a higher directory.

Could you please create a new issue ID to track the higher-level request of disabling the toc/tiles main page and falling through to the first writer-authored topic instead? Rewrite rules support (WH-2976) is one way to achieve this, but I don't want to lock us into only considering this to be a solution.