Introducing WebSphere Portlet Factory HTML Templates

Rose ODonnell (rodonnell@us.ibm.com) Development Manager, WebSphere Portlet Factory, IBM Stephen Zagieboylo (szagiebo@us.ibm.com) Senior Architect, WebSphere Portlet Factory, IBM June, 2006 Copyright International Business Machines Corporation 2006. All rights reserved.

IBM WebSphere Portlet Factory helps you to produce flexible, customized portlets that run in WebSphere Portal, as well as stand-alone Web applications, in an easy and highly automated way. You can use the HTML Templates feature to achieve a custom, handcrafted appearance for your applications without coding the HTML by hand. This article helps you get started with HTML Templates and explains the concepts that form the basis for the automatic construction of the HTML.

Introduction ......................................................................................................................... 2 Basic concepts ..................................................................................................................... 3 HTML Template overview.............................................................................................. 3 Named constructs ............................................................................................................ 4 How the constructs fit together ....................................................................................... 4 Data shape vs. data contents................................................................................................ 5 The shape of data: containers and leaves ....................................................................... 5 Containers: vertical vs. horizontal.................................................................................. 5 HTML generation based on data shape........................................................................... 6 Examples of common patterns ............................................................................................ 6 HTML Template constructs ................................................................................................ 9 Elements within the constructs...................................................................................... 11 The vertical groups (Display and Data Entry) .......................................................... 11 The horizontal groups (tables and columns) ............................................................. 11 Controlling which construct is selected ........................................................................ 12 Sample HTML Templates................................................................................................. 12 Columnar....................................................................................................................... 12 ColumnarStyles ............................................................................................................. 12 LabelAbove ................................................................................................................... 13 LabelAboveStyles ......................................................................................................... 13 DropShadow.................................................................................................................. 13 Thumbnail Grid ............................................................................................................. 13 Conclusion......................................................................................................................... 13 Resources .......................................................................................................................... 14 About the authors .............................................................................................................. 14

Introduction
IBM WebSphere Portlet Factory (hereafter called Portlet Factory) is a tool for creating highly customized portlets that run in WebSphere Portal, as well as highly customized stand-alone Web applications. The PageAutomation framework, a component in Portlet Factory, automates creation of HTML pages, both for data entry and display. It uses information from metadata such as XML Schemae. The HTML Template feature, which is an integral part of PageAutomation, gives you fine-grained control over the generated HTML. The process you use to craft your interface is highly automated and repeatable. You can take advantage of the automation, while still maintaining complete control over the look-and-feel of the resulting HTML. This article assumes that the reader is knowledgeable about and skilled in editing and manipulating HTML. It also assumes the reader is familiar with Portlet Factory and its automation concepts, although development skills are not required to use the feature. The format of an HTML Template is HTML. It has some specific requirements for

naming and for identifying elements, which are special HTML snippets called "constructs" that Portlet Factory uses in constructing the HTML for your page. You could think of an HTML Template as a collection of HTML snippets (constructs) that are snapped together like pieces in a children's construction toy. You make these constructs using normal HTML, and then you add some specifically named elements to tell Portlet Factory which construct is to be used for which purpose, and to identify the various pieces. The biggest challenge in creating an HTML template is to build it so that Portlet Factory will create valid HTML when it snaps your constructs together. Understanding the construct hierarchy is key to getting the right results; the best way to do that is to start with one of the sample HTML Templates provided with Portlet Factory and to modify it as needed to achieve what you want. There is currently no contextual editor provided by Portlet Factory for the editing of HTML Templates. You can use any commercial HTML editor which enables you to see and edit the HTML source code that you are creating. Because you will have to enter specific names for the constructs and their constituent pieces, you will need to edit the HTML source code directly.. Although HTML Templates can be edited in a standard text editor, we recommend that you use an HTML editing tool that can display the HTML in a browser window as you edit a template, or you might want to use an XML editor, such as the Eclipse plugin XMLBuddy. Using these types of tools will help ensure that you are creating a wellformed HTML Template to produce the results you want. Install the Portlet Factory with an application server; for example, WebSphere Application Server or Tomcat. (It does not require a portal server.) To explore examples of several HTML Templates and to see how they operate, add the Feature Set, Tutorials and Samples Applications.

