Putting a "Return to Top" link only on select paragraphs
The Requirements
Wanting a return to top link per paragraph
The Challenge
First before anything else, you have to make a modification to the page template to include an anchor. Since Page.asp contains conditions, you have to make them match the ones set for the "Page content with header/footer" and the "Page content with no header/footer." and change it so it would look like the following:
<a wwpage:condition="header-footer-exists" name="topcontent">Top of the page</a>
<blockquote wwpage:condition="header-footer-exists"
wwpage:content="content">
Page content with header/footer.
</blockquote>
<a wwpage:condition="header-footer-not-exists" name="topcontent">Top of the page</a>
<div wwpage:condition="header-footer-not-exists" wwpage:replace="content">
Page content with no header/footer.
</div>For more information on page template modifications and appropriate conditions, you can refer to the following: http://wiki.webworks.com/DevCenter/Documentation/PageTemplates#defining-conditions-and-replacements
After this has been set, you could, if you have no tables or bullets (highly unlikely) simply add a modification to the content.xsl file located in Formats\[your format]\Transforms and put
<html:a href="#returntop">Return to top</html:a>
Underneath the
<!-- End paragraph emit -->
comment
However, this returns less than favorable results. When trying this, the link would appear under every item in the content that contained a carriage return. Epublisher treats every Paragraph style (Headings, bullets, and even table cells) as its own break. This is great for styling, not so great for semantics (treating multi-line text rather than just single lines of text as a paragraph) Mad props to JesseWiles, though to at least pointing me in the right direction to get started with looking at the </xsl:element> tag to put in my code.
The Code
Requirements are to put a link under Body paragraphs and having some sort of logic to control the XSL to only recognize certain paragraph style. In lieu of having this style hardcoded in the XSL, we would want a switch that the user can control in the UI. Mad shouts to BenAllums too, because he suggested creating an FTI setting that will let the user switch on or off if a given Paragraph style will get this return to top link.
For more information on FTI settings, refer to the following page: http://wiki.webworks.com/DevCenter/Documentation/FTI
Content.xsl
We heart content.xsl, because it is like totally our BFF:
So, we have to create a boolean <xsl:if> statement in order to get this FTI setting to appear as "true" but we need to grab this from user input from the FTI (discussed next) So we don't have to reinvent the wheel, Ben suggested looking to the "Use character style" options around line 817
<xsl:variable name="VarUseCharacterStylesOption" select="$ParamOverrideRule/wwproject:Options/wwproject:Option[@Name = 'use-character-styles']/@Value" /> <xsl:variable name="VarUseCharacterStyles" select="(string-length($VarUseCharacterStylesOption) = 0) or ($VarUseCharacterStylesOption = 'true')" />
So based on this code, I modified it slightly to look like this
<xsl:variable name="VarEmitReturnToTopLinkOption" select="$ParamOverrideRule/wwproject:Options/wwproject:Option[@Name = 'emit-return-to-top-link']/@Value " />
<xsl:variable name="VarEmitReturnToTopLink" select="$VarEmitReturnToTopLinkOption = 'true'" />
<xsl:if test="$VarEmitReturnToTopLink">
<a href="#topcontent">Return to top...</a>Basically, we are taking the value of the attributes in the heirarchy of the Options and the Option in the pages.fti (will make more since when you open it up) and the "emit-return-to-top-link" attribute and testing to see if they are true based on the user input. If you want to learn more about the ins and outs of XSL and how it relates to ePublisher, I would suggest taking a look at the following: http://wiki.webworks.com/DevCenter/Documentation/Engine
Pages.fti
We have to make the modification to the Pages.fti in order for us to actually see the switch:In the same directory as the content.xsl file, you will have the FTI file (copied from your favorite format and pasted in your project directory)
<Option name="emit-return-to-top-link" group="options" default="false"> <OptionClass name="boolean" /> </Option>
Page.asp
Returning to page conditions, you modify the page template as was mentioned earlier:
<a wwpage:condition="header-footer-exists" name="topcontent">Top of the page</a>
<blockquote wwpage:condition="header-footer-exists"
wwpage:content="content">
Page content with header/footer.
</blockquote>
<a wwpage:condition="header-footer-not-exists" name="topcontent">Top of the page</a>
<div wwpage:condition="header-footer-not-exists" wwpage:replace="content">
Page content with no header/footer.
</div>
Generate, generate, generate
Save these files, save your project, reopen ePublisher, and voila you have your switch and then you can regenerate with the "Back to Top" links
If you look at the content.xsl code above and are familiar with XSL, you will recognize the paths that we used to get this modification and why they were like that. If not, well you can trust me.
Support Goddess Notes
- Your variables, elements, attributes and existence must have case sensitivity, otherwise this will not work.
Tested in CHM and WebWorks Help 5.0 formats.
- Best advice if working with multiple Formats: start from scratch each time.
- Don't try to copy and paste between multiple versions of content.xsl
- Very messy and you might get an error like this:
[Error] Error occurred while reading tranform 'wwformat:Transforms\popups.xsl' from file 'C:\Program Files\WebWorks\ePublisher\2009.4\Formats\Microsoft HTML Help 1.x\Transforms\popups.xsl'. [Error] An 'xsl:call-template' element cannot have text node children.
Yuck! So, just take your time, have a few cups of espresso and enjoy the world of XSL modifications.