Page Automation HTML Templates

 

In this topic ... Benefits Provided by HTML Templates How to Invoke a Template Template Structure and Constructs Alternating Styles Adding Elements Related Topics ... Page Automation Template Examples

The Data Page builder, along with the other Builders that use Data Page, can automatically generate HTML for displayed pages. You can control the look and feel of the generated HTML by using Page Automation HTML Templates.

There is a default template, of course, and it is highly useful for rapid prototyping and simple pages. However, if you want to achieve an exact look and feel in your generated pages, we can provide your own HTML template. This approach allows you to format multiple application pages with little or no hand-crafting.

 

When to Use an HTML Template?

The amount of control you want to exert over the look of the application varies, depending on your needs and choices.  In some cases, auto-generated HTML will be adequate for your needs. In other cases, you might a more sophisticated look and feel for your pages than what is available by default from the page automation system.

In general, you have several options to choose from when it comes to page formatting:

• Let system determine page look and feel - We can use Data Page and its associated Builders to generate all the HTML needed for an application.  This insulates you completely from changes and ensures that, if the data driving your application changes, your pages will reflect the changes automatically.

• Create a base page and stylesheet - If you want your own look and feel we can add a base HTML page and a style sheet to get some control over the way that page looks. Used in conjunction with Data Modifiers this will give you control over many of the elements on your page.

• Hard code HTML tags - If you want complete control over the look of the application we can also hard code individual tag names into an HTML page to control the display of all items on the page. This approach can be tedious and we can end up tied to the underlying data. In addition, you are not taking advantage of the Data Page builder's page generation capabilities.

• Use an HTML Template  - This approach represents a great middle ground and provides two major advantages: HTML Templates offer you a lot of control over individual page elements and HTML Templates also allow you to exploit the Data Page Builder's ability generate the bulk of the HTML code.

 

Benefits Provided by an HTML Template

The HTML template files provide instructions to the page automation Builders and allows you to control the automatic generation of HTML. This control greatly reduces the need to hand-craft the look and feel of each individual page. To create your own HTML template, you make a copy of one of the master templates that come with the product and edit it to get the effects you want.

We can use one HTML template for all pages in an application to achieve a consistent look and feel or you may use different templates for different pages or sets of pages. HTML templates are used in conjunction with imported pages (Imported Page Builder) which provide content layout, graphics and non-generated artifacts. They may also be used with style sheets as desired.

 

How to Invoke an HTML Template

The Data Page Builder provides a "Template File" input we can use to specify an HTML  template file that describes the formatting for all constructs generated by the Builder. These specifications can also be overridden by other builders at any level in the Page Automation hierarchy of contents, such as a Data Field Modifier or a Data Column Modifier. There is a hierarchy of action associated with the formats: more specific references override more general (global) settings. Thus a Data Field Modifier specification for a Field or Container Node will override the corresponding specification for that construct in the HTML template file.

When a template file is specified for a Container, it also will be used for all elements within that container, unless it is further overridden at a lower level.

We can also override a template file with the Data Hierarchy Modifier builder. In this case, the override will not affect the Containers that were selected. Only new Group Containers that the builder creates will be affected. This is a common reason to use the Data Hierarchy Modifier: so that we can create new groups with an entirely different display style.

 

HTML Template Files and Example Models Available

The HTML template files and their matching style sheets are located in the directory factory\html_templates. Available HTML templates include:

• columnar.html - Creates a basic, 4-column display and is intended to go with the style sheet template_compatible.css

• horizontal4columnar.html -  Used in conjunction with  columnar.html. Allows you to take a few values and display them across the page on a single  line. The technique is to use a Data Hierarchy Modifier to put these values in a separate group, and assign the correct horizontal template at the same time.  A classic place to use this technique is with the values City, State, and Zip, which can usually fit across in the same space as a line of address.  The example uses this technique.

• prompt_above_input.html - This is useful when you have a narrow space on the screen in which to put your form, the labels are immediately above the input fields or the text elements.  It works well with the style sheet template_compatible2.css.

