Your Development & Design Resource

CSS for IBM Notes and Domino XPages Developers

Cascading Style Sheets (or CSS) is a style language that enhances or can outright override the native Web and Mobile Browser rendered representation of HTML markup. Mastering CSS will enable you (browser-willing) to completely control the user interface and user experience of your applications.

In this article, we'll cover CSS Selectors and Media Types... but let's start first with a fundamental review of CSS, exactly what CSS is doing in a browser, and how CSS works with HTML and JavaScript via frameworks.

Getting Started

HTML Elements typically display in one of two ways: block and inline. The most frequent examples of a block vs. inline HTML elements are DIV and SPAN elements (respectively).

HTML Elements are rendered by a web browser with a native style. For example, an H1 Element will be a large font-size, bold, and display as a block-type element.

Sadly, browser rendering engines (or layout engines) will interpret a given HTML Element differently. Internet Explorer will have different font-size, margin, and padding for an H1 Element when compared to Firefox which itself differs from the rendering from Chrome and Safari.

This can cause headaches for user interface design, but luckily most applications and websites use the general rendering of given HTML Elements as a starting point before the CSS takes over.

CSS can be used to enhance or flat-out override the rendering of a given HTML Element.

Using CSS

CSS and styling can be applied to an HTML Element in various ways:

  • via the HTML Element's style attribute.
  • via a <style> Element in the HTML <head>.
  • via a stylesheet <link> Element in the HTML <head>.

While many of you may be tempted to use the HTML Element's style attribute (see example below), don't do it...

While this technically works, it's bad practice for two reasons:

  1. Maintainability
  2. Size and Caching

Not only will you have to go into your HTML Element any time you want to make a design change, but you won't gain any benefits of caching and you'll miss the opportunity to deliver smaller markup to your browser clients.

While that first option (Maintainability) should make the case for you, it's really the second (Size and Caching) that should drive the point home: in the world of smartphones and tablets hitting your applications, you'll want to deliver a fast solution which means smaller package size and leveraging caching whenever possible.

Pretty much the same reason that the <style> option is out too.

Which leaves us to creating a caching-friendly external stylesheet for our CSS.

CSS Selectors

Now that we understand why we're creating an external stylesheet, we have to understand how we can use CSS on our HTML Elements.

While it's not the purpose of this article to deep-dive into every single method that can be used to select a given HTML Element, let's review some of the basics.

  1. You can select an HTML Element by the tagName.

    This CSS rule will affect any h1 HTML Element.

  2. You can select an HTML Element by className or ID.



    These CSS rules do the following:

    1. Applies a color rule to the h1 and h2 Elements based on their tagName.
    2. Applies a font-size rule to any HTML Element that has an ID of "header1".
    3. Applies a font-size rule to any HTML Element that has a className of "heading2".

    It's important to point out that non-tagName'd elements that have the ID "header1" or className "heading2" will be affected by the above CSS rules.

    There are times when you want to use tagNames for IDs or classNames, and times when you do not.

    For example, if you're dealing with a className that's intended to highlight/mark a given HTML Element, you'll want to stay away from tagNames.

  3. Walking DOM HTML Elements for pin-point application of CSS rules.

    Let's take a look at the following HTML Table Element:

    Some developers may use the following syntax to style, for example, the Table Header and Body Cell Elements (TD) via CSS:

    The problem with this syntax is that this will apply to any TD descendent inside of the columns3 Table. In other words, if you add another Table HTML Element inside one of the columns3 Table cells, it too will set a width of 33% for any cells within.

    To avoid this, we'll walk the Table HTML Element to get handles on the Table, the Table Header (thead) and Table Body (tbody) rows and columns and use our CSS to apply specific style and formatting rules:

    What you're left with is the following HTML Table, styled via the above CSS:

  4. CSS2 and CSS3 Selectors

    These selectors allow you to use any value for any attribute of an HTML Element.

    Let's take a look at a demo application that I'm putting together which uses the Dojo dijit.layout.BorderContainer control. Specifically, I'm using the Extension Library (ExtLib) XPages xe:djBorderContainer Control, but this will work just as well if I used a core xp:div Control or even a standard HTML DIV Element.



    The above CSS affects only an HTML DIV Element whose attribute "dojotype" is set to "dijit.layout.BorderContainer" which is the immediate child node of an HTML DIV Element which has a className of "lotusContent" and has an attribute named "role" which is set to "main", setting the height and width of said BorderContainer to 100%.

    Check out the CSS2 Selectors spec for more syntax examples.

CSS Media Types

The last thing in this CSS Primer that we'll want to cover is CSS Media Types.

As mentioned, CSS can manipulate the rendering of an HTML Element. With Media Types, you can set what CSS is applied based on the target platform or state.

Let's take a quick look at the different Media Type options available:

