HOWTO: Declare the CSS and JavaScript Resources Used in Your Templates

The CSS and JavaScript resources needed by your JSF pages can be added directly from inside your templates, or using runtime extension points.

Defining New Resources

Let's define two types of resources to be included later on pages:

<extension target="org.nuxeo.ecm.platform.WebResources" point="resources">
  <resource name="myCss.css">
    <uri>/css/myCss.css</uri>
  </resource>
  <resource name="myScript.js">
    <uri>scripts/myScript.js</uri>
  </resource>
</extension>

Here the uri element is used, so resources will be looked up in the JAR holding the declaration. Please refer to the resources extension point documentation for more details.

Including Resources in a Given Page

Let's consider defining a new page template, using the main page template at /pages/basic_page.xhtml:

<ui:composition template="basic_page.xhtml"
  xmlns="http://www.w3.org/1999/xhtml"
  xmlns:ui="http://java.sun.com/jsf/facelets">
  <ui:param name="pageName" value="myPage" />
  <ui:param name="pageFlavor" value="#{themeActions.currentFlavor}" />

  <ui:define name="basic body">
    Main body content goes here
  </ui:define>

</ui:composition>

This template uses a page named myPage.

It can also reference the two resources defined above to include them too:

<extension target="org.nuxeo.theme.styling.service" point="pages">
  <page name="myPage" charset="utf-8">
    <links>
      <icon name="icon">/icons/favicon.png</icon>
      <icon name="shortcut icon">/icons/favicon.ico</icon>
    </links>
    <defaultFlavor>default</defaultFlavor>
    <flavors>
      <flavor>default</flavor>
    </flavors>
    <resources>
      <bundle>nuxeo_includes</bundle>
      <bundle>nuxeo_base</bundle>
      <bundle>nuxeo_sassCss</bundle>
      <bundle>nuxeo_dm</bundle>
      <resource>myCss.css</resource>
      <resource>myScript.js</resource>
    </resources>
  </page>
</extension>

Alternatively, if the page already exists, resources can be appended to it:

<require>component.defining.the.myPage.page<require>
<extension target="org.nuxeo.theme.styling.service" point="pages">
  <page name="myPage">
    <resources append="true">
      <resource>myCss.css</resource>
      <resource>myScript.js</resource>
    </resources>
  </page>
</extension>

Alternatively, resources can be included to a new resource bundle:

<require>component.defining.the.myPage.page<require>
<extension target="org.nuxeo.ecm.platform.WebResources" point="bundles">
  <bundle name="myBundle">
    <resources>
      <resource>myCss.css</resource>
      <resource>myScript.js</resource>
    </resources>
  </bundle>
</extension>
<extension target="org.nuxeo.theme.styling.service" point="pages">
  <page name="myPage">
    <resources append="true">
      <bundle>myBundle</bundle>
    </resources>
  </page>
</extension>

Including Resources in Several Pages

The default bundle named nuxeo_includes, defined by component org.nuxeo.theme.nuxeo.webapp, handles the inclusion of most of the JavaScript files used in default pages. New resources can be added to it so that they're available in all default pages:

<require>org.nuxeo.theme.nuxeo.webapp</require>
<extension target="org.nuxeo.ecm.platform.WebResources" point="bundles">
  <bundle name="nuxeo_includes">
    <resources append="true">
      <resource>myCss.css</resource>
      <resource>myScript.js</resource>
    </resources>
  </bundle>
</extension>

Similarly, the default bundle named nuxeo_base, also defined by component org.nuxeo.theme.nuxeo.webapp, handles the inclusion of most of CSS files used in default pages. New resources can also be added to it.

Including Resources in a Given Template

When designing a page, you may want to include specific resources. The main page template at /pages/basic_page.xhtml waits for a pageName parameter, that will already include resources and bundles contributed through the page extension point.

It also inserts additional templating zones to include additional resources, here is a sample usage:

<ui:composition template="basic_page.xhtml"
  xmlns="http://www.w3.org/1999/xhtml"
  xmlns:h="http://java.sun.com/jsf/html"
  xmlns:ui="http://java.sun.com/jsf/facelets">
  <ui:param name="pageName" value="#{themeActions.currentPage}" />
  <ui:param name="pageFlavor" value="#{themeActions.currentFlavor}" />

  <ui:define name="stylesheets">
    <nxr:resource name="myCss.css" />
  </ui:define>

  <ui:define name="header_scripts">
    <nxr:resource name="myScript.js" />
  </ui:define>

  <ui:define name="basic body">
    Main body content goes here
  </ui:define>

</ui:composition>