The XPages Blog

When writing sample XPage applications I tend to use the oneUI theme that is distributed as part of the IBM Lotus Domino server, the main reason being that it can make the sample applications look good while reducing the size of the NSF file.

When it comes to creating your own internal applications you may not want to use oneUI as it contains a LOT of CSS that you may never even use so that will mean you need to build your own style sheets that will include layout stylings, font settings and color schemes. Fortunately you don't need to start from scratch, there are a couple of CSS frameworks that work well with XPages and it's very easy to create a theme document for them.

The main CSS Frameworks that I have been looking at are Blueprint ( Modified MIT License & GPL License ) and Tripoli ( GPL License ) and a merging of the two, plus some bits from a few others, called BlueTrip ( GPL License ). When selecting a CSS framework one of the important things to look at is if it uses ID's to apply it's styles or if it uses classes. As XPages dynamically changes the ID's of elements rendered to a web browser you will need to use a CSS Framework that only deals with classes. You can quickly determine this by opening the CSS file and if you see any #'s at the start of a style definition then you know it's using ID's so avoid that particular CSS framework for use in XPage applications. So far I have found that the YahooUI ( BSD Licensed ) uses some ID's for layout controls so it it probably a bad choice.

Once you have picked the CSS Framework that you want to work with adding it to your application is very easy. In your Domino Designer client got the Resources -> Style sheets section in your NSF file and import the CSS files that are part of the framework. In Blueprint these consist of screen.css, print.css and ie.css. The main file, screen.css, will reset the browsers css to basic settings so that all browsers start with the same defaults, it then contains settings for standard elements like check boxes, input fields, buttons and fonts so that these elements will appear the same across any browser and lastly it contains a grid layout system that you can read about on the Blueprint website. This grid system is where a framework like blueprint will save you a lot of time.

The other two files are not necessarily needed, ie.css contains special css hacks so that some of the framework will work in Internet Explorer 6, if your not planning on supporting that browser then you should just leave it out entirely. print.css contains special css definitions that are only applied if a web page is printed. Currently in Xpages there is no way to specify the media type for a CSS file that is added either as a resource on the XPage or via a theme so it is probably best to leave this file out also but if you don't mind editing the css file you can wrap the css in an '@Media print{}' rule to work around this current limitation. Your theme document will look something like this when finished :

<theme>

<resource>
<content-type>text/css</content-type>
<href>/screen.css</href>
</resource>

<resource>
<content-type>text/css</content-type>
<href>/print.css</href>
</resource>

<resource rendered="#{javascript:context.getUserAgent().isIE(0,6) == true}">
<content-type>text/css</content-type>
<href>/ie.css</href>
</resource>

<resource>
<content-type>text/css</content-type>
<href>/application.css</href>
</resource>

</theme>

The extra theme reference to application.css would be your own custom css resource where you will add in all your own layout and color schemes for the application. As you can also see I am using the rendered= method to make sure the css for Internet Explorer 6 does not get sent to Firefox or other web browsers.

Using a CSS framework can help you cut down on some of the more basic parts of building your XPages web application. If your not interested in using the grids portion of blueprint then even it's reset and standardization sections will ensure that all browsers start on a level playing field.

In the last part of this series I showed you how to add <control> sections to your theme document so that default properties could be set for different controls that you add to your XPage application. I also mentioned that you can override the default properties by manually adding in your own properties to the control.

If you have written any XPage applications yet you will probably have seen the 'All Properties' section for each control where you can manually set the styleClass and whatever other properties are exposed but there is one property that I have yet to see anybody talk about and that is the 'themeID'.

Lets say you have decided that you are going to use 'Link' controls with the 'lotusBtn lotusBtnSpecial' outerStyleClass, that is part of the oneui theme, for all the action buttons in your application. You would not want to create a special <control> section in the theme file for the link control because it would apply to all link controls on your page. Instead you can define your own control name like this

<control>
 <name>Link.Action</name>
 <property>
 <name>outerStyleClass</name>
 <value>lotusBtn lotusBtnSpecial</value>
 </property>
 </control>

Now in your application when you add a link control that you want to be an action button, instead of having to remember the different style classes that you need to use you can set the themeID property to 'Link.Action' and the XPages renderer will be able to work out what properties to set by looking at the theme file.

Using Themes In XPages Part One
Using Themes In XPages Part Two 

In the last part of this mini series I showed you how to add basic resources to a theme document but I also mentioned that when you use themes you need to keep a cheat sheet handy because the class names are not listed in the styles property tab for any control.

