Custom Marker Processing

Description

Many customers would like to perform custom processing on their source document markers (markers in FrameMaker, fields in Word, @otherprops in DITA). Custom marker processing can be easily accomplished on the ePublisher platform. Users can accomplish this either with an .xsl only override or can allow UI control over marker behavior. This example project will demonstrate a non-UI, .xsl only approach.

This project documents a customer marker implementation implemented by LindaRose.

Contents

  1. Custom Marker Processing
    1. Description
    2. GUID Markers
    3. GUID Markers with XML+XSL
      1. Step 1: Emit into XML
      2. Step 2: Suppress GUID in Rendered HTML
    4. GUID Markers with WebWorks Help
    5. Sample Project

GUID Markers

Customer has source FrameMaker documents which include "GUID" markers. Each "GUID" marker contains a GUID (Globally Unique Identifier), which is used to related published content back to the source. These "GUID" markers are inserted and updated using a custom script in FrameMaker. ePublisher need only preserve the contents of these markers in the rendered output.

GUID Markers with XML+XSL

The XML+XSL format publishes content to an XML structure which can then be transformed by a client-side XSL stylesheet for display within a user browser. The .xml files generated by the XML+XSL format resemble:

The key parts to notice are:

Step 1: Emit into XML

To render our "GUID" markers into the XML content, we will need to define the rules for how that content should be rendered by ePublisher. We can do this by creating an override for "Transforms\content.xsl".

In the past, we would recommend that users copy over "content.xsl" and keep a full copy in the customization area. Now, since ePublisher 2009.1, it is possible to implement what is termed a minimal override via wwtransform:super. The difference is that minimal overrides only contain the changes we care about. This is possible through XSLT support for "better match" templates.

For example, instead of:

one can now create an equivalent override (since 2009.1) with:

This type of minimal override helps to isolate custom .xsl code further from the ePublisher defaults without the need for resolving changes for future upgrade with file comparison tools.

NOTE: You can learn more about wwtransform:super over in the WebWorks Wiki.

With this minimal override file in place, we can now add in the necessary custom processing code for operating on our markers. Here, we assume the marker name is "GUID".

NOTE: We make sure to assign a namespace prefix to our <guid> element so that we can refer to it during later processing. Users are free to define alternate namespaces and namespace prefixes as required.

WARNING: You may need to switch targets and/or close and reopen your project for ePublisher to locate your new override.

Step 2: Suppress GUID in Rendered HTML

With the customization from Step 1 in place, we can now generated XML content which includes the "GUID" markers as <guid> elements:

This is correct so far. However, when this content is rendered by client-side browsers according to the "xsl/document.xsl" stylesheet, the result looks like:

Review of the rendered HTML shows why we see this result:

How can we suppress rendering of the <guid> element?

As I mentioned previously, a browser renders XML documents according to the templates defined by the stylesheet processing instruction:

So, to change how <guid> elements are rendered, we need to define a custom "xsl/document.xsl" file.

The default "xsl/document.xsl" is located within the format at "XML+XSL\Files\xsl\document.xsl". We can create an override for this in our project with:

NOTE: This transform will be handled by a client-side browser, so we cannot create a minimal .xsl override. We must copy the entire file.

Now that our "xsl/document.xsl" override file is in place, we can add the necessary code to suppress rendering of <guid> elements. We will add an XSL match template for those elements at the end of the stylesheet:

Viewing generated .xml files confirms that <guid> element rendering is now suppressed:

HTML source:

WARNING: You may need to switch targets and/or close and reopen your project for ePublisher to locate your new override.

GUID Markers with WebWorks Help

Processing "GUID" markers in WebWorks Help is similar to the approach taken with XML+XSL. We'll start by copying over "Transforms\content.xsl" to the override area:

Next, we'll remove the existing stylesheet contents and reference them via wwtransform:super:

Now, we can add our custom processing for "GUID" markers. The match template resembles the version used for the XML+XSL format. The difference here is that we want the GUID element to show up in the HTML content yet prevent it from being rendered by the browser.

One approach is to emit a <guid> element in the HTML namespace and use a CSS @style attribute to suppress GUID rendering:

This approach works for FireFox 3.* browsers, yet fails with Internet Explorer 8.

A better approach is to nest the <guid> element within a <span> tag. This gets around rendering differences for unrecognized elements, such as <guid> by different browsers.

WARNING: You may need to switch targets and/or close and reopen your project for ePublisher to locate your new override.

Sample Project

A sample project which implements these customizations is available.

This project was developed using ePublisher 2009.2, though it should be compatible with ePublisher 2009.2 and 2009.3 as well. It cannot be used with older versions of ePublisher (2009.1 and earlier) due to project incompatibilities.

DevCenter/Projects/Custom Marker Processing (last edited 2010-02-08 22:32:02 by BenAllums)