Nuxeo Server

How to Declare the CSS and JavaScript Resources Used in Your Templates

Updated: December 5, 2017 Page Information Edit on GitHub

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

This page talks about using JavaScript inside the Nuxeo web application (the back office). If you want to build a JavaScript application (with jQuery, Node, AngularJS, ...) you should follow our Nuxeo JavaScript Client page.

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

You can browse the Nuxeo Resources JSF tag library documentation to get details on how to use a given resource or bundle in a 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>
7 days ago Manon Lumeau add tags for doc days
14 days ago Manon Lumeau Fix tag on theme
14 days ago Manon Lumeau Fix tag on themes component
a month ago manonlumeau Added content-review-lts2017 label
2 months ago manonlumeau NXDOC-1346-FT review screenshot
2 years ago Manon Lumeau 16
2 years ago Lise Kemen 15
2 years ago Lise Kemen 14
2 years ago Anahide Tchertchian 13 | NXDOC-577: add ref to the nxr tag lib doc
2 years ago Solen Guitter 11 | Formatting
2 years ago Solen Guitter 12
2 years ago Anahide Tchertchian 10 | NXDOC-577: cleanup
2 years ago Anahide Tchertchian 9 | NXDOC-577: update theme doc
3 years ago Solen Guitter 8
3 years ago Manon Lumeau 7
3 years ago Manon Lumeau 6
3 years ago Manon Lumeau 5
4 years ago Solen Guitter 4
4 years ago Solen Guitter 3
7 years ago Jean-Marc Orliaguet 1
7 years ago Jean-Marc Orliaguet 2
History: Created by Jean-Marc Orliaguet