There is, however, another feature of theme documents that can make things easier by automatically applying style classes to certain controls.

Lets say you have written some CSS that you want to use on all the 'Pager' controls in your application. You could manually add the style names to the styleClass property each time you add a pager to your application or you can use the theme document by adding a control section that looks like this

<control>
 <name>Pager</name>
 <property>
 <name>outerStyleClass</name>
 <value>myPagerContainer</value>
 </property>
 <property>
 <name>styleClass</name>
 <value>myPager</value>
 </property>
 </control>

The name of the control your are specifing the properties for is in the name tag. There are a lot of controls and even sub controls that you can include in here from the simple controls like 'link' or 'text' or 'button' to the more advanced ones like 'PagerControl.Pager.First' or 'DataTable.ViewPanel'. next we define the property that we want to manage using a <property> tag and inside that tag we specify the name and value. In most cases the name of the property that we want to manage will be 'styleClass' but as you can see in my example about there may be other properties like 'outerStyleClass' or 'selectedTabStyleClass' ( which you'll find in a tabbed panel control).

If you are extending a built in theme like oneui that the theme document may already have a <control> section for the control you are setting up your default properties for. Under normal circumstances extended themes are merged in with your theme but you can override this by adding an override attribute to the control tag like this

<control override='true'>

The control override will ensure that your control property definitions take precidence and none of the property definitions from the theme you are extending will bleed through into your application.

So what happens if you manually add a value to the styleClass property in your XPage? Well under normal circumstances the value manually specified overrides anything that may appear in the theme document for that control. So if you have a control property for buttons setup so that all buttons in your application look the same but you need to put in a special button using a different style you still can. This behaviour, however, can also be overridden in the theme document by adding a 'mode' attribute to a property tag like this

<control>
 <name>ViewRoot</name>
 <property mode="concat">
 <name>styleClass</name>
 <value>tundra</value> 
 </property>
 </control>

here I am using 'mode="concat" to make sure that the Dojo style call of 'tundra' is added to every Xpage. The control name 'ViewRoot' is equivilent to the <body> tag in the generated HTML.

In the next part I'll show you how to create special controls and how to apply them in the design of your XPage application.

Using Themes In XPages Part One

When developing XPage applications you have two options for adding CSS style sheets to your code. You can attach them directly to the XPage or Custom Control resources section or you can create a theme document and reference them from there.

Adding the style sheet directly to the Xpage or Custom Control does have some advantages. The list of classes will appear in the styles section for all the controls on that page which will make selecting them a little easier and the 'design' perspective for the XPage will try and apply the styles so you get a better idea of how the page will look when it's rendered in the browser. It's not perfect but it can help.

Creating a theme document, however, allows you to build different sets of style sheets so the person deploying your application can easily change the look and feel of the application by selecting which theme to use. As an example you could have different color based themes. The disadvantage is that the list of classes in the CSS file(s) won't display in the styles section for each control so you need to have some sort of cheat sheet to help you remember them and the design perspective won't render the controls with the css.

A theme document is just an XML file within the notes database. You'll find them in the Resources -> Themes section of the designer client. The basic structure of a theme document looks like this :

<theme extends="webstandard">
<resource>
<content-type>text/css<content-type>
<href>stylesheet.css</href>
</resource>
</theme>

The first thing to note is the opening <theme> tag. As you can see you can decide to extend one of the builtin XPages themes. When the 'extends=' attribute is added to the theme tag the Xpages renderer will first process and add all the resources from that theme before processing your theme resources. The built in themes are 'webstandard', 'oneui', and 'notes'. If your not extending one of the built in themes then you can leave this attribute out completely.

Inside the theme tags you have resource tags. The resources can be style sheets as in the example above but it's also possible to add other resources, you just need to change the content-type as required by the resource type. You can have as many resource sections as you need for your theme.

The resource tag can also contain a 'rendered' attribute like this

<resource rendered="#{javascript:context.getUserAgent().isIE(0,6) == true}">

In this example the rendered attribute is running some server side javascript to determine which browser is being used. If it is Internet Explorer versions 0 thru 6 then the resource is rendered to the web browser, if your using higher version of IE or a different web browser then the resource does not get sent to the users web browser. This is a great way of adding special stylesheets that contain hacks for some of the behaviours of CSS in earlier versions of IE.

In the next part of this mini series I'll show you how to automatically add certain style classes to controls using a theme document.

Using Themes In XPages Part Two