• DevCenter
• Documentation
• Resolvers

ePublisher URI Resolvers

Description

This article focuses on ePublisher URIs and the resolver objects which handle these URIs.

What are Resolvers?

To understand the significance of this resource, we first need to talk about resolvers. Resolvers are objects which take a Uniform Resource Identifier (URI), and determine the actual resource to which it refers. Here I am referring to URIs as defined in RFC 3986. In the ePublisher XSLs, URIs often look like the following:

 wwformat:Transforms/content.xsl
 wwtransform:common/splits/uniquenames.xsl
 wwhelpers:dita-ot

The job of the resolver is to take URIs, such as those referenced above, and resolve them to an actual resource, such as a file or directory on the filesystem. For instance, a resolver might take in the URI, wwformat:Transforms/context.xsl, and resolve it to the system path: C:\Program Files\WebWorks\ePublisher Express\Formats\Dynamic HTML\Transforms\content.xsl.

Resolvers Increase Flexibility

So, what's the big deal? Why not just hard-code the path C:\Program Files\WebWorks\ePublisher Express\Formats\Dynamic HTML\Transforms\content.xsl, and be done with it? Why do you need a resolver to tell you that? The answer lies in leveraging the specialization that is available in XSL. It also hints at part of the power of the ePublisher platform. In this case, we push the resolution of the actual resource off to the resolver. As a result, the system is not bound to a specific, or absolute location, but is free to return a resource from a list of places, based on a given criteria.

A very important part of every URI is the scheme. The scheme identifies how a URI should be interpreted. For example, the http scheme identifies a URI as a resource which plays by the rules of the Hypertext Transfer Protocol. Some of the more common schemes include ftp, file, and feed. ePublisher uses schemes to identify a list of filesystem locations, in order of priority, where a given file or directory may be located.

Let's look, for example, at the URI: wwformat:Transforms/content.xsl. We will assume that the Format of a given project we are working with is Dynamic HTML. Additionally, we assume that there is a single Target in the project which is also named, Dynamic HTML. When ePublisher encounters the URI, wwformat:Transforms/content.xsl, it calls on a resolver, which searches the following "slots" on the filesystem, and returns the first one it finds.

• NOTE: This behavior is identical to how a shell environment resolves a command that you type at the prompt. In that case, the shell runtime searches each slot identified in a "PATH" variable until it is able to find the program that was typed at the prompt.

 {Project-Directory}\Targets\Dynamic HTML\Transforms\content.xsl
 {Project-Directory}\Formats\Dynamic HTML\Transforms\content.xsl
 {Product-Directory}\Formats\Dynamic HTML\Transforms\content.xsl

In deconstructing the URI and the list of locations it references, we can make a couple of observations. First, the scheme, wwformat, refers to the currently active Target and Format. Files related to the active Target, or Format can be placed in the Project directory. If no resource is found in the Project directory, an attempt is made to reference locations in the ePublisher product installation area (C:\Program Files\WebWorks\ePublsiher Pro\Formats by default). Next, the path portion of the URI is simply appended to each one of the locations associated with the scheme. So, Transforms\content.xsl appears at the end of each path in the list above. This tiered look-up process enables ePublisher XSL Overrides.

Conclusion

Resolvers are a powerful aspect of the ePublisher platform. The addition of the wwtransform:super represents an easier, and more efficient way to extend ePublisher Formats.