Basic concepts
HTML Template overview
The goal of using HTML Templates is to enable the Page Automation code of Portlet Factory to build HTML that looks handcrafted but is instead generated from a description of the data. With just a few templates, you can define the overall look for an entire application with hundreds of pages in it. In addition, by changing the templates (with Profiling), you can change the overall look dramatically, without sacrificing the quality of the appearance at all. The idea behind HTML Templates is that there are a relatively small number of ways to arrange data on a page. You can provide descriptive HTML snippets, or constructs, that describe the display of each type of arrangement. There are three basic things to understand:

1. The constructs that you must specify 2. How those constructs will be fit together, based on the shape of the application data 3. How to create specialized versions of the constructs for special purposes This article addresses the first two of these topics.

Named constructs
Portlet Factory Page Automation defines a comprehensive set of named constructs to describe the layout and display of data. In general, the constructs describe certain data shapes, such as a table, a column, or a data entry form. For each construct-type your application needs, you specify one or more snippets of HTML that describe the results you want. Page automation selects the most appropriate constructs from among your set of definitions as it processes the layout of data on each page. You can nest your construct specifications to represent a hierarchy of use. For example, a date appearing in a header column of a table can be treated differently than a date displayed within a table row. In essence, you provide a set of descriptive rules that Page Automation is to follow for the various data shapes and desired presentations for your application. See the Construct Reference Table for the list of named constructs. Every construct contains elements that specify the location within the construct for the constituent parts. For example, a DisplayField construct needs to know where the FieldLabel and FieldElement are to be placed. There are default behaviors (or errors) if a construct does not specify the location for all the elements a construct can include. An HTML Template may contain multiple construct descriptions ranging from the general (for example, any integer) to increasing levels of specificity (for example, an integer displayed as a label), and even to the point of identifying a data element by its name in the application (CustomerID). This would not be a typical case but it illustrates that you have complete control over the automated display of your data. When there are multiple constructs specified, Page Automation always uses the one that most specifically matches the particular data being processed.

How the constructs fit together

Some of the named constructs are containers; that is, they can contain other constructs. Page Automation follows a set of rules in fitting constructs together to create HTML. (For example, it puts ColumnHeader constructs inside the TableHeader section of the Table construct.) You must specify your HTML Template constructs in a logical and consistent manner so that they will form legal HTML when they are combined. See Examples of common patterns to see how the constructs fit together. See Controlling which construct is selected to learn how you can control exactly which construct is selected for any given case. Two conventions are followed to make it easier to define your constructs so they fit together correctly. Within a construct, every named element that is intended to hold constructs of a different type has the word Container as part of its name. For example, the construct GroupContainer is an element that can contain different constructs, depending on where it occurs.

Furthermore, all elements of the name pattern: <anything>Container are always emptied out before they are used by Page Automation. This enables you to nest your construct definitions the way you logically think about the hierarchy and containment you want, including the use of sample data to document your template. You can effectively build your constructs in place and visualize your specification by viewing the HTML Template file in a browser window.

Data shape vs. data contents

With HTML Templates, you handle your data at a fairly high level of presentation abstraction. When creating a simple HTML page, you know the exact values you want to display, and you only need to be concerned with how to lay them out. When you are creating a JSP page, you think of the data more abstractly, by field name or by some other referenced technique. You also have to consider how to render sections of repeated elements, such as the rows from a database query. You know the shape of your data, not the actual values, and you construct the JSP page with this shape in mind. When you are creating an HTML Template, you are yet another degree of abstraction removed from the data. Page Automation knows the shape of the data as the application is being generated; all you have to do is provide sufficient descriptive rules (constructs) so that PageAutomation can apply the right constructs to get the effect you desire. Essentially, you are instructing Page Automation: IF the data is shaped like this, THEN create HTML (and ultimately, JSP) that looks like this.

The shape of data: containers and leaves

