Theme

Online Style Guide An online UI Style Guide is available to help you design your pages, customize and style them.

Page layout

The layout for the different theme pages is defined in an XML file with the following structure.
For instance, in 5.5, the default galaxy theme is defined in file themes/document-management.xml. It represents the structure displayed when navigating in the Document Management tab of the application (the galaxy name has been kept for compatibility).

It is now possible to add a class attribute to the <page>, <section>, <cell> and <fragment> elements. They will be part of the generated stylesheet.

This structure is declared to the theme service using the following extension point:

The file referenced by the "src" tag is looked up in the generated jar.

Views referenced in this layout still need to be defined in separate extension points. For instance here is the logo contribution:

The global application settings still need to be defined on the "applications" extension point:

In the above example, you can see that the galaxy/default page is the default page of the application. Other pages like galaxy/popup can also be explicitely set for some specific views.

Branding : use flavors and styles!

CSS configuration used to be held by the same XML file than the one defining the pages structures. This was a problem for modularity, as some addons needed to add styling to existing pages without changing the global structure of the page.

Since 5.5, extension points have been added to allow style contributions separately from the structure. A new notion of flavor has also been added, to make it possible to switch some elements held by the branding (colors, logo...) without changing the associated styles: the local configuration makes it possible to change this flavor so that branding can be customized when navigating in some parts of the document hierarchy.

The pages extension point

Each theme page needs to have a themePage contribution to the pages extension point: this is the main link between the page structure and its branding.
Here is an example of the galaxy theme default page:

• <defaultFlavor> refers to the default flavor used for the page. See below for flavor definition.
• <flavors> refers to the different flavors available for this page in the Theme local configuration.
• <styles> refers to the dynamic CSS stylesheets that will be embedded in this page. See below for styles definition.
• <resources> refers to static resources (CSS stylesheet that do not use variables, and Javascript file). See below for resources definition.

Style order is important! The theme engine will actually concatenate all the stylesheets defined in the <styles> element, in the order of their declaration, to build one big stylesheet named myCustomTheme-styles.css. So if you need to override a CSS class existing in one of the Nuxeo stylesheets, for example .nxHeader .logo in header.css, you will have to do this in a custom stylesheet declared after the Nuxeo one. For example my_custom_styles should come after header.

The styles extension point

Each dynamic CSS stylesheet embedded in a theme page needs to have a style contribution to the styles extension point.
Here is an example of some of the basic stylesheet contributions:

The files referenced by the "src" tags are looked up in the generated JAR.

Here is an excerpt of the "buttons_and_actions" CSS file:

It can mix standard CSS content, and also hold variables that can change depending on the selected flavor (see below).

The flavor extension point

Each flavor needs to have a flavor contribution to the flavors extension point.
Here is an example of the default flavor:

• <presets> contributions define a list of CSS property presets, as it was already the case in the old system. They represent variables that can be reused in several places in the CSS file.
  For example in themes/palettes/default-borders.propertieswe can define:

  A preset can be referenced in a dynamic CSS file, using the pattern "preset_name (__FLAVOR__ preset_category)".
• <label> and <palettePreview> are used to display the flavor in the Theme local configuration.
• <logo> is used to customize the default logo view logo_DM_galaxy.xhtml.

Theme static resources

JS and CSS static files (ie. that don't need to be configured with flavors) should be defined as static resources, using the resources extension point as it was the case in the old system.

Note that dynamic CSS files are parsed, and this parsing may not accept CSS properties that are not standard (like CSS3 properties for instance). Placing these properties in static resources is a workaround for this problem if you do not need to make them reference flavors.

Here are sample contributions to this extension point:

Note that the resource name must end by ".css" for CSS files, and ".js" for JavaScript files.

The files referenced by the "path" tags are looked up in the generated war directory (nuxeo.war) after deployment, so you should make sure the OSGI-INF/deployment-fragment.xml file of your module copies the files from the JAR there.