• horizontal4prompt_above.html - Used in conjunction with prompt_above_input.html. Allows you to take a few values and display them across the page on a single line.  The technique is to use a Data Hierarchy Modifier to put these values in a separate group, and assign the correct horizontal template at the same time.  A classic place to use this technique is with the values City, State, and Zip, which can usually fit across in the same space as a line of address.  The example uses this technique.

The example HTML Template models are available in a project when the "Tutorials and Samples - Applications" Feature Set is installed in the project.  These sample models are located in the project's WEB-INF/models/samples/datapage directory. HTML Template example models include:

• LabelAbove.model  - Uses the prompt_above_input.html template for input and output pages

• LabelOnLeft.model - Uses the columnar.html template for input and output pages

These models are based on the HTML templates listed above. Each model uses a different  template, and respective horizontal template, to group the City, State, and Zip inputs on to a single row. Each model has a link to the other model, so we can compare the different looks that are created.

We can also click here to view some examples of how an HTML Template can be edited to achieve a particular effect.

 

HTMLWRAPPER tags

The HTML templates provided by WebSphere Portlet Factory include <HTMLWRAPPER/> tags around some of the markup. This is part of the XML markup of the model. The <HTMLWRAPPER/> tag is used to contain elements of the page to which we can apply other builders. This tag is used in place of standard HTML tags in places where HTML markup would not allow a tag, for example, between a <table>

and a <tr> tag. When the page is transformed to JSP, these tags are removed, leaving valid HTML markup.

The following is an example of how this tag is used around a table row in the columnar.html template.

<HTMLWRAPPER name="LabelContainer"> <TR name="TableLabel"> <TD colspan="4" class="TableLabelCell"> <SPAN name="LabelText" class="TableLabelText">Table Label</SPAN> </TD> </TR> </HTMLWRAPPER>

For custom HTML, we can use this tag around elements that you intend to attach with builders. Be sure to provide a unique name on the name attribute.

 

Auto-Generated HTML Template Structure and Constructs

Pages generated by the Data Page Builder have a common structure that is based on constructs. A construct is a building block of a displayed page. By changing an HTML master template we can alter the way a construct displays a page element. Each construct is composed of sub-elements that define its content. For example, some basic page constructs include:

Table

   Wrapper

   Label

   Title

 

Column

   Header

   Header sorted

   Column data

 

Display Group

   Wrapper

   Label

   Group

 

Field

   Display field

   Data entry field

The system provides HTML master templates that include all the constructs that are generated by the Data Page builder. Typically, you will create derivative HTML templates from these master files. By editing the sections of the HTML template that define the constructs of interest, we can control how page elements are displayed.

 

Constructs

Each HTML template file is composed of constructs. A construct describes a specific portion of page HTML that the Page Automation system generates. There are 16 basic constructs that constitute a generated page.

The HTML template file contains examples of HTML for each of these constructs. The HTML will applied to the resulting page as needed. The example HTML is identified using the name attribute.  For example:

<td name="ColumnHeader_int" align="center" class="label">

              <span name="HeaderElement"></span>

            </td>

A construct always starts with the XML element that contains the name attribute that matches the construct name ("ColumnHeader_int"),  with or without qualifiers appended.  Note that names are case sensitive.

Constructs are listed below and described in detail in a later section. Constructs include...

• DisplayPageWrapper

• DataEntryPageWrapper    

• TableWrapper

• TableLabel

• Table     

• ColumnHeader

• ColumnHeaderSorted     

• ColumnData         

• DisplayGroupWrapper

• DisplayGroup

• DisplayGroupLabel    

• DisplayField         

• DataEntryGroupWrapper

• DataEntryGroup

• DataEntryGroupLabel    

• DataEntryField

 

Construct Name Qualifiers

Inside an HTML template file, we can have several different examples of each named construct. In each case, the system will choose the most specific example for a given construct. It does not matter what the order of construct specifications is within the HTML template file. In order of precedence, qualifiers are based on:

1. Name of the element

2. Control type that the element is using (Fields only)

3. Type of the element.

Qualifying a Construct by Container / Field Name

