The Differences Between The resource and resources Tags in an XPages Theme

If you’ve modified a theme, you’ve almost certainly used resource tags to include stylesheets and client-side JavaScript libraries. Each resource tag specifies a single resource to include. However, you can also use the resources tag to include multiple resources. In this post, I’ll explain the differences and a caveat.

resource Tags

Most themes only make use of resource tags because they’re what’s demonstrated by the examples. When you create a new theme, these comments are included by default:

<theme extends="webstandard" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="platform:/plugin/com.ibm.designer.domino.stylekits/schema/stylekit.xsd" >
  <!-- 
    Use this pattern to include resources (such as style sheets
    and JavaScript files that are used by this theme.
  -->
  <!--
    <resource>
      <content-type>text/css</content-type>
      <href>mystylesheet.css</href>
    </resource>
  -->

If I have a stylesheet named myStylesheet.css, it’s very easy to tweak that example to include it in my theme.

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

I can also include a client-side JavaScript library like this:

<resource>
  <content-type>application/x-javascript</content-type>
  <href>csjsMyClientJSLibrary.js</href>
</resource>

Each resource tag defines a single resource. It has child tags to define the content type and the path to the resource.

The resources Tag

The resource tags work well, but you can also use a single resources tag instead and there are a few reasons that this is advantageous.

If you’ve looked in the source of an XPage or custom control where you included one or more resources, you’ve noticed that there’s a this.resources tag that includes a line for each individual resource.

For example, in a test database, I created an SSJS script library and a stylesheet and included them as resources on an XPage. This is how they are included in the page source within an xp:this.resources tag:

<xp:this.resources>
  <xp:script src="/ssjsMyLibrary.jss" clientSide="false"></xp:script>
  <xp:styleSheet href="/myStylesheet.css"></xp:styleSheet>
</xp:this.resources>

With the resources tag, you can use a similar syntax in the theme.

There are a few benefits:

1) Succinct syntax

Especially as the theme grows to include a lot of resources, it is nicer to have a less verbose syntax so you can review the contents of the theme more easily.

All of the same properties are available as with the resource tag, they’re just specified as attributes rather than as child tags.

2) Ability to include server-side resources

The resource tag can only include client-side resource (client-side JavaScript libraries, stylesheets, dojo modules,etc), but the resources tag can include SSJS libraries and resource bundles as well.

This makes it much easier to deploy those resources application-wide.

Tip for Specifying Resources in the Theme

There isn’t a simple way to add resources to the theme, but here’s how to streamline the process:

1. Add the resources to an XPage or custom control
2. View the source of the page and copy the block to the theme (and remove it from the page)
3. Remove xp: and xp:this. from the tags

<resources>
  <script src="/ssjsMyLibrary.jss" clientSide="false"></script>
  <styleSheet href="/myStylesheet.css"></styleSheet>
</resources>

This works, but it’s a good idea to specify the type attribute (for example type=”text/javascript”) as well.

Caveat – Avialability of SSJS Library on Page Events

There is an important caveat to loading SSJS libraries this way. The theme is loaded during the Render Response phase of the JSF lifecycle, so SSJS libraries loaded by the theme will not be available to page events that happen before that phase. Therefore, if you need to execute library functions on page-level events that happen earlier (beforePageLoad and afterPageLoad), you will need to include them on the page and not in the theme. SSJS libraries loaded by the theme are available to the beforeRenderResponse and afterRenderResponse events.