Customizing your generated UI

Added by

Garry Sager | Edited by IBM contributor

Craig Lordan on September 10, 2012 | Version 26

Edit
More Actions ▼

Abstract

This article with the accompanying sample shows you how to use IBM Web Experience Factory to customize your applications UI using the latest builders and themes.

Tags: Code Samples, User Interface

Prerequisites

You should have a basic familiarity with Experience Factory and be able to create and run models.

Introduction to Customizing generated UI

This sample will show some common methods you can use to customize the UI that is generated by our wizards and high level builders. It will talk about how to control the overall look and feel of your pages and techniques to customize fields at a page level. Here are some of the techniques and builders illustrated in this sample, Themes, Data Field Settings, Data Field Merge, design view modifications, exporting the complete page for customization.

Sample description

The sample is a simple sales order model that displays orders and the contacts for those orders. The base models were built using our best practices with a service provider and consumer. The consumer model was built using the Data Services UI Consumer model wizard. The initial model ServiceOrders and the customized model ServiceOrdersCustomized are both included in the sample so you can see what was added and how it changed the pages.

Techniques illustrated in this sample

Customization Technique	Where used
Adding action columns to your UI.	Data Services User Interface builder SalesOrderConsumerDSUI added delete and edit operations to the view page.
Changed layout and css for model	Theme builder clean_label_above updated the model to use WEB-INF/factory/themes/clean_label_above.uitheme
Changed base pages to add buttons to top and bottom of page	Theme builder clean_label_above updated the Details, Update pages to have buttons at bottom and top
Control field UI and behavior	Data Field Settings builder All Pages updated the fields on all pages to look and behave correctly
Merging fields to enhance the layout of the fields for display	Data Field Merge builder AddressMerge merged the address fields for layout on the view page
Custom Layout Template with CSS for Data Layout builder	Data Layout builder Four Column Show/Hide List updated the view page
Design view customization of layout	Display Manager builder SalesOrderConsumerDSUIDetailDispMgr updated the Details page builder SalesOrderConsumerDSUIUpdateDispMgr updated the Update page
Custom HTML	Imported Page builder SalesOrderConsumerDSUICreate replaced the complete Create page

Understanding the different ways that the UI can be customized.

Controlling the UI: page layouts

Overall page layout is controlled with imported HTML pages

Fields can be moved and grouped using drag and drop in Design view
Field layout, grouping, and visibility can be controlled with builders

Data Column Modifier, Display Manager, Data Hierarchy Modifier, Data Field Modifier

For complete customization of field layout, use a custom layout page with named tags for the fields in a schema

Use “Export HTML for Data Layout” command to automatically create HTML file with named tags
Iteratively modify the HTML file using an HTML editor to position fields as desired

Adding action columns to your UI.

Our high level UI builders have optional inputs that allow you to automatically generate columns and methods to perform actions on the rows of your list.

We wanted to allow the user to be able to delete and edit records from the list view so we enabled the inputs in the DSUI builder that created these columns. These inputs are List Page to Update set to Add a column with links to jump to update and Add Delete Column on List Page to Add a column with "Delete Records" links.

Controlling overall style and look with themes.

Themes allow you to centrally control and modify the look and feel of an entire application:

CSS styles

“Smart refresh” and page loading progress indicators

Page layouts

Table and form layout rules (HTML templates)

Table highlighting and paging controls

A theme can be applied for a model, or automatically for a whole project

You can also override theme elements at any level with the Theme builder

One of your design decisions is at what level you want to customize your models within the project. Is it at the project level where all models within the project are affected or only an individual model. We wanted to change the UI to minimize the colors and move the labels above the edit fields to help minimize the width of the forms. To do this in this sample we added a theme builder to the model and will use clean_label_above.uitheme that gives us the look we want.

Updating base pages to customize the look and layout of your pages.

We wanted to change the pages that are generated to have buttons on the top and bottom so that the user wouldn't have to scroll the window to get to the buttons. We did this by updating this theme builder inputs to update the base DSUI builder pages to reference the pages we created that add the buttons to the top of the form. These pages were created by copying the existing base pages into the projects pages directory and adding these tags to the top of the page