To create a construct for a specifically named node that you know is going to appear in your data, use the ByName_ qualifier.  This always gets the highest precedence.  For example, suppose you know that your data contains a repeated element named Order and you want to use a non-default table layout for that table, you could create a construct named TableByName_Order which will be used only for the container named Order.

Qualifying a Construct by Field Control Type

We can also qualify the DataEntryField and the DisplayField according to the control type that will be used to display them, using the qualifier _<control name> (including the underscore).  For example, suppose that your normal Data Entry field layout is to have 4 columns containing the label, the required prompt, the input element, and the validation error, respectively.  However, when the input element is a textarea, you would like, instead, to use two rows, where the first row has the label, the required prompt, and the validation error, and then the second row contains a single column (with colspan=4) which holds the textarea element.  In this case, you would specify the normal DataEntryField construct with the name  "DataEntryField," and then create another construct named DataEntryField_textarea.  

Qualifying a Construct by Container / Field Type

In some cases, you might want to change the display of certain elements based on the type of the element. For example, you might normally have column heads and column data left-aligned. However, if the data type is double you would like to center-align the column head and right-align the data.  You do this by creating a construct name with the qualifier _<type name>.  For the example above, you would have the normal ColumnHeader and ColumnData constructs, then you would add two other additional complete  constructs with the names ColumnHeader_double and ColumnData_double.

Special Type: autodelete

There is a special type name, "autodelete," that is applied to automatically generated columns created in the Data Column Modifier and which provide the Delete functionality.  This type is applied to all delete columns, no matter what type of delete column choice was selected (Link, Button or Checkbox). We can use the autodelete type qualifier with ColumnHeader or ColumnData constructs:  for example, ColumnHeader_autodelete.

 

Data Entry vs. Display

All of the constructs except Table can be divided into two groups, Data Entry and Display.  This distinction is always made on a page-wide basis. In other words, if there are any Data Entry fields on the page, then the entire page is considered to be a Data Entry page, and every selection of a construct will be made.

 

Fitting Constructs Together

The critical part of building your own template is understanding how the constructs fit together.  You have to specify the different elements so that, when they are fitted together, they will result in  valid HTML. There are two features that make this process easier:

1. Inner constructs can be created in place, that is, inside the elements where they will eventually be placed by the Page Automation engine.  The rule is that any Container element will be emptied before it is used.

2. We can add text in the places where text will eventually go in the finished page, so that we can see, in the template page, what it will look like.  

Below is a table of all the fundamental construct names and the named XML elements that are valid within each construct.  These XML elements appear within the XML of the construct itself.  Both the construct name and the inner element names are specified using the HTML NAME= attribute.  

Note that only construct names can have qualifiers. Inner names must be exact, and are case sensitive. Many inner name elements end with "Container".  All of these elements will be emptied before the construct is used, which means that we can create, in place inside the container, the constructs that might go inside it, without ruining it.

Fitting constructs together mirrors the rules that apply to building well-formed HTML. An important consideration when fitting constructs together is that all examples of the constructs that might go in a particular container must be built with HTML that will fit correctly.  For example, if you make your DisplayPageWrapper such that the PageContentsContainer within it is a <TABLE> tag, then the constructs TableWrapper and DisplayGroupWrapper should start with a <TR> tag, or, perhaps, with a <SPAN> that contains <TR> tags.  You can make several different versions of the TableWrapper tag, with different qualifiers, but they all should be crafted to fit within all versions of the DisplayPageWrapper and the DataEntryPageWrapper constructs.