XML provides a good metaphor for the shape of data. In XML data, there are complex data elements and simple data elements. In Page Automation, these correspond to containers and leaves. Sometimes a container represents an element that is repeated, such as a row in a database. Sometimes it is used for grouping data that is related in some way. The Model developer may sometimes define additional containers (using a Data Hierarchy Modifier or a Page Automation Display Manager) for the sole purpose of managing the display (in cooperation with the specifications in an HTML Template).

Containers: vertical vs. horizontal

Containers have a display mode attribute that can be either vertical or horizontal. This is more a description of the type of container and how it is handled, than the actual visual layout of the container contents. Page Automation uses the vertical or horizontal attribute in determining various aspects of the generated HTML. A horizontal display mode container is considered to be a Table. A vertical display mode container is considered to be either a Display Group or a Data Entry Group.

Containers are assigned a default display mode, but the Model developer can change the display mode for any page data by using the Data Field Modifier Builder.

HTML generation based on data shape

The Page Automation code constructs HTML based on the shape of the data it is processing, and by following the rules that you have given in your HTML Template. This HTML is then used to generate the JSP for the page. There are a relatively small number of ways that data can be arranged (see the Construct Reference Table). For each of these, the HTML Template provides the Page Automation subsystem with a sample to be used for the specific data shape at hand. In creating an HTML Template file, you should provide constructs for all the types of data shapes that will appear in your application. And you should include constructs for all types, even if they arent used, since it doesnt hurt and the application might change in the future.

Examples of common patterns

This section illustrates a few simple but common patterns. It is important to arrange constructs so that they will produce legal HTML when they are applied by Page Automation to your data. While the Construct Reference Table defines what is legal for each construct, it isnt possible to define all legal combinations and permutations. In the following examples, constructs are in bold and construct elements are in parentheses. Here is a standard way that elements fit together to produce a common grouping pattern: PageWrapper (PageContentsContainer) GroupWrapper (LabelContainer) GroupLabel (GroupContainer) Group (DataContainer)
GroupWrapper again OR- Field

Figure 1. A common grouping pattern

Here is a common use of TableWrapper when there are no ColumnGroups: PageWrapper (PageContentsContainer) TableWrapper (LabelContainer) TableLabel (GroupContainer) Table (TableHeaderContainer) ColumnHeader (DataContainer) ColumnData

Figure 2. Using TableWrapper with no ColumnGroups

Here is an example of TableWrapper when ColumnGroups are used: TableWrapper (LabelContainer) TableLabel (GroupContainer) Table (OptionalColumnGroupHeaderContainer) ColumnGroupHeader OR ColumnGroupHeaderEmpty (TableHeaderContainer) ColumnGroupSubHeaderWrapper (TableHeaderContainer) ColumnHeader ColumnGroupSubHeaderWrapperEmpty (TableHeaderContainer) ColumnHeader (DataContainer) ColumnGroupContentsWrapper (DataContainer) ColumnData ColumnGroupContentsWrapperEmpty

(DataContainer) ColumnData Figure 3. Using TableWrapper with ColumnGroups

HTML Template constructs

The Construct Reference Table lists all the constructs that the Page Automation code expects. It also describes which elements are expected within a construct to identify the location for that element and what happens if the element is not present. The fourth column lists which other constructs (if any) each Container construct can contain, depending on where the construct occurs. Table 1. Construct Reference Table
Construct Name DisplayPageWrapper DataEntryPageWrapper DisplayGroupWrapper DisplayGroup Elements within construct PageContentsContainer PageContentsContainer LabelContainer GroupContainer DataContainer RepeatElement LabelText FieldLabel FieldElement LabelContainer GroupContainer Behavior if omitted error error label omitted uses Wrapper error uses DataContainer label text omitted label text omitted error label omitted uses Wrapper Can Contain DisplayGroupWrapper DataEntryGroup-Wrapper DisplayGroupLabel DisplayGroup DisplayGroupWrapper* DisplayField *2 *3 *3 *3 DataEntryGroupLabel DataEntryGroup

DisplayGroupLabel DisplayField DataEntryGroupWrapper

