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"
Many times, developers are satisfied with the user interface generated by Web Experience Factory, or can achieve the look they desire by tweaking the generated user interface using modifier builders like Data Field Settings or Data Field Modifier, or by using CSS style sheets to change the appearance. However, in cases where a particular look is required that does not fit well with the automatically-generated user interface, you can gain full control of your application's appearance by using custom HTML to replace parts or all of a particular page.
The two main ways to override the Factory's HTML with your own are:
• 1. specifying custom HTML to replace that generated from the data by the page automation system
• 2. supplying new “base pages” for use by high level builders such as 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 technology of the Factory 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 DUSI and View and Form. Part of the power of Page Automation is that it starts by creating an internal model of how the data will be laid out on the page, and then 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 is focused 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.
One of the features of the Page Automation system is that you can completely take over the creation of the HTML which makes the framework for the JSP page that Page Automation will create. This 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 it means hand-edited work for each page on which you use it, and that page has now lost 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 is optional, as you could also start from manually-coded HTML)
2.Hand-edit the HTML, retaining the important named elements
3.Cause your new hand-edited version to be used instead of the generated HTML
In typical cases Web Experience Factory can automate steps one and three above.
Note that there may be cases where you are given HTML – perhaps built by a professional user interface designer – to serve as your application's user interface, and this HTML may not have been built using the above process, i.e., having 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 two main options:
1. Export the HTML from the Factory and then “match up” the designer-provided HTML with the exported HTML, modifying the exported HTML so it has the desired appearance
2. Use the provided HTML as the basis for your application directly
If you choose #1 above, then the techniques in this document can be followed as shown. If you choose to use the provided HTML directly, then you will want to see the document (TBD) 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, then right-click on the element 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 on the “Row” group:
This right-mouse menu choice will extract the selected HTML and bring up a dialog allowing you to save this HTML as a file in your project. You'll want to save this file in the folder that you've chosen to store your HTML files – the default 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's builder call list. This builder pulls the exported HTML back in and causes it to be to be used in place of the automatically-generated HTML that page automation would have created for the specified area.
Editing the Exported HTML
Note again that this exported HTML is simply the structural basis for your page's display, not the output that your application will deliver 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 will import this page, examine it for named elements that match the fields in the associated data, and then invoke builders that target these named areas to generate the display and behavior code. You are free to modify the exported HTML as you see fit so long as you maintain the named elements that you wish to preserve. If you remove the named element corresponding to a data field, that field will not be present in the generated display – this may be beneficial if that is what you intended. Please see 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've exported the HTML as above using the “Export HTML for Data Layout” right-mouse command from the design view, then there is no additional step needed to pull your modified HTML back in and use it: as noted above, that command will have created an HTML Data Layout
builder call in your model. If you are using completely hand-built HTML or have 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 Data Services User Interface (DSUI) and View & Form are normally specified by the Web Experience Factory theme, and so can be controlled at several levels.
• You can make a custom theme that specifies new values for one or more base pages – this will change the base pages for every model that uses that theme
• A Theme builder call can be placed at the top of a model, and new base pages can be specified using the corresponding builder inputs – this changes the base pages within that model
• To override a base page in a particular builder call, you can uncheck the “Use Theme” builder input; this will expose a number of inputs including those to control the base pages * * note that View & Form requires special care when unchecking the Use Theme input because the newly-exposed inputs will not be populated with the values from the current theme – you'll need to specify these 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. When you do this, you can either build your single HTML file and then break it back into a base page and a data page to be fed back to HTML Data Layout, or you can use the combined base/data page as-is by simply using it as a base page. Using a merged base/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 will only be able to apply it to a specific DSUI / View & Form instance.
The base pages for DSUI use an element named “data_placed_here” into which the data-driven elements will be placed, while the View and Form builder's base pages use an element named “data” for this purpose. To merge customized data-driven page page area HTML with the base page, you would simply replace this named tag with your customized HTML.