Addons

HOWTO: Override a Default Style

Updated: March 18, 2024

Most of the default application styling is done using "dynamic" SCSS files referring to variables and flavors. These styles can be browsed on GitHub.

If you'd like to override a default style, here's an how-to, taking as example the override of the "feedback message" styling. Find out how it's styled by default, in case the style is using flavors and you would like to keep this feature (as variables are resolved at display time, you may not be aware that some variables are used).

For instance, here's the default styling for the class facesStatusMessage defined in messages_and_tooltips.scss:

.facesStatusMessage {
  position: fixed;
  right: 1em;
  top: 1em;
  z-index: 10000; }

Here's another example, showing a style using Sass variables:

.warningFeedback,
.ambiance-warn {
  background-color: $warning-background;
  color: $warning-label; }

To override the "feedback message" styling:

  1. Create a local copy of this style so that you can change it.
  2. Create an XML extension point to declare it and attach it to theme pages. Here's a sample structure:

    ├── pom.xml
    └── src
        └── main
            └── resources
                ├── META-INF
                │   └── MANIFEST.MF
                ├── OSGI-INF
                │   └── theme-contrib.xml
                └── themes
                    └── sass
                        └── my-project.scss
    
    

    The MANIFEST.MF file must reference the theme-contrib.xml file for it to be taken into account at deployment. Here's an excerpt:

    Nuxeo-Component: OSGI-INF/theme-contrib.xml
    
    

    Do not forget to add a new line at the end of this file, otherwise manifest parsing may fail.

  3. Fill the theme contribution to declare your own CSS file. Here's an example:

    <?xml version="1.0"?>
    
    <component name="com.my.application.theme">
    
      <!-- require this contribution as it's the one declaring the original styles to override -->
      <require>org.nuxeo.theme.nuxeo.webapp</require>
    
      <extension target="org.nuxeo.ecm.platform.WebResources" point="resources">
        <resource name="my-project.scss" type="css">
          <path>themes/sass/my-project.scss</path>
          <processors>
            <processor>sassCss</processor>
          </processors>
        </resource>
      </extension>
    
      <extension target="org.nuxeo.ecm.platform.WebResources" point="bundles">
        <bundle name="nuxeo_sassCss">
          <resources append="true">
            <resource>my-project.scss</resource>
          </resources>
        </bundle>
      </extension>
    
    </component>
    
    

    Theme pages

    Here you can see that styling is added to the nuxeo_sassCss , which contains all the default styles of Nuxeo Platform.

    Note also that a static .css file can be added in resource if the CSS file does not hold any variables to replace at runtime.

    An alternative way to proceed, when adding a CSS file to all pages, is to contribute the CSS file to the nuxeo_includes default resource bundle, already gathering common CSS and JS resources for all Nuxeo pages (and referenced on all default pages):

    <?xml version="1.0"?>
    
    <component name="com.my.application.theme">
    
      <!-- require this contribution as it's the one declaring the original styles to override -->
      <require>org.nuxeo.theme.nuxeo.webapp</require>
    
      <extension target="org.nuxeo.ecm.platform.WebResources" point="resources">
        <resource name="my-project.scss" type="css">
          <path>themes/sass/my-project.scss</path>
          <processors>
            <processor>sassCss</processor>
          </processors>
        </resource>
      </extension>
    
      <extension target="org.nuxeo.ecm.platform.WebResources" point="bundles">
        <bundle name="nuxeo_includes">
          <resources append="true">
            <resource>my-project.scss</resource>
          </resources>
        </bundle>
      </extension>
    
    </component>
    
    

  4. Fill the CSS file.

    Here's an example contribution to put the feedback message at the center of the screen (instead of top right, as done by the original default style):

    .facesStatusMessage {
      left: 40%;
      position: absolute;
      right: 40%;
      text-align: center;
      top: 40%;
      z-index: 1000; }
    
    

    This file can also reuse existing variables for colors, fonts, borders, backgrounds, etc.

  5. Make sure your Nuxeo plugin is correctly deployed, and your new styles will take effect.