Modifying the Page Template

Description

A customer wanted to modify her page template to include some additional content (independent of Company Contact Info) that could be specified in the Format Settings and applied to some page styles, but not all of them. I thought the solution, though seemingly complex, might be helpful to other users; it is easy to replicate and adapt to your own project needs.

Contents

  1. Modifying the Page Template
    1. Description
    2. Procedure
      1. Modify Page.asp
      2. Modify pages.fti
      3. Modify pages.xsl
      4. Define UI Settings
    3. Conclusion
    4. Resources

Procedure

The basic steps to adding this feature are:

  1. Add HTML and XSL references to Page.asp.
  2. Add new fields to Format Settings and an option to the Page Styles.
  3. Define new conditions and replacements in pages.xsl.
  4. Use new UI fields to reference external files.

For this example, we will work with the WebWorks Help 5.0 format. The same modifications also apply to most other output formats, though.

Modify Page.asp

First, perform an override on Page.asp, located by default in the ePublisher Pro installation directory here:

Once it is copied into the appropriate project subfolder, open it in a text editor to make changes. Above the first <blockquote> tag, add something like the following: 

    <div wwpage:condition="unica-replace" style="text-align:center;">
        <img src="unica-logo.jpg" border="0" alt="Unica Corporation" wwpage:attribute-src="topReplace-src" />
    </div>

That will check to see if the “unica-replace” condition is met; if so, it will insert that HTML. It will use the image file designated in the Format Settings. Next, add something like this after the header-footer-not-exists </div> tag: 

    <hr wwpage:condition="unica-replace" />
    <div wwpage:condition="unica-replace" style="text-align:center;">
     <h5>
      <a href="Copyright.html" wwpage:attribute-href="bottomReplace-href" target="_blank">Copyright</a>
     </h5>
     <div class="Message">
       This Help system is best viewed using Internet Explorer 6.0 or higher, or Netscape Navigator 6.2.1 or higher.
     </div>
     <img src="images/bottom-logo.jpg" alt="splash graphic" wwpage:attribute-src="bottomReplace-src" />

     <table align="center" width="500" cellpadding="2" cellspacing="2">
      <tr>
       <td align="center">
         <h6>Affinium is a registered trademark of Unica Corporation.<br />
             Copyright &#169; 2007 Unica Corporation. All Rights Reserved.
         </h6>
       </td>
      </tr>
     </table>
    </div>

That markup will check the unica-replace condition, adding the HTML code and referencing the specified files, if applicable. You can save and close Page.asp.

Modify pages.fti

So, now we need to define all of the settings we referenced in the page template. In the Format Settings, we need to add some fields to choose the images and the copyright HTML page from the project’s “Files” folder. Also, we’ll add a setting to the Page Style options to choose whether to enable these replacements for each style.

Perform an override on pages.fti, located in the WebWorks Help 5.0/Transforms folder. Once it’s copied into the appropriate project subfolder, open it with a text editor, such as NotePad.

In the <Groups> section, add this line: <Group name=”Unica” />

In the <Settings> section, add this: {{{ <!-- Unica Replacements -->

}}}

In the <RuleTraits category=”Page”> section, add this option: {{{ <Option name="unica-replacements" group="options" default="false">

Save and close pages.fti.

Modify pages.xsl

Finally, add the XSL that will determine the state of the conditions and pass the appropriate settings where applicable.

1. Perform an override on pages.xsl.

2. Open it in a text- or xml editor.

3. In the <!-- Conditions --> section, add this below the <xsl:variable name="VarInitialConditionsAsXML"> line: 

      <!-- Unica Replacements -->
      <!--                    -->
      <xsl:variable name="VarUnicaReplaceOption" select="$VarPageRule/wwproject:Options/wwproject:Option[@Name = 'unica-replacements']/@Value" />
      <xsl:if test="$VarUnicaReplaceOption = 'true'">
        <wwpage:Condition name="unica-replace" />
      </xsl:if>

4. In the <!-- Replacements --> section, above the webworks-root replacement, add this code: 

      <!-- Unica Replacements --> 
      <!--                    -->
       <wwpage:Replacement name="topReplace-src">
        <xsl:variable name="VarTopReplaceSrc" select="wwprojext:GetFormatSetting('top-image-src','')" />
        <xsl:if test="string-length($VarTopReplaceSrc) &gt; 0">
          <xsl:attribute name="value">
            <xsl:value-of select="$VarTopReplaceSrc" />
          </xsl:attribute>
        </xsl:if>
       </wwpage:Replacement>

       <wwpage:Replacement name="bottomReplace-src">
         <xsl:variable name="VarBottomReplaceSrc" select="wwprojext:GetFormatSetting('bottom-image-src','')" />
         <xsl:if test="string-length($VarBottomReplaceSrc) &gt; 0">
           <xsl:attribute name="value">
             <xsl:value-of select="$VarBottomReplaceSrc" />
           </xsl:attribute>
         </xsl:if>
       </wwpage:Replacement>

       <wwpage:Replacement name="bottomReplace-href">
         <xsl:variable name="VarBottomReplaceHref" select="wwprojext:GetFormatSetting('bottom-copyright-href','')" />
         <xsl:if test="string-length($VarBottomReplaceHref) &gt; 0">
           <xsl:attribute name="value">
             <xsl:value-of select="$VarBottomReplaceHref" />
           </xsl:attribute>
         </xsl:if>         
       </wwpage:Replacement>

5. Save and close pages.xsl.

Define UI Settings

Finally, you’ll need to fill out all the new custom settings you defined.

  1. Save and close the project if it is open.
  2. Copy the relevant files (the top image, bottom image, and copyright.html page) into the project’s user “Files” folder, so that they will be copied into the output upon generation; you can put the graphics in an “images” subfolder within the Files directory if you prefer.
  3. Open the project in ePublisher Pro.
  4. In the Format Settings, you should find a new “Unica” group. Click the button in each field and choose the appropriate image/file. If you prefer to use a relative path or URL, just type it directly into the text field.
  5. In the Style Designer, choose the Page Styles section.
  6. Select a page style (or the Default style to apply to all unnamed pages) and open the Options tab.
  7. Change the “unica-replacements” setting to “Enabled” to add your replacement content to the specified pages.
  8. Regenerate output to apply the changes.

Conclusion

So, you should get WebWorks Help 5.0 output with the specified top image before the main content. Then, at the bottom, you should get the copyright link and the text and bottom image you have defined. You can enable this header and footer for each page style in the Style Designer, giving you conditional behavior for this feature.

The examples described here are pretty basic, and the effects aren't necessarily "pretty." But, this should serve as a starting point to lead you in the direction of overrides for the page template, FTI files, and XSL conditions and replacements. You can accomplish many other similar tasks once you grasp the main ideas behind this one, and that's why I hoped this would be helpful.

Of course, all of the variables, setting names, and HTML used here are specific to one user's project, and anything here can be modified or omitted to suit your needs.

Resources

Attached below, you'll find a small sample project demonstrating this series of overrides. It shows (in the most basic sense) the possible results of a customization like this. It contains all of the overridden files described here, as well as output produced with those files.

PageTemplateMods.zip

If you'd like additional (and more technical) information regarding the ePublisher page templates, see the Wiki article PageTemplates

HelpCenter/Tips/Page_Template_Modifications (last edited 2008-02-13 06:18:28 by localhost)