Web Publisher Template Basics

About This Article

This article describes the creation of xml templates and their supporting files for use within Web Publisher. It describes the basic principles of Web Publisher templates, rules files, xsl stylesheets, preview images, xml applications and folder mapping.

This document will prove helpful if:

• You’re just beginning in your configuration of Documentum Web Publisher and want to understand where to start.
• You’ve already created some simple templates but want to understand how to do more with your templates.

To get the most from this article, you should already have:

• A working knowledge of basic XML and XSL.
• A working installation of Documentum Web Publisher and a general understanding about how to interact with the web based authoring tool.

Overview

Web Publisher is a browser-based, customizable tool that allows a business user to create web content. It has the advantage over raw web page authoring tools by allowing a more secure enforcement of business rules. A content author can be permitted to create a wide variety of content formats such a Word, PDF, PowerPoint, Images or XML to name a few. Any XML content created by the author would then be transformed using XSL to the proper web site format. This document focuses on transforming XML files into HTML web pages.

There are several components of Web Publisher templates that are important for you to understand:

General Template Components

• Template - Sets basic attributes and information on the content such as object type and lifecycle. Types of Templates Include:
  • XML - Defines the structure of the final XML document. The order of the tags within the XML file determines the order the user will input information.
  • HTML - Defines the format of the final HTML document. The order of the tags within the HTML file determines the order the user will input information.
  • Downloadable Files (i.e. Word, PDF, etc) - Defines the initial layout for the new content. Typically, these type of files are added as templates to set proper attributes and security on newly created content.
• Rules Files - Only valid for templates that use the Web Publisher Editor for input. Defines the labels and input types that will appear in the Web Publisher editor for each XML (or HTML) tag.
• Thumbnails (Preview) - Small image of the final document. Thumbnails are presented to the content author when navigating and selecting a template to create new content. Their purpose is to provide the author with a visual cue as to which template to select.
• Categories - Hierarchical structure that provides alternate ways of organizing the content within Web Publisher. Authors navigate through Categories to select a template when creating new content.
• Default Workflow - Business process assigned to a template. Workflows may be assigned as optional or mandatory for each template. If a workflow is set as mandatory, the workflow will automatically launch when the content author selects “Start Workflow”. If a workflow is set as optional, the user will be presented with a list of available workflows with the optional workflow checked.
• Folder Map - Defines where the content will be stored within the Web Cabinets for publishing to the web site. This xml file defines the set of attributes and folder paths that determine content storage location which corresponds to the web site URL.

XML Only Template Components

• Presentation - An XSL stylesheet that transforms the final XML content into a web ready format. Each XML template can be associated to multiple stylesheets that may be used for different purposes on the web site. Stylesheets may also be assigned based on locale so you can use the same template for many countries. The transformation occurs when you wish to preview (local view within the Web Publisher Editor) or web view (publish to the web site) the XML document. For example if you choose to preview a document, the system will check and see if multiple stylesheets are associated to the file. If so, it will present you with a list of “formats” that you can view the document in. When you select the format you desire, the system will transform the XML document based on the stylesheet associated with your selected format.
• XML Application - An xml file that defines the business rules for how the XML file you authored is created in the docbase. For example, you may wish to chunk the document into multiple pieces of a virtual document. Or, you may wish to populate meta-data of the document from the content of the document or vice versa. This article briefly addresses two-way synchronization of attributes with XML tags which is useful for dynamic web sites under the XML Applications section. You can find out more about XML Applications in the document, “Managing XML Content in Documentum” provided by Documentum.
• Instruction Files - Instruction files are used to update existing xml content. For example, if you add a new tag to your template and you would like the older content to contain the new tag, an instruction file will support bulk updating the old content.

The location within Web Publisher of many of the components described above is shown in the following image:

XML Content Transformation

When content is published, the transformation engine built-in to Web Publisher will use an associated XSL file and the XML content file to create an XHTML page.

XML Template Creation from Start to Finish

XML Templates

There are a few things you should be aware of when creating XML templates for content:

