Modifying Your Application's Appearance Using Custom HTML

This is one in a set of articles about creating your application's UI. The main article in this series is Creating Your Application's UI

Other articles in the series are:

Approaches to UI Design and Layout
Using the design view to customize you data layout
Writing Page Automation friendly HTML and styles

---

Modifying your application's appearance using custom HTML

This document describes one set of steps related to the overall customization of your application's appearance. For an overview of this more general task, please see the document entitled "Creating Your Application's UI".

Most often, you are satisfied with the user interface that Web Experience Factory generates. If you are not satisfied, you can achieve the desired look. Either use modifier builders like Data Field Settings and Data Field Modifier to tweak the generated user interface or use CSS style sheets to change the appearance. However, if you require a particular look that does not fit well with the automatically generated user interface, you can use custom HTML to replace parts or all of a particular page to gain full control of your application's appearance.

The main ways to override the generated HTML code with your own are:

• Specify custom HTML to replace that generated from the data by the page automation system.
• Supply new “base pages” for use by high level builders (for example, Data Services User Interface and View & Form) to lay out the non-data elements such as buttons.

These techniques can be used together or separately, as your needs demand.

Managing the layout of data-driven pages managed by Page Automation

Page Automation is the Factory technology that builds both JSP pages and Java code based on a schema or other data definition. The core access to this technology is the Data Page builder, which can also be accessed through high level builders such as Data Services User Interface and View and Form. Part of the power of Page Automation is that it starts by creating an internal model of how the data is to be laid out on the page. You can use assorted modifier builders, such as Data Field Modifier or Data Column Modifier, to change the internal representation before the actual work of creating the JSP and Java occurs. This document focuses only on the different techniques you can use to manage the layout of the JSP pages to get the eventual HTML result that is desired.

With the Page Automation system, you can completely take over the creation of the HTML that makes the framework for the JSP page that Page Automation creates. This ability has both benefits and limitations. The benefit is that you can control precisely how the resulting page will look, while still using Page Automation to generate the Java code that manages the flow of data (including validation). The disadvantage to this approach is that hand-edited work is required for each page on which you use Page Automation. Additionally, that hand-edited page loses the flexibility to modify itself if there is a change in the schema, query, or service upon which the page is based.

There are several steps you have to go through to manage this process.

1. Export the desired page area's HTML structure, as automatically generated by page automation. (This step is optional, because you can also start from manually-coded HTML. )
2. Hand-edit the HTML and retain the important named elements.
3. Cause your new hand-edited version to be used instead of the generated HTML.

Typically, Web Experience Factory can automate steps one and three above.

Handling of externally supplied HTML

Often you are given HTML to serve as your application user interface. The HTML is perhaps built by a professional user interface designer. This HTML may not have been built using the above process. It could have been hand-coded from scratch or built in a visual design tool without being based on HTML exported from the Factory. This document does not address this situation directly. In this case, you have the following main options:

• Export the HTML from the Factory and “match up” the designer-provided HTML with the exported HTML. Modify the exported HTML so that it has the desired appearance.
• Use the provided HTML directly as the basis for your application.

If you choose the first option above, the techniques in this document can be followed as shown. If you choose to use the provided HTML directly, refer to the document Writing Page Automation friendly HTML and styles for additional tips on how to deal with this situation.

Exporting the HTML

To export the current HTML structure of a particular data-driven area on a page, first navigate in the design view to the page in question. Right-click the element that you wish to modify and select Export HTML for Data Layout. For example, to customize the detail display in the “Orders Service Consumer” sample, you would choose the “uiDetails” page, and then right-click the “Row” group.



This right-mouse menu choice extracts the selected HTML and displays a dialog in which you can save this HTML as a file in your project. Save this file in the folder that you chose to store your HTML files. The default location is the “pages” folder under WebContent.

In addition to exporting the HTML for the selected region, this command also adds an HTML Data Layout builder call to your model builder call list. This builder pulls the exported HTML back into the model. The HTML is used in place of the automatically-generated HTML that Page Automation would have created for the specified area.

Editing the exported HTML

The exported HTML is simply the structural basis for your page display and not the output that your application delivers to the browser. In particular, neither the data nor any code to display the data is yet present in the exported HTML. Also not included are any behavior-related scripts. Page automation does the following with the exported HTML page.

• Imports this page.
• Examines the page for named elements that match the fields in the associated data.
• Invokes builders that target these named areas to generate the display and behavior code.

You can modify the exported HTML as you see fit if you maintain the named elements that you wish to preserve. If you remove the named element that corresponds to a data field, that field will not be present in the generated display. This condition may be beneficial if that is what you intend. Refer to the document “Writing Page Automation friendly HTML” for details on these named elements and how they are used by Page Automation.

Using the modified HTML in place of the generated structure

If you exported the HTML as above using the “Export HTML for Data Layout” right-mouse command from the design view, there is no additional step needed to pull your modified HTML back into the model and use it. That command created an HTML Data Layout builder call in your model. If you are using completely hand-built HTML or exported your HTML in some other way, you can manually add this builder call to achieve the same effect.

Modifying base page HTML

The base pages used by the Data Services User Interface (DSUI) builder and the View & Form builder are normally specified by the Web Experience Factory theme. These base pages can be controlled at the following levels.

• You can make a custom theme that specifies new values for one or more base pages. This theme changes the base pages for every model that uses that theme.
• You can place a Theme builder call at the top of a model and specify new base pages by using the corresponding builder inputs. These actions change the base pages within that model.
• You can uncheck the Use Theme builder input in a particular builder call to override a base page. This action exposes a number of inputs, including those to control the base pages.

Note: The View & Form builder requires special care if you uncheck the Use Theme input because the newly-exposed inputs are not populated with the values from the current theme. You need to specify these inputs yourself.

Merging base pages and data-driven page areas

Sometimes you may want to customize the base page and data-driven area together as a single HTML file. If you do this, you can do one of the following:

• Build your single HTML file and break it back into a base page and a data page to be fed back to the HTML Data Layout builder.
• Use the combined base page and data page as-is by simply using it as a base page. Using a merged base page and data page like this has the drawback that a base page normally is applied globally using a theme. If the base page has data-specific elements in it, you can only apply it to a specific Data Services User Interface builder and View & Form builder instance.

The base pages for a Data Services User Interface builder use an element named “data_placed_here” into which the data-driven elements are to be placed. Similarly, the View and Form builder base pages use an element named “data” for this purpose. To merge customized data-driven page page area HTML with the base page, simply replace this named tag with your customized HTML.