XPages OneUIv2 Theme Deep Dive

Lance Spellman | President, WorkFlow Studios

Agenda

What's an Xpages theme?

Discussion Database Demo

Trying different out-of-the-box themes

Extending themes with your changes

What's an XPages theme?

Themes are powerful design elements that control overall layout of Domino web applications. With themes, you can give all your web applications a consistent look and feel, and include corporate branding.

Themes are much more than styles. They can include various style sheets and can also override/ specify individual control's look and feel. For example, in a theme you can specify a particular style class for all submit buttons in your application.

And last but not least: you can define multiple themes within an application, and then simple switch between themes via the application properties:

Discussion Database Demo

The 8.5.2 Discussion template is based on the OneUIv2 theme

Preview the database http://127.0.0.1/discussion.nsf

In Application Properties in Domino Designer, go to the XPages tab

By default, the Application Theme is blue

Try changing to red and reloading the page

Discussion Db Theme Choices

Theme Options

Can be server-wide by specifying a server default

Can be application specific

Can even be XPage specific

Dissecting a theme, finding all the files on the server

Using Server Default Theme

For Discussion Db, change theme to Server Default

Preview the page

Ouch!

Server Default: Where does it get set?

The server looks for an xsp.properties file in data\properties directory

If found, it looks for the entry xsp.theme.web

If blank, it looks for the entry xsp.theme

If the xsp.properties file doesn't exist, or the entries don't exist, then the webstandard theme is applied as shown below

Set a theme for Server Default

In data\properties there is a xsp.properties.sample file

Make a copy of it named xsp.properties

Edit the file and uncomment the #xsp.theme=webstandard toxsp.theme=oneuiv2

Save the file

Tell http quit on the server console

After http's shutdown, issue load http on the server console

Preview the page again

Results...not so good?!?

Look at the source

Theme was applied, the appropriate css files are shown as loading

The screen background is blue, so oneuiv2 is doing something

Why doesn't the rest of the page look better?

Theme extensions

This database originally was set to use the blue theme and it worked with that. blue extends oneuiv2, apparently in a big way.

Before looking at blue theme...

Let's identify where the domino server is getting oneuiv2 and webstandard themes from

Look in the domino\xsp\nsf\themes directoryThere you find all the .theme documents includingoneui.theme (8.5 and 8.5.1)

oneuiv2.theme (previewed in 8.5.1 and supported in 8.5.2)

webstandard.theme

Open the oneuiv2.theme with WordpadResources are declared there with paths like/.ibmxpress/domino/oneuiv2/base/core.css

The /.ibmxpress/domino directory is mapped by the Domino server todata\domino\html directory

Under the html directory is the oneuiv2 folder with all the CSS files

Where's the Blue theme?

Go to Resources and Themes within the database

In the list of themes, blue is one of them

Open it and see that it extends oneuiv2

Dissecting the Blue Theme

Change to Design mode

In addition to all the resources provided by oneuiv2, there are additional resources provided by the blue theme

The blue.css file referenced here is found in the Resources Stylesheets folder of the application

Change the Navigator colors

I like the blue theme, but I really don't like the green navigator

Use Firebug to select the navigator element

Find out what element it is, and what styles are being applied to it

The green box turns out to be an element with this class.xspPanelNavigationMenuTop

Make the Navigation Box Pretty

Well, beauty's in the eye of the beholder, right?

Before going and changing any code anywhere, try it in Firebug firstHelps verify you are working with the right element

Lets you try out different settings and tweak without code change/save/refresh

Add a New Resource to the Blue Theme

Copy the first resource section and paste it in BELOW

Change the filename in the pasted version to custom.css

Why below?We are going to overwrite some class definitions

The resources are read in order

With our class definition read last, it will take precedence over earlier definition

Create a new Custom.css file

In Resources Stylesheets, create new Stylesheet

Name it custom.css per the resource definition we just added

For the classes we identified in Firebug, we create our re-definition

The navigation box was class .xspPanelNavigationMenuTopHere's how we redefined it