• Object Types, Lifecycle & Default Attributes - The object type and lifecycle of the XML template file will be the object type and lifecycle of all content created in Web Publisher using that template. All object attribute values of a template will automatically carry over to any content that is based on that template. This is a convenient way to ensure that attributes for certain types of content have default values. Inherited attributes include the template alias set which is used to determine security within Web Publisher.
• Pre populated XML Values - The content of the template (the XML file) can be pre populated with anything you want. These values and attributes will automatically be inherited by content created using the template.
• Structure - The structure of the XML content of a template determines the final structure of the content. If the structure is updated in the future, all content associated with the template must be updated as well. This can be accomplished through Instruction files but it may be tricky. Keep this in mind while putting together your XML templates so you build a lasting structure.
• Ordering - The order you list the XML elements in the template file is the order they will be displayed in the GUI when a user creates content. Keep this in mind while putting together your template so the input order will be intuitive to the author.

Template Creation

In order to create a Web Publisher template, the user must be in the web developer or administrator group within Web Publisher.

1. Determine the Category Structure - Templates are stored under the Site Manager node in Web Publisher. To create a new Category:
   • Navigate to Site Manager/Templates
   • Select File -> New -> Category
2. Import the XML Template
   • Create the xml file using a text editor on your local machine. A sample xml template is provided for download, here
   • Navigate to the desired category
   • Select File -> Import
   • Browse your local drive to select the template
   • Set the template attributes (object type, lifecycle, XML Application, etc)
3. Assign the Associated Files
   • Rules File - Select the checkbox next to the template then select View -> Associations -> Rules. To create a new rules file, see rules file section below
   • Presentation File - Select the checkbox next to the template then select View -> Associations -> Presentation. When associating a presentation you must first select the transformation format which tells the system the format of the rendition that will be created.
     

     Figure 3: Presentation File Association

     To create a new presentation file, see presentation file section below
   • Preview File - Select the checkbox next to the template then select View -> Associations -> Previews. To create a new preview file, see preview file section below
   • Workflow - Select the checkbox next to the template then select View -> Associations -> Workflow. Set the workflow in the Default Workflow dropdown indicating whether it is mandatory or not. You must click Apply for the changes to take effect.
4. Configure Folder Mapping - To configure folder mapping, see folder mapping section below
5. Make Available - Select the checkbox next to the template then select Tools -> Templates -> Make Available. A content author can only create content with the template once it is marked as available.

Editor Rules File

Editor rules files define which widgets are used in the Web Publisher content editor to populate the XML elements and attributes in the associated template with the user-entered values. There are two ways to create a new rules file:

• Web Publisher Rules Editor - Web Publisher provides a web based GUI interface which is a great tool for beginners.
• Local Text Editor - More advanced users tend to prefer using a local text editor to manually create/edit rules files. Using a local editor allows the developer to access advanced functionality that is not available through the web interface.

Set your preferred rules editor within the Web Developer tab on the Web Publisher Preferences screen. We recommend starting out using the Web Publisher rules editor and switching to a local text editor when more advanced functionality such as custom tags are needed.

Rules File - Creation

Web Publisher Rules Editor

To create a new rules file with the web based editor:

1. Navigate to Site Manager/Rules
2. Select File -> New -> Rule
3. Enter a name for the rules file
4. Select the specific locale or all translations for the rules file
5. Select a template to associate with the rules file

Local Text Editor

To create a new rules file with the local text editor:

1. Create the rules file through a text editor on your local machine
2. Navigate in Web Publisher to Site Manager/Rules
3. Select File -> Import
4. Browse your local drive to select the rules file

Rules File - Widget Options

The following table lists a brief summary of the available widget options. For more detailed information, please refer to the “Web Publisher Administration Guide” provided by Documentum.

