• DevCenter
• Projects
• DisableNavigationButtons_on_PerTopic_Basis

Disabling Navigation Buttons on a Per Topic Basis

Description / Overview

I need to disable the previous/next (and SyncTOC ideally) buttons for particular pages (specified by a PageStyle marker in source) in my (Webworks Help 5.0) output. I'll get more into the use case below, but Ben Allums said it sounded like browse sequences in old WinHelp; that's a good way to understand what I need. I essentially have topics that should not be in the online TOC or be linked linearly - they are standalone, accessed only via links (and index and search).

After doing initial work to catch the PageStyle marker in pages.xsl and add some special text to Page.asp when the marker is found, we determined that there is no way to do this via XSL transformations and Page template commands alone. The Webworks Help 5.0 javascript runtime engine assumes that prev/next navigation is either on or off, globally, and if on, assumes the user wants to be able to page through the output from start to finish. So changing this behavior involves changing the Javascript engine itself.

Thanks to Jesse Wiles's help in a recent Study Hall, who determined that the functionality sounded a lot like how the PDF button works, and wrote some test code based on the PDF button code, that would theoretically disable the navigation buttons. This code was implemented in the latest attachment, but it's not quite working.

I think what's missing is to call the code correctly. It seems like pages.xsl should have a way to tell the engine to use the navigation button disable code when processing a page with the PageStyle marker. So far everything I've tried to do this has not worked. And that's where we're at.

Introduction

((leaving the rest of the article until it works)) Let's imagine that we want to make a large user guide appear less overwhelming. A typical "design pattern" for doing this is to include only general information in the guide (print and online) with links to detailed topics in the online version. These detail topics are not conceptually part of the structure of "the book": they aren't listed in the TOC, and they are not related by their order in the source file. Expand/Collapse sections or Pop-up Windows are the standard ways to do this, but they don't work if you are also generating formats that don't support those, such as JavaHelp.

Webworks Help 5.0 (and Dynamic HTML) assumes that the pages it generates should all be linked together with prev/next buttons (although you can turn them off globally in a project/stationery). This makes it hard to generate online output that is both linear (book like) and non-linear (info database). (I'm concentrating on Webworks Help 5.0 but this all seems as-or-more applicable to Dynamic HTML, so keeping it in mind.)

The Webworks Help 5.0 "engine" does know how to disable the navigation buttons, as evidenced by the fact that when you display the first page in an output, the "previous" button is disabled, and the "next" button is disabled when showing the last page. I don't know whether it determines this at "runtime" when displaying the online output, or at "compile time" when generating the output. This may be the key to making this work - for any page with a particular PageStyle marker value, trick the engine into thinking there is no topic before or after it.

Development Project, Source, Output

The following ZIP file contains a minimal ePublisher Pro (2009.3 / Frame 9) project representing the current state of, ahem, development:

* DisablePrevNext-via-PageStyle(r1).zip

It's pretty small.. Just unzip it to your machine and load the DisablePrevNext-via-PageStyle.wep in Pro. The Frame source is in ./Source and I've also included the output.

Walkthrough of Example Project

FrameMaker Source

./Source/Bk2.book is just one of the example books that comes with FrameMaker with some adaptations. Think of it as a "online" book that could be used to build a JavaHelp deliverable, WebWorks Help, Dynamic Help, etc.

• Bk2.fm is the traditional linear guide chapter, with a couple of sections; all to be generated in the traditional manner. The important part is the section called "EXAMPLE SECTION LINKING TO ONLINE-ONLY REFERENCE TOPICS" which, oddly enough, does what it says. It has cross-references to the reference topics that won't appear in the TOC.

• Bk2-OnlineRefTopics.fm is a reference/detail chapter. It's not meant to be part of the book, conceptually, more of a database of topics. The important things to note about how this is structured:

  1. The chapter title is hidden conditional text.

  2. The headings use the "Head2NoNav" paragraph tag, and contain a PageStyle marker, text "NoNavigation". We need the paragraph tag to break each topic onto its own page, and we need the PageStyle marker so the output can go on a new page without breadcrumbs.

ePublisher Pro Project

Minimal Style Designer changes were made: Paragraph Styles to set up the TOC and page breaks; Page Style to set up NoNavigation to not output breadcrumbs. Overrides have been made to Page.asp and pages.xsl, mostly patterned after the LaurenLever/@Solutions/Overrides/Locale to page template page.

Page.asp

./Formats/WebWorks Help 5.0/Pages/Page.asp has the following added after <hr wwpage:condition="header-exists" align="left" />:

<!-- Add text to page template based on PageStyle marker -->
<div wwpage:condition="NoNavigation" style="text-align:center; font: bold 10pt 'arial,verdana,sans-serif'; background-color: #FFFFCC;">
Note: The <img src="wwhelp/wwhimpl/common/images/sync.gif" height="12" />, <img src="wwhelp/wwhimpl/common/images/prev.gif" height="12" />, and <img src="wwhelp/wwhimpl/common/images/next.gif" height="12" /> navigation buttons above should be disabled for this online help reference topic but aren't.
</div>

This uses the wwpage:condition command to add a note only on pages where the Page Style is NoNavigation (tested and set on pages.xsl).

pages.xsl

./Formats/WebWorks Help 5.0/Transforms/pages.xsl has the following added after <xsl:variable name="VarInitialConditionsAsXML">:

<!-- No Navigation -->
<!--               -->
 <xsl:if test="contains(wwstring:ToLower($ParamSplit/@stylename),'nonavigation')">
  <wwpage:Condition name="NoNavigation" />
  </xsl:if>

This tests whether the PageStyle marker text is "NoNavigation" and if so, sets the condition to true for Page.asp.

There's some code a bit further down where I tried to use it to "skip navigation" but that didn't do anything, so I won't reproduce it here.

Analysis and Notes

• The pages.xsl code is catching the page style set in the source. Can pages.xsl reset the next and previous page URIs to null instead?
• Playing around with the wwpage commands and what's on the Page.asp template have led me to believe that Page.asp has no way to control the navigation buttons.

• Was thinking initially that DevCenter/Projects/Multiple Page Templates might be needed or at least couple be used for this. This was before understanding the power of the wwpage controls in the Page.asp template. Since Page.asp can't control the navigation buttons, multiple page templates won't be of any help.

• This seems like a perfect application for the Page Styles functionality, which is why I've implemented that in the source. Since I'm using a unique paragraph tag for these topics, that could be used if that's easier (ie catch the Head2NoNav para tag and disable buttons for that)..

The End

<Remember, most of the body of this article doesn't reflect the current state of the project / code. See Description / Overview section for latest.>