Media Type Description
all Suitable for all devices.
braille Intended for braille tactile feedback devices.
embossed Intended for paged braille printers.
handheld Intended for handheld devices (typically small screen, limited bandwidth).
print Intended for paged material and for documents viewed on screen in print preview mode.
projection Intended for projected presentations, for example projectors.
screen Intended primarily for color computer screens.
speech Intended for speech synthesizers. Note: CSS2 had a similar media type called 'aural' for this purpose.
tty Intended for media using a fixed-pitch character grid (such as teletypes, terminals, or portable devices with limited display capabilities). Authors should not use pixel units with the "tty" media type.
tv Intended for television-type devices (low resolution, color, limited-scrollability screens, sound available).

Media Type information from

By not specifying a Media Type in your CSS, you're specifying all. However, the vast majority of your enterprise application development work will be with the screen, handheld, and print devices and states.


There are 3 ways to specify a media type for CSS:

  1. @import

    You can use the @import to include external CSS stylesheets into your current stylesheet by specifying them at the top of your stylesheet. I strongly emphasize at the top as any CSS (or comments for that matter) that sit above the @import will break the import.

    Here's an example of what your style.css CSS might look like:

    This would import the layout.css and forms.css stylesheets into your current stylesheet, and allow you to extend their styles (cascading, y'know...).

    You can also specify the media type for each @import:

    Of course there are drawbacks to this technique. First, older browsers do not recognize this syntax... and IE has been known to choke on/ignore @imports (are you shocked?!).

    The other drawback is that other developers on your team (or you if you have to revisit the project again a year later) might find it difficult to remember that you're including stylesheets and specifying media types inside of another stylesheet. Your mileage may vary, but that's enough to keep me away until someone convinces me that this is the best way to do it.

  2. @media

    Like the @import above, @media is an in-stylesheet technique to manage the media type. Within the stylesheet (or HTML style Element), you can use the following syntax to provide different CSS for screen and print states.

    This certainly addresses the "wait, what's going on here?" concern from the @import technique, and the older browser support issues still hold true... but you don't have to go too far before you realize that this technique is horrible for handheld and other over-the-air media types.

    Moving on...

  3. HTML Link Element Media attribute

    Old browser-friendly? Check.

    Works in Internet Explorer? Check.

    Easy to read/figure out what's going on when you have to go back into the code to change something months/years later? Check.

Now it should be said that there are multiple ways to do this... because you might need to combine all of these examples (maybe not the @media one though on second thought) to address the unique demands of your project.

Applying what we've learned

Let's take a look at a particular scenario and how we could employ everything we've covered in this article to address it.

I have an XPage that uses a dark blue background and a fixed-width layout, but I want to be able to print the content of that page without wasting money on color toner cartridges...

OK, it's a stretch for an example, but you get the idea!

Let's take a look at the following Demo XPage: IBM XPages: CSS Media Types Demo

Pretty basic, but let's take a look at the print and screen CSS:

Note: I'm not sharing the core screen.css here both for space and the fact that it's not the point, but those of you interested can pull that from the demo.

Here's the CSS from the screen_mediaTypesDemo.css stylesheet:

Here's the CSS from the print.css stylesheet:

Now let's take a look at the end result: a unique [extended] screen-specific and print-specific look for our XPage:

IBM XPages: CSS Media Types Demo XPage using screen-specific CSS IBM XPages: CSS Media Types Demo XPage using screen-specific CSS (click to enlarge this image)

IBM XPages: CSS Media Types Demo XPage using screen-specific CSS IBM XPages: CSS Media Types Demo XPage using print-specific CSS (click to enlarge this image)

In my print-specific CSS, I'm not only adding padding for titles and subtitles and spacing content, but I'm pushing the contents of the <xp:div id="container_footer"> control to the bottom of the printed page.


[Revised 09:57 AM May 10, 2013 -- Chris Toohey]

In this article you've [hopefully] learned a lot about CSS: how CSS works to extend or completely override the rendering of HTML elements, how CSS selectors can be used to get handles on specific HTML elements with pin-point accuracy, and how media types can be used to create target platform and state-specific user interfaces for your XPages.

Understanding the fundamental function of the building block technologies that we XPage developers use is critical to mastering XPages and completely controlling the resulting user interface and user experience with our applications.

Once you understand that this:

... is the answer for this:

I need to get a handle on the ExtLib xe:djBorderContainer control that I've added to the center content section of the xe:applicationLayout and force it to go full length and height...

-- then you can begin writing CSS that completely controls your application UI markup without the need maintain unique classes or other hooks into your markup. This, of course, giving you complete control and extensibility of rendered XPages markup... whether your wrote the controls yourself or not!

If you've liked this article, please Like / +1 / Share to help other IBM Notes and Domino XPages developers learn these techniques. It also helps me gauge interest in a given topic or approach to covering topics.

And as always, if you have ideas for articles or topics that you want covered, reach me via email at

About the author: Chris Toohey

Thought Leadership, Web & Mobile Application Development, Solutions Integration, Technical Writing & Mentoring

A published developer and webmaster of, Chris Toohey specializes in platform application development, solutions integration, and evangelism of platform capabilities and best practices.

More from is powered by IBM Notes Domino XPages & hosted by Prominic.NET

Contact Us

Use our Contact / Feedback form or one of these email addresses:

Creative Commons License

Except where otherwise noted, by Chris Toohey is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.