"vf_buttons" name="vf_buttons"

"cancel_button"

"submit_button"

Control field UI and behavior automatically with Data Field Settings

From a single Data Field Settings builder, you can easily control the appearance and behavior of all the fields in an application

For each field, you can control labels, visibility, column sorting, validation, field type (drop-down, checkbox, rich text editor, date picker, etc.), and more

We wanted to enhance the users data entry ability and we also wanted to change the labels of some of the field. We updated the Data Field Settings builder to do this, the field Customer ID we changed to display as Customer # and the field Name we changed to display as Contact. We updated the field type for field Amount to be Currency , State to be a Select with a look-up table, Phone to be a Phone Number, Email to be an E-Mail Address and Description to be a Rich Text Editor field.

Merging fields to enhance the layout of the fields for display.

The Data Field Merge builder lets you merge fields so that they are presented as a single field and lets you merge columns so that they are presented as a single column.

For this model we had we wanted to display the fields Address, City, State and Zip that we wanted to display as a single column within the list. We added a Data Field Merge builder and added the separators to format these values to be displayed as
Address
City State, Zip

Creating Data layouts to facilitate the use of your custom UI patterns.

The Data Layout builder is a great way to transform the grid style tables generated by the Page Automation builders (Data Page, View & Form, and DSUI) into alternate list layouts that are suitable for viewing on Desktop, Mobile, and Tablet devices.

For this page we were looking at a layout design that we could use on many of our list views. We looked at the existing data layout templates and none exactly matched the pattern that we wanted, so we decided to create our own template. In this case the Multi-Line Show/Hide List template was close to what we wanted so we decided to copy the template and style sheet to the projects data_layout_templates directory and updated it to have the extra columns we wanted within the layout. We also modified some styles removing the width and height from the img selector and added some new classes that allowed for us to have vertical separators for our fields. We then added the data layout builder to the list view and selected which fields we wanted to be displayed and where. Some of the locations within the layout were targeted by image builders to add the needed images. The styles to control the layout of these images were added within the data layout builder to control the spacing around the images.

Using the design view to customized data entry pages.

The design panel in the model editor shows a visual representation of a visible element that is selected in either the Application Tree or the Pages panel. Clicking the Design tab exposes the Design panel. This panel lets you quickly and conveniently see visible elements in your model without having to generate the web application and lets you make design changes. It supports the adding and manipulation of builders and their inputs allowing a user to modify field layouts and attributes. This view allows you to add high level layouts( two column, T layout, Inverted T and I layout) or use drag and drop to rearrange the layout of your fields on the page. All changes are stored as inputs to builders and are dynamically applied at generation time.

For more information on design view customization [Using the design view to customize your data layout].

For the details and update pages we wanted to change the layout of the form to an I layout with the customer # on the top then the order information and contact information in there own sections in the center and followed by the description field. We did this by selecting the I layout from the palette and dropped it on the list. This splits the fields into the 2 center sections. We selected the fields and dragged them to the sections we wanted them in. We then added the group labels for Order Information and Contact Information by right clicking on the groups and selected the Edit Group Label menu item from the Layout tools.

Exporting the complete page HTML to customized the creation page.

Exporting the HTML

, but other HTML can be changed as you wish. It's important to note that after creating this page making theme changes specific to the base pages and templates will have no affect on these pages.

For this model we exported the create page and customized it to look completely different from the details and update pages, but this time we did the editing of this page using the HTML editor and not the design view. We've also added comments throughout the HTML of the page to outline some of the changes we did with the HTML editor.

Instructions for running the sample

To run the sample application:

1. Create a project or use an existing project.
2. Download the gettingstarted_customized_samples ZIP file and import it into the project using File > Import> WebSphere Portlet Factory Archive command.
3. Open one of the models found in WEB-INF\models\samples\gettingstarted_customized and run it. These models will run out-of-box without any configuration required.

Resources

Data Layout builder help (describes the Data layout template file format)