Widget Name	Description	Tips
Calendar*	Displays a calendar to allow the author to select a date.	If the calendar widget is used, this date field must be filled in by the author. By default, Web Publisher sets that date to TODAY and there is no way to clear out the value. The format of the outputted date is defined by the dateFormatString attribute. This format follows simple date format standards. *Note: This widget is only available in version 5.3 and above.
Checkbox	Displays a checkbox to allow the author a yes or no choice.	The checkbox is a good widget to use when the author’s decision determines whether something appears or does not appear on the web page. A checkbox will store a different value in the content based on the author’s selection. Make sure your checkbox label and instructions are clear and easy to understand.
Choice	Displays a selection list for the author to choose an option.	The choice list may be populated through a DQL query or a hard coded list. When possible we recommend using a DQL query to keep the list dynamic. With the choice widget, the value displayed is the value stored in the content. It is not possible to display one value such as the object name and store another value such as the object id.
Content	Displays a rich text area to allow the author to enter formatted content.	The content widget is great for the main content of a web page. Authors can be given the ability to edit the html directly making the editor robust for those one off situations which always occur. All content must be xml compliant so it is recommended to not edit the code unless absolutely necessary. As of Web Publisher 5.3, the content widget cannot be synchronized with Documentum attributes.
Custom	Allows developers to create and display custom widgets.	Custom widgets are frequently created for look ups into a registered table or to browse the Repository and select a piece of related content. for information on creating custom widgets please refer to “Web Publisher Administration Guide” provided by Documentum.
Graphic	Displays a image selector for the author to choose an image to display on their web page. The author may be presented with the folder structure to browse and select an image or a list of images.	It is extremely convenient for the author to import local images directly into the editor. However in order to allow the author to import an image, the images must be displayed in a list. This list can only display one image attribute (typically the object name) and it can not be sorted. If there are many images in the system that may be used for the template, the list may become cumbersome fast. Where possible, we recommended storing images for each template in a separate folder to allow the list to stay manageable. For general web pages that are used by all authors for a wide variety of purposes, we would recommend using the tree control and not allowing import.
Repeatdef	Displays a repeating list of xml tags. This allows the author to designate how many values will be stored in the content.	The repeatdef may be used to repeat a single or multiple xml tags. If a set of tags will be repeated together (i.e. title, details), we recommend grouping them together in under one tag underlying xml file. This will make it easier to display in the presentation file. By default when an author selects to add a new repeating element, Web Publisher copies the content of the previous repeating element into the new element. This can be turned off by setting repeatdef.populateContent=false in the /wp/editors/contenteditor/resources/EditorUI.properties file. There is no easy way to limit the number of repeating items added by the author. We recommended adding the maximum number allowed in the repeatdef instructions and using the presentation file to limit the number of items displayed.
Tabledef	Displays a table structure for the authors to create tables within the xml content.	The tabledef tag is good to use if you have pre-defined, structured, non dynamic tables on your web page. We have found that these type of tables are typically the exception. Majority of tables displayed on a web page are dynamic or unique. Unique tables should be handled with the rich text editor to allow more flexibility. Tabledefs are not exposed through the web based rules editor. You must use a local text editor to add them to your rules file.
Tagcontent	For XML templates, this defines that the inputted information will be stored within the content of the xml tag. For non-XML templates, this widget must be used to display content input fields within the editor.	The tagcontent is specifically used for storing content within non-XML templates. In order for the content to be edited with the Web Publisher tagcontent elements must be used. Template: ‘<dctmEditor teComponentType=”myTitle”>default title</dctmEditor>’ Rules File: ‘<tagcontent tag_name=”myTitle”/>’
Tagattribute	For XML templates, this defines that the inputted information will be stored within an attribute of the xml tag. For non-XML templates, this must be used to display attribute input fields within the editor.	The tagattribute is specifically used for storing attributes within non-XML templates. In order for the attribute to be edited with the Web Publisher tagcontent elements must be used. Template: ‘<img teComponentType=”myImage” width=”100″ height=”100″/ >’ Rules File: ‘<tagattribute tag_name=”myImage” selected_attr=”src”/>’
Textarea*	Displays a multiple line text field for entering content you don’t want parsed by an XML parser.	One option for the text area is to mark the output data as cdata. This is helpful if you would like the user to enter special characters such as a registered trademark into the short description. When you set type=”cdata” the text is output wrapped in CDATA tags. *Note: This widget is only available in version 5.3 and above.
Textline	Displays a single line text field for entering unformatted content.	Prior to the new 5.3 calendar widget, the textline was used to default and store date attributes. Due to limitation of not being able to set a nulldate with the calendar widget, the textline may still be used if business needs define that the author must have the ability to set a nulldate.
Textselector	Displays a file selection to allow the author to choose text from a existing file.	The textselector may only be used for simple text files. This widget is great to use for disclaimers or other supporting information that is used across many pages. The value of output_property determines the information that is stored in the content (i.e. folderPath, contents, ID). Be careful when using contents because the fragment must be well-formed XML.
Xselector	Displays a file selection with a Browse button for the author to choose a file.	The xselector is meant to be used when the author must browse through a large amount of files. A dropdown list of pre-defined queries enables the author to quickly find their file. When using the xselector make sure you have thought through the design so the queries are easy to use and intuitive for the author.

