Introducing WebSphere Portlet Factory HTML Templates

Rose O’Donnell (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.

.............................................. 13 LabelAboveStyles ............................................................ It also assumes the reader is familiar with Portlet Factory and its automation concepts..................... automates creation of HTML pages........................................................................................................................................ 4 How the constructs fit together ............. 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........................................................................................................................................................... 12 ColumnarStyles ............ a component in Portlet Factory.................. 4 Data shape vs................ 9 Elements within the constructs...................................... 11 The vertical groups (Display and Data Entry) ....... 11 Controlling which construct is selected .......................................................................................................................... 6 HTML Template constructs ................................................................................................................................................................................................................................... 13 Conclusion.............................................. 12 Columnar...................................................................................................... 2 Basic concepts ............ 5 The shape of data: containers and leaves .............................................................................................. 13 DropShadow............................................................................................ as well as highly customized stand-alone Web applications..................................... 12 LabelAbove ....................................... It uses information from metadata such as XML Schemae............. 12 Sample HTML Templates................................... It has some specific requirements for ....................................................................................................................... 3 HTML Template overview.................. You can take advantage of the automation.............................................................................................................................. 5 Containers: vertical vs. 13 Thumbnail Grid ............................................................................... The HTML Template feature................ The process you use to craft your interface is highly automated and repeatable... 6 Examples of common patterns ............... both for data entry and display.......................... which is an integral part of PageAutomation................................. The PageAutomation framework..................... 3 Named constructs ........................Introduction .............................................................. horizontal........................................................................ 5 HTML generation based on data shape.................. data contents........................................................................................................ 13 Resources ......................... This article assumes that the reader is knowledgeable about and skilled in editing and manipulating HTML................................................................................................................................... 11 The horizontal groups (tables and columns) ... while still maintaining complete control over the look-and-feel of the resulting HTML................................. although development skills are not required to use the feature........................... The format of an HTML Template is HTML.... gives you fine-grained control over the generated HTML................................................................

With just a few templates. 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. WebSphere Application Server or Tomcat. (It does not require a portal server. we recommend that you use an HTML editing tool that can display the HTML in a browser window as you edit a template. and to identify the various pieces. 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. In addition. 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. without sacrificing the quality of the appearance at all. Although HTML Templates can be edited in a standard text editor. The idea behind HTML Templates is that there are a relatively small number of ways to arrange data on a page. Because you will have to enter specific names for the constructs and their constituent pieces. you can define the overall look for an entire application with hundreds of pages in it.) To explore examples of several HTML Templates and to see how they operate. You make these constructs using normal HTML. by changing the templates (with Profiling). you can change the overall look dramatically. You can provide descriptive HTML snippets. that describe the display of each type of arrangement. for example. Install the Portlet Factory with an application server. add the Feature Set.naming and for identifying elements. and then you add some specifically named elements to tell Portlet Factory which construct is to be used for which purpose. Understanding the construct hierarchy is key to getting the right results. or you might want to use an XML editor. such as the Eclipse plugin XMLBuddy. you will need to edit the HTML source code directly. 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. You can use any commercial HTML editor which enables you to see and edit the HTML source code that you are creating. or constructs.. Using these types of tools will help ensure that you are creating a wellformed HTML Template to produce the results you want. which are special HTML snippets called "constructs" that Portlet Factory uses in constructing the HTML for your page. There is currently no contextual editor provided by Portlet Factory for the editing of HTML Templates. There are three basic things to understand: . Tutorials and Samples – Applications.

Within a construct. you specify one or more snippets of HTML that describe the results you want. the constructs describe certain “data shapes”. the construct “GroupContainer” is an element that can contain different constructs. In general. An HTML Template may contain multiple construct descriptions ranging from the general (for example. an integer displayed as a label). a column. Named constructs Portlet Factory Page Automation defines a comprehensive set of named constructs to describe the layout and display of data. See Controlling which construct is selected to learn how you can control exactly which construct is selected for any given case. In essence. that is. How those constructs will be fit together. How to create specialized versions of the constructs for special purposes This article addresses the first two of these topics. See the Construct Reference Table for the list of named constructs. You can nest your construct specifications to represent a hierarchy of use. This would not be a typical case but it illustrates that you have complete control over the automated display of your data. For each construct-type your application needs. any integer) to increasing levels of specificity (for example. For example. such as a table. you provide a set of descriptive rules that Page Automation is to follow for the various data shapes and desired presentations for your application. There are default behaviors (or errors) if a construct does not specify the location for all the elements a construct can include. depending on where it occurs.1. or a data entry form. See Examples of common patterns to see how the constructs fit together. every named element that is intended to hold constructs of a different type has the word “Container” as part of its name. a date appearing in a header column of a table can be treated differently than a date displayed within a table row. Every construct contains elements that specify the location within the construct for the constituent parts. a DisplayField construct needs to know where the FieldLabel and FieldElement are to be placed. (For example. For example. Page Automation always uses the one that most specifically matches the particular data being processed. and even to the point of identifying a data element by its name in the application (CustomerID). For example. How the constructs fit together Some of the named constructs are “containers”.) You must specify your HTML Template constructs in a logical and consistent manner so that they will form legal HTML when they are combined. based on “the shape” of the application data 3. When there are multiple constructs specified. . it puts ColumnHeader constructs inside the TableHeader section of the Table construct. Two conventions are followed to make it easier to define your constructs so they fit together correctly. they can contain other constructs. Page Automation follows a set of rules in fitting constructs together to create HTML. The constructs that you must specify 2. Page automation selects the most appropriate constructs from among your set of definitions as it processes the layout of data on each page.

This is more a description of the type of container and how it is handled. than the actual visual layout of the container contents. by field name or by some other referenced technique. JSP) that looks like this. such as a row in a database. Essentially. Sometimes it is used for grouping data that is related in some way. data contents With HTML Templates. including the use of sample data to document your template. such as the rows from a database query. You can effectively build your constructs “in place” and visualize your specification by viewing the HTML Template file in a browser window. You also have to consider how to render sections of repeated elements. In XML data. Containers: vertical vs. these correspond to “containers” and “leaves. you know the exact values you want to display. not the actual values. 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. In Page Automation.” Sometimes a container represents an element that is repeated. 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). all elements of the name pattern: <anything>Container are always emptied out before they are used by Page Automation. there are complex data elements and simple data elements. When you are creating an HTML Template. you are instructing Page Automation: “IF the data is shaped like this. and you only need to be concerned with how to lay them out. and you construct the JSP page with this shape in mind. Data shape vs.Furthermore. You know the “shape” of your data.” The shape of data: containers and leaves XML provides a good metaphor for the shape of data. you think of the data more abstractly. Page Automation uses the “vertical” or “horizontal” attribute in determining various aspects of the generated HTML. you are yet another degree of abstraction removed from the data. A vertical display mode container is considered to be either a Display Group or a Data Entry Group. When creating a simple HTML page. • • A horizontal display mode container is considered to be a Table. horizontal Containers have a display mode attribute that can be either “vertical” or “horizontal”. Page Automation knows the shape of the data as the application is being generated. When you are creating a JSP page. This enables you to nest your construct definitions the way you logically think about the hierarchy and containment you want. THEN create HTML (and ultimately. . you handle your data at a fairly high level of presentation abstraction.

This HTML is then used to generate the JSP for the page. While the Construct Reference Table defines what is legal for each construct. even if they aren’t used. For each of these. constructs are in bold and construct elements are in parentheses. And you should include constructs for all types. you should provide constructs for all the types of data shapes that will appear in your application. it isn’t possible to define all legal combinations and permutations. It is important to arrange constructs so that they will produce legal HTML when they are applied by Page Automation to your data. Examples of common patterns This section illustrates a few simple but common patterns. but the Model developer can change the display mode for any page data by using the Data Field Modifier Builder. since it doesn’t hurt and the application might change in the future. In the following examples. HTML generation based on data shape The Page Automation code constructs HTML based on the shape of the data it is processing.Containers are assigned a default display mode. 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. and by following the rules that you have given in your HTML Template. There are a relatively small number of ways that data can be arranged (see the Construct Reference Table).Field . 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.

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 1.

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 .Figure 2.

The fourth column lists which other constructs (if any) each Container construct can contain. Table 1. depending on where the construct occurs.(DataContainer) ColumnData Figure 3. 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 . 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. Using TableWrapper with ColumnGroups HTML Template constructs The Construct Reference Table lists all the constructs that the Page Automation code expects.

.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. *4 ColumnGroups is an advanced topic. You can safely put “sample” text in them. but it must surround the associated DataContainer *3 These are all text or control elements. 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 DisplayGroup’s DataContainer may contain DisplayFields or DisplayGroupWrapper *2 RepeatElement is not a Container.

for example. and . where the column headers are the labels of the container’s child elements. there are two grouping constructs: Group Wrapper and Group. which are all leaves. 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. and the column contents (typically repeated) are the data of the container’s child elements. Containers with display mode “none” are not shown. The vertical groups (Display and Data Entry) Every container is assigned a Display mode attribute: vertical. a Data Entry Field requires four pieces be placed on the page: label. The horizontal groups (tables and columns) The most common display for display mode horizontal is a table. The most common group that gets horizontal display mode is a Row from a database query. or none. you specify each of these locations within the construct by your placement of these elements. the element named “DataContainer” locates the children of that container.Elements within the constructs For each construct. The most important difference between the Table construct. required indicator. Display vs. This section describes the way various modes are handled. Group Wrapper vs. When Table is used. label and data) and Data Entry fields (often 4 columns). For example. DisplayGroup. It is typically repeated data. as if you were simply repeating one order. the elements listed define the location of the important things for that construct. horizontal. Repeated “Vertical” Data There are instances when vertically displayed data has a repeat pattern. the entire page is considered to be a Data Entry page. containers with display mode “horizontal” are treated as Tables. For a Data Entry Field construct. and validation error message. and DataEntryGroup is the way the immediate children of the container are handled. and its immediate children are the columns. Data Entry An entire page is treated as either Display or Data Entry. Group For both the Display Groups and the Data Entry Groups. You can appropriately align a mix of Display Fields (often 2 columns. If there is a single Data Entry field on the page. a list of orders where each order includes a table of items. You can display this list of orders one above the other. For all container constructs. This enables flexibility and efficiency in managing multiple kinds of groupings. containers with display mode “vertical” can be either Display Groups or Data Entry Groups. data control. labels of the children are put in one section (TableHeaderContainer).

html. By controlling which construct is selected with some simple rules. ColumnarStyles This Template is identical to Columnar. value. then Page Automation will use the ColumnHeaderSorted construct. Controlling which construct is selected Within a single HTML Template file. The constructs to use for these children are ColumnHeader (or ColumnHeaderSorted) for the labels (headers) and ColumnData for the data. PageWrapper creates a TABLE tag without rows or columns. Sample HTML Templates Portlet Factory includes several sample HTML Templates that produce typical presentation layouts. you can specify a completely different HTML Template file as Builder input for specific places in the Page Automation contents tree. If sorting properties have been put on a column by the model author. validation error message). in one of three ways: 1. You control the use of these additional choices by adding qualifiers to the construct name. Based on the data type of the data element for which the construct is being selected 2. except that it uses styles directly rather than using HTML classes and a style sheet. Based on the control type of the element 3. required prompt. The benefit of this template is that all the columns will line up. you can achieve rich layout that looks hand-crafted. The power of HTML Templates is hidden in this ability to be as specific as you need to be. but is actually fully automated. You might find it useful to start with the sample that most closely resembles what you are trying to achieve. but with the expectation that there will be four columns. Page Automation will create the TD tags. if your application does this (or you can rely on the defaults.html. (label. Therefore. you need to provide an HTML snippet for sorted columns. even across groups. of course). In this template. . you can have multiple instances of the same construct but in different patterns. and you do not have control over the style sheet that is being included in the page. Based on the specific name of the element In addition. Each Element on the page is expected to start with a TR tag.the data of the children is placed inside the DataContainer. Columnar The default HTML Template in the Data Page Builder is Columnar. This can be an advantageous when your page is being displayed in a portal. as necessary.

but the ultimate savings in time is worth the investment. Thumbnail Grid This special Template transforms a long list of compact objects into an array of objects. the Page Automation subsystem will be able to consistently generate the design you want. presenting a shadowed appearance. Labels are above the elements. . Sample templates provided with the product can help get you started.LabelAbove This HTML Template is useful when the page is being fit into a narrow space. 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. There is a learning curve to become familiar with the constructs used to specify how data should be treated. This DIV tag has thicker right and bottom borders. DropShadow This Template is similar to LabelAboveStyles in that each DisplayGroup and DataEntryGroup gets its own DIV tag. so that. Conclusion The use of HTML Templates in Portlet Factory can give you complete control over the layout and look of your data. even if your application or data changes. both in the Display and in the Data Entry pages.

com Steve Zagieboylo is a software architect in Workplace. or both. other countries. He came to IBM from the Bowstreet acquisition. Windows and Windows NT are registered trademarks of Microsoft Corporation in the United States. other countries. Massachusetts.ibm. You can reach Rose at rodonnell@us.com/developerworks/websphere/zones/portal/proddoc. or both.ibm.ibm. Trademarks • • • DB2. Tivoli.com/developerworks/websphere/zones/portal/ developerWorks WebSphere Portlet Factory forums http://www. She came to IBM from the Bowstreet acquisition.com.html WebSphere Portlet Factory product documentation http://www. or both.com/developerworks/websphere/zones/portal/portletfactory/proddoc. in the United States. Lotus. szagiebo@us.jsp WebSphere Portal product documentation http://www. Inc.com/developerworks/forums/wsdd_forums. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems. Rational.htm l WebSphere Portlet Factory product overview http://www.ibm. Massachusetts. IBM.ibm.com/software/genservers/portletfactory/ WebSphere Portlet Factory support http://www.com/software/genservers/portletfactory/support/ About the authors Rose O’Donnell is a manager in Workplace.Resources developerWorks WebSphere Portal zone http://www. He has been the principal designer and implementer of the Page Automation capability in Portlet Factory.ibm.ibm. .ibm. Portal and Collaboration Software in Westford. other countries. and WebSphere are trademarks or registered trademarks of IBM Corporation in the United States. Portal and Collaboration Software in Westford.

phtml . product.ibm.• Other company. IBM copyright and trademark information: http://www. and service names may be trademarks or service marks of others.com/legal/copytrade.