Prerequisites

You should have a basic familiarity with Web Experience Factory, HTML and styles. You should also know how to create and run models. You'll need to add the User Interface/Mobile feature to the project. Import the Theme_Demo.zip file into your project.

Related Article
Creating your applications UI This article and related articles describe a number of techniques for constructing your applications user interface and page layout.. It describes many of the elements that are controlled by the theme such as HTML templates, style sheets (CSS), base pages, highlighting style, and paging style.

Themes and user interface control This product documentation tells you how you can use themes to specify and control the appearance of the user interface (UI) in Web applications.

Introduction to Themes
Let's start by including the help topic Themes and user interface control. This topic give a good overview on how to use themes and is available as a related concept help link in topics where themes are used.

Samples

This project includes models that show different ways working with themes and the different ways you can use them to customize your applications at a very high level. The models are designed to easily show the technique they are illustrating and are kept simple. The ones that include profiling illustrate how you would use profiling to control the theme behavior in a multi-channel environment.

First lets start with a very simple model /models/samples/themes/SalesOrders that was built using the list and detail service consumer model wizard. It contains a service consumer, view and form, and data field settings builder. You will notice there are no theme builders included in the model. So how could this model be affected by a theme? As we can see above in the Project-level theme support and the Builder-input theme support, the View and Form builder has an input that allows it's inputs to be based on the theme that is currently in affect. In this model that would be the project based theme that we set in the override.properties configuration file. So why would I set the value in the override properties file and what should I be setting it to? This setting would best set to the most common theme that you would use within the project, so you wouldn't have to add individual theme builders into models and you could affect many models with the single change. So is this always my desktop theme? It might be, but what you should be doing is figuring out the most commonly used theme for models in this project and use that theme as the default. So for example if the project is not targeting multi-channel applications but mobile only devices, then it would be your mobile theme you would use set in the override properties file. The theme I choose to use in this project was my new desktop theme WEB-INF/samples/themes/desktop.uitheme . This theme extends a clean theme that was added for the 8.0 release . In this theme we wanted to override the base pages /samples/pages/dsui/create.html and the style sheets /samples/pages/clean.css that were defined in the extended theme. So what can you override in a theme? You can override any part of the extended theme by redefining the value for any of entries in that theme or values that it had inherited from the theme it extended, so basically any theme property can be set in a theme and it will be the value used in models using this theme. One use of a theme for a project is to not only add item definitions to a project but to remove or redefine items that we define. For example, for your portlets, you might want to use portal styles that were defined in the portal theme and not the styles we defined in our style classes. You can define css files that are empty so the styles that are used by page automation are not defined and the elements on the page will use the portal theme's definitions based on the css selectors defined in the portals page. Another common use of a project based theme is customizing base pages and styles to use corporate standard colors, icons, layouts and button placement.

The next sample we will talk about is the /models/samples/themes/SalesOrdersTablet and WEB-INF/samoles/themes/tablet.uitheme. This model illustrates the ability to have themes that are derived from the your own theme and also using the theme builder within a model to affect that model only. In this model we wanted to use the theme we defined for the project theme to be the base and then update the base pages for the pages to change the default layout of the View and Form created pages. If we were creating a theme to be used as a project level theme we would probably override more properties so we could have consistent look and feel for applications that were View and Form or Data Service User Interface based. Notice that we added the Theme builder before any builders that create page automation builders - this is very important if it isn't a warning is generated and it's not obvious which parts of the theme will affect which pages in the model. We start by defining tablet theme to extend the desktop theme we defined . Next we define only the components we want to update within this theme which in this case are the base pages for View and Form and the Input Page. You will note that we didn't update all theme properties, but only the ones we wanted, and the other properties for this theme are inherited from the extended theme or it's parent theme on up. The best way to see what theme properties are currently set for the model is by using the application tree view in the designer.

You can see the values of all the current theme settings for this model and can navigate to the files by clicking on the link. You can then modify the files and these changes will be reflected in the generated model. Some things to be careful of are to never modify any files in the /factory directory as product upgrades will overwrite your changes. Remember that files that are not in the factory folder could also be referenced by other models in the project and if you create your own feature package for your theme it would also be true that you wouldn't want to modify the file in the project but modify it in the features file so the value will not be overwritten when the feature is refreshed. Also remember that class definitions of styles for portlets are shared on the portlet page so if you have different models that define a named style differently in different style sheets all portlets that reference that named style will use only one definition.

Next we will take a quick look at using profiling to control the themes for different devices. The model we are using is model /models/samples/themes/SalesOrdersProfiled_Theme and the profile set is profiles/ProfiledThemes. To create this theme we opened the theme builder in the builder call editor and clicked on the profile button for the theme file. That opens this dialog box