DataEntryGroup

DataContainer

error

DataEntryGroup-Wrapper* DataEntryField *2 *3 *3 *3 *3 *3 TableLabel Table *3 ColumnHeader ColumnHeaderSorted ColumnGroupSubHeaderWrapper ColumnGroupSubHeaderWrapperEmpty ColumnGroupHeader ColumnGroupHeader-Empty *2 ColumnData ColumnGroupContentsWrapper ColumnGroupContentsWrapper Empty *3 *3 *3 *4 *4 ColumnHeader ColumnHeaderSorted ColumnData ColumnData *3 *3

DataEntryGroupLabel DataEntryField

RepeatElement LabelText FieldLabel FieldElement FieldRequired FieldValidationError LabelContainer GroupContainer

uses DataContainer label text omitted label text omitted error required text omitted validation text omitted label omitted uses Wrapper label text omitted column headers omitted

TableWrapper

TableLabel Table

LabelText TableHeaderContainer

OptionalColumnGroupHeaderContainer RepeatElement DataContainer

if needed, error error RepeatElement

ColumnHeader ColumnHeaderSorted ColumnGroupHeader

HeaderElement HeaderElement HeaderElement ColumnGroupHeaderCell (must be TD!) ColumnGroupHeaderCell (must be TD!) TableHeaderContainer TableHeaderContainer DataContainer DataContainer DataElement DataElement

uses top of construct uses top of construct uses top of construct uses Header nothing uses Wrapper uses Wrapper uses Wrapper uses WrapperEmpty uses top of construct uses top of construct

ColumnGroupHeaderEmpty ColumnGroupSubHeaderWrapper ColumnGroupSubHeaderWrapperEmpty ColumnGroupContentsWrapper ColumnGroupContentsWrapperEmpty ColumnData ColumnData_autodelete

* A DisplayGroups DataContainer may contain DisplayFields or DisplayGroupWrapper *2 RepeatElement is not a Container, but it must surround the associated DataContainer *3 These are all text or control elements. You can safely put sample text in them. *4 ColumnGroups is an advanced topic.

Elements within the constructs

For each construct, the elements listed define the location of the important things for that construct. For example, a Data Entry Field requires four pieces be placed on the page: label, required indicator, data control, and validation error message. For a Data Entry Field construct, you specify each of these locations within the construct by your placement of these elements. For all container constructs, the element named DataContainer locates the children of that container.

The vertical groups (Display and Data Entry)

Every container is assigned a Display mode attribute: vertical, horizontal, or none. Containers with display mode none are not shown; containers with display mode vertical can be either Display Groups or Data Entry Groups; containers with display mode horizontal are treated as Tables. This section describes the way various modes are handled. Display vs. Data Entry An entire page is treated as either Display or Data Entry. If there is a single Data Entry field on the page, the entire page is considered to be a Data Entry page. You can appropriately align a mix of Display Fields (often 2 columns, label and data) and Data Entry fields (often 4 columns). Group Wrapper vs. Group For both the Display Groups and the Data Entry Groups, there are two grouping constructs: Group Wrapper and Group. This enables flexibility and efficiency in managing multiple kinds of groupings. Repeated Vertical Data There are instances when vertically displayed data has a repeat pattern; for example, a list of orders where each order includes a table of items. You can display this list of orders one above the other, as if you were simply repeating one order. Both DisplayGroup and DataEntryGroup constructs let you specify exactly where the HTML will be repeated when there is more than one instance of the data.

The horizontal groups (tables and columns)

The most common display for display mode horizontal is a table, where the column headers are the labels of the containers child elements, and the column contents (typically repeated) are the data of the containers child elements. The most common group that gets horizontal display mode is a Row from a database query. It is typically repeated data, and its immediate children are the columns, which are all leaves. The most important difference between the Table construct, DisplayGroup, and DataEntryGroup is the way the immediate children of the container are handled. When Table is used, labels of the children are put in one section (TableHeaderContainer), and

