What are page automation templates?

Page Automation HTML templates

There is a default HTML template which is very useful for rapid prototyping and simple pages. However, when you want to achieve a specific look and feel for your generated pages, you can create your own HTML template and use this approach to format multiple application pages with little or no hand-crafting.

Why use an HTML template?

You can control the automatic generation of HTML by using HTML template files that guide the actions of the page automation builders. This control greatly reduces the need to hand-craft the look and feel of each individual page. To create your own HTML template, copy of one of the master templates that come with the product and edit it.

Use one HTML template for all pages in an application to achieve a consistent look and feel or use different templates for different pages or sets of pages. You use HTML templates in conjunction with imported pages (Imported Page builder) for content layout, graphics and non-generated artifacts. You can also use them with style sheets.

When to use an HTML template?

The amount of control you want to exert over the look of the application will vary depending on your situation. In some cases, auto-generated HTML will be just fine. In other cases, you might want 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:

The structure of automatically generated HTML templates

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 you 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:

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

16 basic constructs

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: Names are case sensitive.

Constructs include the following:

• DisplayPageWrapper
• DataEntryPageWrapper
• TableWrapper
• TableLabel
• Table
• ColumnHeader
• ColumnHeaderSorted
• ColumnData
• DisplayGroupWrapper
• DisplayGroup
• DisplayGroupLabel
• DisplayField
• DataEntryGroupWrapper
• DataEntryGroup
• DataEntryGroupLabel
• DataEntryField

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.

Adding 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 tag to which you 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 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"> 

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.

You 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>

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

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. You can add text in the places where text will eventually go in the finished page, so that you can see, in the template page, what it will look like.
   

HTMLWRAPPER tags

The HTML templates provided by IBM® WebSphere® Portlet Factory include tags around some of the markup.

This is part of the XML markup of the model. The tag is used to contain elements of the page to which you 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

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"> 

    <SPAN name="LabelText">Table Label</SPAN> 

   </TD> 

  </TR> 

</HTMLWRAPPER> 

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

Qualifying a construct by field control type

You can also qualify the DataEntryField and the DisplayField according to the control type that will be used to display them, using the qualifier _ (including the underscore).

For example, if 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, but when the input element is a text area, 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 name

To create a construct for a specifically named node that you know is going to appear in your data, use the qualifier.

This always gets the highest precedence. For example, if 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 can create a construct named TableByName_Order which will be used only for the container named "Order".

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

Note: 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). You can use the autodelete type qualifier with ColumnHeader or ColumnData constructs: for example, ColumnHeader_autodelete.

How Themes and HTML templates can work together

The default theme for a project provides a convenient way for you to specify HTML template files in your application.

HTML template files describe the formatting for all constructs generated by builders in the application. Using a theme, you can control HTML template use at the project level and in individual models. An input (Use Theme) in the following builders lets you invoke HTML template files based on the project default theme.

• Data Page
• Input Form
• View & Form

If you do not use a theme in those builders, use inputs (HTML Template File) to specify HTML template files for different page types. These specifications of HTML templates can 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 overrides the corresponding specification for that construct in the HTML template file.

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

You can also override a template file with the Data Hierarchy Modifier builder. In this case, the override does not affect the containers that were selected. Only new group containers that the builder creates are affected. This is a common reason to use the Data Hierarchy Modifier: so that you can quickly create new groups with an entirely different display style.

Page automation example: adding spacer rows to a table

By changing only the template, you can add spacer rows anywhere in a table: before the header, between the header and the data, before or after each data row, and after the entire table.

This example has far too many spacer rows. Notice that it uses a Construct Name Qualifier of ByName_PhoneNumber so that this construct will only apply to a container with the name PhoneNumber.

The important step for adding spacer rows before and after the data rows was to separate the RepeatElement from the DataContainer. In the basic template, the DataContainer element of the table construct was not specified, so it defaulted to the same XML node as the RepeatElement. In this example, we want to repeat more than just the data row, we want to repeat around a section that includes the data row and the spacer rows. This is accomplished by adding a tag which acts as the repeat element, and adding the

<tr>

for the DataContainer within it.

Note: All of the containers are left empty. This is because this overrides only the table construct, and the system will continue to use the ColumnHeader and ColumnData constructs that are already defined in the template. The (rather hideous) result of this addition to the basic template is beside it.

<table name="TableByName_PhoneNumber"> 

<tr><td colspan="100"> 

--- spacer row above header --- 

</td></tr> 

<tr name="TableHeaderContainer"></tr> 

<tr><td colspan="100"> 

--- spacer row below header --- 

</td></tr> 

<span name="RepeatElement"> 

<tr><td colspan="100"> 

--- spacer row above each data row --- 

</td></tr> 

<tr name="DataContainer"></tr> 

<tr><td colspan="100"> 

--- spacer row below each data row --- 

</td></tr> 

</span> <!-- end Table.RepeatElement --> 

<tr><td colspan="100"> 

--- spacer row below entire table --- 

</td></tr> 

</table> <!-- end Table construct --> 

Page automation example: changing page layout based on control type

Often you will want to change the layout for a field based on the control type. The most common situation is that you want any field which is edited using a textarea get the entire width of the screen for the textarea, even though the other fields are using only the right-hand portion for their edit devices.

With the following change to the basic template, plus a Data Field Modifier builder on the Comments section which tells it to use a textarea for editing, we get the desired results. For comparison, the normal Data Entry Field construct is shown here along with the qualified one.

<tr name="DataEntryField">

<td class="label"><span name="FieldLabel">Sample Field Label</span></td>

<td><span name="FieldRequired">*</span></td>

<td><span name="FieldElement">Sample Field Element</span></td>

<td><span name="FieldValidationError">Sample Validation Error</span></td>

</tr>

<span name="DataEntryField_textarea">

<tr>

<td class="label"><span name="FieldLabel">Sample Field Label</span></td>

<td><span name="FieldRequired">*</span></td>

<td></td> <!-- Leave empty so Validation column lines up. -->

<td><span name="FieldValidationError">Sample Validation Error</span></td>

</tr>

<tr><td colspan="4">

<textarea name="FieldElement" cols="40" rows="10"></textarea>

</td></tr>

</span>