from here we choose the Create Profile Set button and created the ProfiledThemes profile set duplicating the mobile_devicetype_base profile set. We do this so we have the that we want multi-channel profiles defined and then we create the profile entry Theme_ByDeviceType which we use for this input. We set the default profile entry to the desktop theme we created, Then set the Smartphone value to our mobile theme and the Tablet value to our tablet theme. Notice that there are profiles for different devices so we could have created entries for specific devices if we want. So why create a new porfile set? Well if you just added an entry to an existing profileset like mobile_devicetype_base it would be removed when the project was upgraded, so we create our own profile set that is based on the mobile_device_type profileset and create our own profile entry. By profiling this input the model will generate different look and feel for the application that is device specific. We then profiled a couple other page modifier builders to change other non-theme based UI modifications.

Next we will look at a model /models/samples/themes/SalesOrdersPhone_Light_Theme that uses a theme that changes lot's of style definitions so that your mobile application uses light text on dark backgrounds, /WEB-INF/samples/themes/mobile_light_on_dark.uitheme. Since this theme is designed for mobile applications it extends the base mobile theme . The theme properties that are defined within this theme are all the page automation style properties. By doing this any pages that are created using page automation will now all use the same definitions for named styles. One interesting note on this style sheet was that when I originally used it and navigated to an update page the fields appeared blank, so I spent time trying to figure out how I messed up the data for the input fields. Then it occurred to me that the input field background color and the text color were both white. So the data was there I just couldn't see it, so I selected the text in the blank looking input and there the text was. So just a word of warning when updating named styles check your pages in both read only and edit modes.

Override theme properties

So why would I override theme properties instead of creating my own theme files? One reason would be you would like to override a limited number of properties in an existing theme as a limited change for a single model. Another reason is you want to change the default rdd file for your mode - this is something I have used in a mobile application where the theme's rdd did not support the displaying data from rich text fields the way I wanted. I was displaying the field in a text area instead of a rich text editor for performance but that meant the HTML tags in the rich text were displayed. So I created a new rdd file that was based on the mobile rdd file /WEB-INF/samples/data_definitions/basic_mobile_rich_text_datadef.xml. I added a control builder base_RichText and it's definition

Rich Text Editor
Rich Text Editor for input
com.bowstreet.builders.webapp.TextAreaBuilder


virtual
25
5



false

ContentFilterTranslate


and then referenced it in the override part of the builder inputs.
The sample model /models/samples/themes/SalesOrdersOverride has a theme builder that has been overridden. The inputs that were overridden were the Default rdd file and all the style sheet reference inputs. The style sheet that I used for these references was created using this builder by choosing the Create combined style sheet button found near the bottom of the builders input page. When you press this button, all the style sheets that are currently referenced by this theme are combined into a single style sheet file /samples/mobile/themes/mobile_override.css. Now one thing to note, doing this creates the combined file but DOES NOT update any of this themes references to that style sheet. You could do this yourself. By not updating these fields you can use this with existing themes to generate the combined style file to be used as a basis for a new uitheme file. The combined file includes comments about the original files that were combined

/* Sheets Written */
/* /factory/html_templates/mobile/mobile_buttons.css*/
/* /factory/html_templates/mobile/mobile_gray_buttons.css*/
/* /factory/html_templates/blue_buttons.css*/
/* /factory/html_templates/gridtable_blue_WPF7.css*/
/* /factory/html_templates/mobile/details_template_styles.css*/
/* /factory/html_templates/mobile/mobile_table.css*/
/* /factory/html_templates/mobile/mobile_portal_override.css*/
/* /factory/html_templates/mobile/mobile_gray.css*/
/* Sheets Written */

/* Inserting /factory/html_templates/mobile/mobile_gray_buttons.css */
/** Copyright IBM Corp. 2011 */
/* Inserting /factory/html_templates/mobile/mobile_buttons.css */

Now when you want to work with styles they are all in one file which improves performance and makes it easier to update styles that you want to be consistent.

Next steps

So we now have created a our new themes and have tuned them to work exactly as we would like. But how could we use these files in another project? If we use them in more than one project how do we keep them up to date? Well the best way to handle this in Web Experience Factory is to take your theme files and the files they reference and create a feature set out of them, and also include this profile set if you are using profiles and themes. This gives you the ability to add them to any project you want. And also provide the ability to update these files in projects that contain the feature by using the projects feature property page to refresh the feature after you have updated the feature package files. This gives you a way to know that the themes are all consistent, which for style definitions on portal is very important. And a way to update the layouts and styles in many projects by just refreshing the theme package you created. There are a couple of good articles on creating your own features.

• How can I make a set of custom builders available to other developers and projects?
• Creating a Feature Set