Article Review

This article is part of the Web Content Management (WCM) in Action series which outlines how the Developer Program makes use of the Documentum WCM toolset to manage the creation and production of the developer.documentum.com Web site. Our original intent was to convert our content into XML and then use XDQL to assemble our production pages. Once this effort was complete, we realized that by adding WebPublisher tempaltes, any author regardless of their XML knowledge could contribute content to the site. To read more about the use of XML at the Developer Program click here.

Process Review

First of all let's recap how we got to this point and then dive straight into how WebPublisher lets us automate the whole process and opens up the system to users of all technical levels.

In the High-level Design section we share our motivation for converting the Developer Program Web site into XML. We decided to store our article synopses as XML chunks and then assembling the first-level pages and newsletters from these chunks. This story follows exactly the evolution of the XML installation here at the Developer Program. Once we had reached this point we were really quite content that we had achieved our goal. We could create XML chunks in our favorite editors and import them into the Docbase. Periodically we ran a couple of transforms using the transform component in DeskTop Client and re-created the index pages or newsletter. Already we were saving many precious cycles and the accuracy of the site had increased dramatically. The Docbase Configuration section explains how we configured the Docbase to know what to do when a user imports one of our XML chunks. Already we can see how powerful and transparent this is to manage XML documents. Then the real fun starts when we consider how to use XDQL to transform collections of chunks into production HTML pages.

Primary Objective: Have all first level pages now assembled from XML

So what else did we need...?

WebPublisher Templates

It turns out we needed WebPublisher templates to complete the picture. Before we get over excited and start evangelizing about them, we'll take a minute to give a brief overview of the uses, and components of, a WebPublisher template. Then we'll explain the issues we encountered and how the templates rode to our rescue.

For our purposes we can consider that a template is simply a front-end, or a UI, to an XML chunk. Here is a picture of one of our chunks and the WebPublisher template side-by-side. As you can see, the fields in the template match up to the elements in the XML chunk.

<?xml version="1.0" encoding="UTF-8"?> <content_chunk>     <content_link ref="xxx.html">DFC JavaDocs</content_link>     <para>         We've identified the most used         DFC methods and enhanced the         JavaDocs documentation         with code snippets.     </para>     <product>DFC</product>     <technology>Java</technology>     <product_version>any</product_version>     <content_type>samplecode</content_type>     <publication_date>2001-01-01</publication_date> </content_chunk>

Creating a template is quite easy, you create a skeleton XML file and a rules file. The skeleton file contains all of the XML elements without values and is copied each time you create a new chunk. The rules file tells WebPublisher how to display the UI. The rules include which widgets to display for each element, what text to prompt the user with, how to display the widget, which fields are mandatory and which fields are read-only. When you save the chunk, the text entered into the widgets is transferred into the relevant elements in the XML chunk.

There is one other very important component used by WebPublisher templates, these are the Presentation Templates that are used to create alternate renditions of the XML file. They are actually XSL files that are used to transform the XML. We are going to see this in action when we look at assembling the index pages later in this article.

Creating our target HTML pages required two distinct processes. To author a content chunk, an end user simply fills out a WebPublisher template. Upon saving the template, an XML chunk is created in the Docbase. When we want to create a target HTML page, we use WebPublisher to assemble XML content chunks with an XDQL query that selects the appropriate chunks.

Note: It is not the intention of these papers to teach you how to use WebPublisher; we will focus specifically on how to implement the XML templates used by the Developer Program to manage our Web site.

Creating the Chunks Overview Section

If you want to install the WebPublisher templates before you read this section then Click Here.

Let's get back to the original question posed at the end of the process review. What else did we need? Surely we were happy with our solution, why bring WebPublisher into the fray? It all comes down to work and more importantly, work avoidance. Creating, saving, importing and testing the XML chunks was hard work which only the highly trained and well insured Developer Program team were able to perform. Using WebPublisher templates makes the creation of the chunks absolutely foolproof; DTD's are enforced via the rules file and dropdown lists can be used to ensure only valid entries are used. This means we can now ask individual contributors to add their own chunks.

Before we go any further let's quickly review what we mean by a chunk. Each XML chunk we create represents a synopsis used on the index pages to describe an article. If you go to the Sample Code page you might see a synopsis like this.

Each of these individual synopsis is represented by a single XML chunk in the Docbase.

So, how does it actually work? (It really does work; if you don't believe us then try it for yourself). The picture below illustrates an individual contributor using a WebPublisher template. Here are the steps that they would take;

• go to the folder where the resultant XML file will reside,
• click on 'Add New Content',
• select the template to use; in this case developer/samplecode.xml
• fill in the object name and description for the chunk,
• the WebPublisher template editor is launched,
• the user fills in the required data,
• when finished they save their work and close the template.

The content of the widgets is then transferred into the relevant elements in the XML chunk, it is saved away and then the Presentation Template is applied to the template to generate an HTML rendition.

What does the Presentation Template do in this scenario then? We did not really need an HTML version of this chunk so why bother? Although the chunk is never displayed to end users on its own, we added a basic XML to HTML presentation template so that we can see how the chunk will look on the production HTML page. While editing the chunk in WebPublisher you can click on the preview button and a browser window pops up with the HTML rendition of that chunk. This can actually be quite useful for proof-reading your work.

The output of this process is a single XML chunk; always 'valid', with only allowable values set and with mandatory values guaranteed. Not a bad result by anyone's standards.

Assembling the Pages Overview Section

Now we get to the really interesting part of the process; assembling the pages from these chunks. If you want to read a detailed overview of this process first then click here.

Take a quick look at part of one of our resultant pages; you can see that the page is basically a list of article synopses with an table of contents all wrapped up in a HTML page. We generate this page by running a XDQL query and wrapping the results in HTML. As you have read in the XDQL Development article we can do this by creating an XML chunk and transforming it using an XSL file that contains the XDQL logic and HTML tags.

So once again we are faced with the question 'Why bother involving WebPublisher in the process?'. And it is the same answer, 'Work Avoidance and Accuracy'. If we assemble the index pages by hand we have to do the transformation in the Desktop Client and then export the HTML, check out the current page from WP, copy the new text in and then check the file back into WP. All of this involves work and can be error prone. Using WebPublisher reduces both the work and risk.

The detailed overview explains the process in detail but here is a quick overview.

We have a file called samplecode.xml stored in the Docbase managed with WebPublisher. This file is an XML chunk containing just a single date. When we edit this XML chunk using WebPublisher we can enter a new date and then save the file. During the save an XSL file is used to transform the chunk into our samplecode.htm file. This HTML file is saved as a rendition of the XML file. The date is used to identify which articles should be tagged as 'New'. Once the XML has been checked back in it, and the HTML rendition, can simply be promoted out to the live Web site.

The output of this process is the production HTML file containing a list of all relevant articles with new and updated articles marked with icons. The real power of this comes when we decide to re-structure our Web site or categorize our content - all we will need to do is write new XSL files and regenerate our pages in whatever re-categorize we choose.

The End Results

To illustrate how effective this approach has been for us here is an illustration of how powerful WebPublisher can be when managing your website, Read more.... To illustrate how simple using WebPublisher is; here are the actual instructions we issue to our editors, Read more....