Addons

HOWTO: Override a Template

Updated: March 18, 2024

The purpose of this how-to is to learn how to override a default Nuxeo template. It considers that you are able to create a new bundle and the required files. Otherwise please refer to the page HOWTO: create an empty bundle or use Nuxeo CLI.

Just remember that overriding a default template is risky for maintenance. The original template could be heavily changed or even renamed or removed in future versions of Nuxeo.

Step 1: Getting the Name of the Template

Look for the name of the template you want to override and its path on the server. This information is important because the overridden template must have the exact same path and name. When the server has deployed the bundles, the XHTML templates are located under the folder ${nuxeo_server}/nxserver/nuxeo.war/.

Step 2: Creating the File in the Bundle

In your bundle, create a new XHTML file with the exact same name and in the same folder structure as the original one. In usual Nuxeo bundles, the XHTML files are located under resources/web/nuxeo.war/.

For this example, we will override the nuxeo_footer_template.xhtml template. It is located in the folder ${nuxeo_server}/nxserver/nuxeo.war/incl/.

  1. Create a folder incl/ under resources/web/nuxeo.war/.
  2. Create the overridden template nuxeo_footer_template.xhtml.

Step 3: Deploying the Bundle

Once your file is created and modified to suit your needs, you have to deploy it.

In the Nuxeo Platform, the WAR file is generated each time you start the server by looking into each JAR in nxserver/bundles and nxserver/plugins. More precisely, this happens because you set an install XML tag in the deployment-fragment.xml file. Content syntax of the tag is simply Ant. Create a file deployment-fragment.xml under resources/OSGI-INF.

deployment-fragment.xml

<?xml version="1.0"?>
<fragment version="1">

  <require>org.nuxeo.ecm.webapp.ui</require>

  <install>
    <!–  unzip the content of the resources/web folder in nxserver –>
    <unzip from="${bundle.fileName}" to="/" prefix="web">
      <include>web/nuxeo.war/**</include>
    </unzip>
  </install>

</fragment>

  • org.nuxeo.ecm.webapp.ui is actually the symbolic name of the bundle we would like to override. You can find this information in the MANIFEST.MF file of the bundle.
  • The <require> tag makes sure that your bundle will be deployed after the default one. This tag is also used in the contributions to the extension services to be sure that they will be deployed after the bundles listed in the require tags.

  • The <install> section describes what should be installed.

For more information about the bundle deployment, do not hesitate to read the page Understanding Bundles Deployment.