A sample rules file is provided for download, here

Presentation Files

Presentation files define how to transform the xml content into a web viewable format. The XML can be renderd into many different formats (html, asp, jsp, etc). The format you choose depends on your application and web server. This article focuses on simple html pages.

XSL Stylesheet - Creation

Web Publisher does not provide an interface for the creation of XSL stylesheets. We recommend using a text or simple xsl editor.

A sample xsl presentation file is provided for download, here

A sample xml file and its rendered html file file are provided for download as well. These files are example using the sample presentation file.

Importing into Web Publisher

1. Navigate in Web Publisher to Site Manager/Presentations/Editor
2. Select File -> Import
3. Browse your local drive to select the desired file

Thumbnail (Preview) Images

These files provide a thumbnail image of the template to aid the author in choosing which type of content to create. The optimal image is 100 x 100.

Thumbnail Image - Creation

1. Create a 100 x 100 preview image on your local machine using a photo editor such as Paint or Photoshop
2. Navigate in Web Publisher to Site Manager/Previews
3. Select File -> Import
4. Browse your local drive to select the desired image

XML Applications

An XML application defines how to store the xml file within Web Publisher. The typical use with Web Publisher templates is to synchronize xml elements with Documentum attributes. For example, the title xml content may be synchronized with the title attribute so the user does not have to enter the information twice. Synchronization of attributes is extremely helpful when building dynamic web sites.

XML Applications are created through Application Builder. A sample xml application that synchronizes the title attribute with the page_title xml content is provided for download, here. For more detailed information, please refer to “Managing XML Content in Documentum” provided by Documentum.

Configuring Folder Mapping

Folder Mapping defines where the content will be stored within the Web Cabinets for publishing. Content attributes are typically used for defining the storage location. The default foldermap file is located under Site Manager/Configurations/Foldermaps.

A sample foldermap that stores content based on the subject and author is provided for download, here. For more detailed information please refer to the “Web Publisher Administration Guide” provided by Documentum.

Common Issues/Helpful Hints

Question: I have created the template, rules and presentation files and have set my template to Available but the content author cannot see the template, why is this happening?

Answer: Check the permission on the content template and ensure all content authors have at least RELATE permission to the template.

Question: When an author is creating new content, why is Web View not available?

Answer: If you are using Web Publisher 5.3, first upgrade to 5.3 SP1 to get the fix for a web view bug within the editor. The availability of web view depends on if there is both a web ready rendition for your content and a site publishing configuration has been configured for your web cabinet. If you are experiencing web view problems, check the following:

• Check your presentation file for any bugs
• Make sure the format your presentation file is rendering is a valid web ready format. This information is set up in the Server Configuration file.
• In Documentum Administrator, check the Site Publishing Configurations to ensure a publishing configuration has been set up for your web cabinet and that it is publishing your presentation format.
• Run an end to end test on your Site Publishing Configuration to ensure Site Caching Services is running properly.

Question: What is the difference between Preview and Web View in the Web Publisher Editor?

Answer:

• Preview - Displays content within the web browser but not in the context of the web site. It does not publish the content to the web site. In order for images and stylesheets to work within preview, virtual link support must be installed.
• Web View - Publishes the content to the web site so content is displayed with the context of the web site. Web View takes slightly longer than Preview because it is actually publishing the content to the WIP web site.

Question: How do I edit the default behavior of the Web Publisher Editor? For example, I would like to turn off the mandatory comments?

Answer: The default behavior for the editor is stored in the /wp/editors/contenteditor/resources/EditorUI.properties file.