Elements marked with (opt #) are optional.  The "opt" number designates the policy used to handle the case where these optional elements are missing.  See the table below for descriptions of the four policies.

Construct Names and their Inner Elements

Construct Name	Inner Elements	Contains Constructs
DisplayPageWrapper	PageContentsContainer	TableWrapper DisplayGroupWrapper
DataEntryPageWrapper	PageContentsContainer	TableWrapper DataEntryGroupWrapper
DisplayGroupWrapper	LabelContainer (opt 1) |see notes below GroupContainer (opt 2) *	DisplayGroupLabel DisplayGroup
DisplayGroup	RepeatElement (opt 4) DataContainer	DisplayField
DisplayGroupLabel	LabelText (opt 1)
DisplayField	LabelText (opt 1)
DataEntryGroupWrapper	LabelContainer (opt 1) GroupContainer (opt 2) *	DataEntryGroupLabel DataEntryGroup
DataEntryGroup	RepeatElement (opt 4) DataContainer	DataEntryField
DataEntryGroupLabel	LabelText (opt 1)
DataEntryField	FieldLabel (opt 1) FieldElement (opt 2) FieldRequired (opt 1) FieldValidationError (opt 1)
TableWrapper	LabelContainer  (opt 1) GroupContainer (opt 2)	TableLabel Table
TableLabel	LabelText (opt 1)
Table	TableHeaderContainer  (opt 1)   RepeatElement	ColumnHeader ColumnHeaderSorted
ColumnHeader	HeaderElement (opt 2)
ColumnHeaderSorted	HeaderElement (opt 2)
ColumnData	DataElement (opt 2)

• Opt. 1:  If this element is not present, then the entire element, plus anything it would have contained, will be skipped.  For example, to make a Table with no header row, create a Table construct without any TableHeaderContainer element.

• Opt. 2:  If this element is not present, it will default to the primary construct node.  For example, a ColumnData construct might consist of just the HTML <TD name=ColumnData_text></TD>.  In this case, there is no contained element named DataElement, so it will just use the ColumnData XML node as the DataElement.

• Opt. 3:  Within a Table construct, if the DataContainer element is missing, it will default to the RepeatElement.  Therefore, we need only make these inner elements separate if you want to repeat something more than just the data element (such as a spacer row between data rows).

• Opt. 4:  Within a DataEntryGroup or a DisplayGroup construct, if the RepeatElement is missing, it will default to the DataContainer.  Note that this is the opposite of how these inner elements work inside a Table construct.  This reflects the relative importance of the inner elements to the construct: because a Table nearly always contains a repeat section, the RepeatElement is considered to be more important in Tables;  However, for DataEntryGroup and DisplayGroup, which usually do not repeat (though they can!), the DataContainer is considered to be more important.

* Note that if you allow the GroupContainer to default to the construct node for the DisplayGroupWrapper or the DataEntryGroupWrapper, then this will have the effect of wiping out the LabelContainer, if there is one.  This is because the GroupContainer, being a container, is always emptied before the construct is used.  Therefore, if you want to use the LabelContainer, then explicitly specify a GroupContainer as a separate, inner element.

 

Alternating Styles (and classes) for Table Rows

Often, in creating an HTML table, you want to have alternating styles for the rows  to make the table easier to read. We can build this functionality into an HTML template. On any XML node for which an alternating attribute is desired,  simply prefix the attribute name with sequence_ (with the underscore) and list the different values for the attribute in a comma-separated list.  

For example, in a <TR> tag, to alternate between the HTML class names TableRowOdd and TableRowEven add the following:

<tr  sequence_class="TableRowOdd,TableRowEven">

...                 

          </tr>

This technique has the identical effect as adding an attribute sequencer on the node, selecting the class attribute, and supplying those values for the sequence.  You can apply the sequence_ prefix to any attribute, so you could define the style directly. For example:

<div  sequence_style="background-color:white,background-color:cyan">

...                 

          </div>

 

Add Elements to a Template

Sometimes you will want to use additional Builders which will operate on HTML generated by the Page Automation code. For example, you might want to include an Add Row button for a table, that enables the end-user to add a row.  You would like to include an extra row at the bottom of the table which contains a named <span> tag to which we can attach your Button builder.  Furthermore, the Table template that you are using might be used elsewhere on the page, so you want to be able to make sure your Button builder targets exactly the right <span> tag.

The way to accomplish this is to create an XML node inside the construct that has a name that starts with an underscore.  For example, you might make an element

      <span name="_AddButton">

The system will rename this element when it uses the construct, by pre-pending the name of the container or field that was being rendered when it chose this construct.  In this example, if the above span appeared inside the Table construct and was used to create the PhoneNumber table, that node would be changed to the following span on the page, making it perfect for attaching a Button Builder.

<span name="PhoneNumber_AddButton">