Notice that we only overwrote the 1 property we were interested in. The other definitions for the class remain intact

Other Class Overrides

For the Menu Items and Selected Menu Items, made the background and border red

For the text of the menu items, changed them to black

Redefining controls

In the theme file, you can also define a default class for a control

For example, if we wanted all the buttons to have a certain appearanceCould overwrite the css class

Could define a different css class altogether for the control

We've done the first, let's try the second

Open the Custom Control actionsBar

Select the New Topic button

Go to the Style tab

For the Theme field, type button.cool

Save and go back to the blue theme file

Adding a Control Definition

In the blue theme, there are lots of control definitions. Copy one and paste at the end of the file (but before the ending )

Change the name to button.cool

Change the styleClass value to coolButton

Save

Update custom.css for coolButton

In the custom.css file, we now need a class definition for coolButton

To be really big and Web 2.0, we'll make a big green button

Here's the class definition we came up with and what it looks like

Refactor and create our own theme

Instead of mucking up the existing themes and css, we'll extend

We create a new theme called WFS

Extend blue

Move custom.css from the blue theme

We want to leave the blue theme in it's pristine state, so any mods we'd made there, we're moving out.

Move the resource definition for custom.css from the blue theme and put it in the new WFS theme

Move control definition

Take the button.cool control definition from the blue theme over to the WFS theme

Get rid of custom theme id

To make the theme transferable with no code changes to the base app, we need to get rid of theme id of button.cool on the New Topic button that we added earlier

How to determine a control's theme id

We can apply our cool button style globally to all buttons of this type in the application by changing the styleClass definition for the existing button controls

This requires that we know what the control's theme id is

Some are relatively easy to determine and some aren't

You can use code to get the component's StyleKitFamily

Put the value in a scope variable

Put a computed field on the page bound to the scope variable to reveal it

Defining styleClass for Button.Cancel

After previewing the page, it turns out the New Topic button has a theme id of Button.Cancel

In the WFS theme, replace the Control definition name from coolButton to Button.Cancel

Theme Independence Achieved!

We've set Blue theme back to its original state

We've setup a new theme, WFS, that defines a custom stylesheet

We have a new styleClass definition for all buttons that are of type Button.Cancel

We have a custom.css stylesheet that contains the coolbutton style changes

We now have another theme choice for our application

Set the application property theme choice to WFS

We can choose between themes at the application property level and go back and forth without any other changes needed to the application

Questions?

Resources

There's a lot of great information on the XPages Blog

By searching for all items with tag of theme, there are 5 good articles availablehttp://xpagesblog.com/xpages-blog/tag/themes

Lotus User Interface documentationhttp://www-12.lotus.com/ldd/doc/oneuidoc/docpublic/index.htm

Article in the Domino wikihttp://www-10.lotus.com/ldd/ddwiki.nsf/dx/Create_a_website_layout

My Delicious bookmarkshttp://www.delicious.com/lspellman/xpages+themes

Legal Disclaimers

WorkFlow Studios 2010. All Rights Reserved.

The information contained in this publication is provided for informational purposes only. While efforts were made to verify the completeness and accuracy of the information contained in this publication, it is provided AS IS without warranty of any kind, express or implied. WorkFlow Studios shall not be responsible for any damages arising out of the use of, or otherwise related to, this publication or any other materials. Nothing contained in this publication is intended to, nor shall have the effect of, creating any warranties or representations from WorkFlow Studios or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software.

References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. Product release dates and/or capabilities referenced in this presentation may change at any time at IBMs sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. Nothing contained in these materials is intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth or other results.

IBM, the IBM logo, Lotus, Lotus Notes, Notes, Domino and Lotusphere are trademarks of International Business Machines Corporation in the United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Dissemination or reuse of this presentation is allowed provided full attribution to WorkFlow Studios is made by retaining the title slide and this legal disclaimer slide in their original form.

Click to edit the title text format

Click to edit the title

Click to edit the outline text formatSecond Outline LevelThird Outline Level