the data of the children is placed inside the DataContainer. The constructs to use for these children are ColumnHeader (or ColumnHeaderSorted) for the labels (headers) and ColumnData for the data. If sorting properties have been put on a column by the model author, then Page Automation will use the ColumnHeaderSorted construct. Therefore, you need to provide an HTML snippet for sorted columns, if your application does this (or you can rely on the defaults, of course).

Controlling which construct is selected

Within a single HTML Template file, you can have multiple instances of the same construct but in different patterns. You control the use of these additional choices by adding qualifiers to the construct name, in one of three ways: 1. Based on the data type of the data element for which the construct is being selected 2. Based on the control type of the element 3. Based on the specific name of the element In addition, you can specify a completely different HTML Template file as Builder input for specific places in the Page Automation contents tree. The power of HTML Templates is hidden in this ability to be as specific as you need to be. By controlling which construct is selected with some simple rules, you can achieve rich layout that looks hand-crafted, but is actually fully automated.

Sample HTML Templates

Portlet Factory includes several sample HTML Templates that produce typical presentation layouts. You might find it useful to start with the sample that most closely resembles what you are trying to achieve.

Columnar
The default HTML Template in the Data Page Builder is Columnar.html. In this template, PageWrapper creates a TABLE tag without rows or columns, but with the expectation that there will be four columns, (label, required prompt, value, validation error message). Each Element on the page is expected to start with a TR tag. Page Automation will create the TD tags, as necessary. The benefit of this template is that all the columns will line up, even across groups.

ColumnarStyles
This Template is identical to Columnar.html, except that it uses styles directly rather than using HTML classes and a style sheet. This can be an advantageous when your page is being displayed in a portal, and you do not have control over the style sheet that is being included in the page.

LabelAbove
This HTML Template is useful when the page is being fit into a narrow space. Labels are above the elements, both in the Display and in the Data Entry pages.

LabelAboveStyles
This Template is identical to LabelAbove except that it keeps the styles hard-coded in the page rather than using a style sheet and classes.

DropShadow
This Template is similar to LabelAboveStyles in that each DisplayGroup and DataEntryGroup gets its own DIV tag. This DIV tag has thicker right and bottom borders, presenting a shadowed appearance.

Thumbnail Grid
This special Template transforms a long list of compact objects into an array of objects.

Conclusion
The use of HTML Templates in Portlet Factory can give you complete control over the layout and look of your data, so that, even if your application or data changes, the Page Automation subsystem will be able to consistently generate the design you want. There is a learning curve to become familiar with the constructs used to specify how data should be treated, but the ultimate savings in time is worth the investment. Sample templates provided with the product can help get you started.

Resources
developerWorks WebSphere Portal zone http://www.ibm.com/developerworks/websphere/zones/portal/ developerWorks WebSphere Portlet Factory forums http://www.ibm.com/developerworks/forums/wsdd_forums.jsp WebSphere Portal product documentation http://www.ibm.com/developerworks/websphere/zones/portal/proddoc.html WebSphere Portlet Factory product documentation http://www.ibm.com/developerworks/websphere/zones/portal/portletfactory/proddoc.htm l WebSphere Portlet Factory product overview http://www.ibm.com/software/genservers/portletfactory/ WebSphere Portlet Factory support http://www.ibm.com/software/genservers/portletfactory/support/

About the authors

Rose ODonnell is a manager in Workplace, Portal and Collaboration Software in Westford, Massachusetts. She came to IBM from the Bowstreet acquisition. You can reach Rose at rodonnell@us.ibm.com

Steve Zagieboylo is a software architect in Workplace, Portal and Collaboration Software in Westford, Massachusetts. He has been the principal designer and implementer of the Page Automation capability in Portlet Factory. He came to IBM from the Bowstreet acquisition. szagiebo@us.ibm.com. Trademarks DB2, IBM, Lotus, Tivoli, Rational, and WebSphere are trademarks or registered trademarks of IBM Corporation in the United States, other countries, or both. Windows and Windows NT are registered trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Other company, product, and service names may be trademarks or service marks of others.

IBM copyright and trademark information: http://www.ibm.com/legal/copytrade.phtml