Look and feel

The file starts with the elements declaration, we define the pages, the rows (section markup), the cells and the fragments in the cells.

<theme name="default"> <layout>
      <page name="default"> <section> <cell> <fragment
      type="generic fragment" /> </cell> <cell> <fragment
      type="generic fragment" /> </cell> <cell> <fragment
      type="generic fragment" /> </cell> </section>
      </page> <page name = ...> . . . </page>
      </layout> </theme>

All this markup refers to an Element subtype in the java model: PageElement, CellElement... The fragment element, the one that gives the widget oriented capacity to Nuxeo is typed: we have in the default distribution "generic fragment", "action fragments". A typed fragment returns a model to be displayed and edit in the edit mode of the fragments. This model is often (but not always) what we can see in the "properties" tab of the fragment editor. For now there is in the default Nuxeo distribution:

The fragment can also receive a perspective attribute that specifies in which perspective it will be displayed (the fourth tab in the fragment editor). You can then propose to Nuxeo user the same kind of experience you have in Eclipse. The perspective are specified in the perspective extension point of !ThemeService component.

Then, once you declared all the elements, you can format them through different axes :

To do this, you put, inside the <theme> markup, children markup from those types:

Those 3 markups use the attribute element to get the reference to which element of your skeleton they will be applied:

element="page[3]/section[3]/cell[1]"

<widget element="page"> <view>page
        frame</view> </widget>

<view
        name="page frame"> <element-type>page</element-type>
        <format-type>widget</format-type>
        <class>org.nuxeo.theme.jsf.views.JSFView</class>
        <template>nxthemes/jsf/widgets/page-frame.xml</template>
        </view>

<h:outputText escape="false"
          value="#{nxthemesInfo.model.body}" />

<layout element="page[3]/section[3]/cell[1]">
        <width>50%</width> <padding>20px</padding>
        <margin>0</margin> </layout>

<style
        element="page[1]/section[3]/cell[1]|page[3]/section[4]/cell[1]">
        <selector path=""> <color>#757575</color>
        <border-style>solid none none none</border-style>
        <border-color>#003366</border-color>
        <border-width>1px</border-width> <background> #FFF
        url(/nuxeo/img/gray_gradient.gif) top left repeat-x
        </background> <padding>5px 15px 5px 5px</padding>
        </selector> <selector path="div">
        <font-size>9px</font-size> </selector>
        </style>

We have seen how to define a theme. Now we need to see how a theme is applied. More precisely, how do I manage the choice of the page I will display? In fact, the Nuxeo Theme framework proposes many ways to specify the theme applied to the webapp for a given view:

So how to manage priority when more than one parameter is passed to the framework? The !ThemeService component has another extension point to achieve this: the negotiation extension point. Not only can it be used to select a theme but it also works with other objects as we will see later.

<negotiation object="theme"
      strategy="nuxeo5">
      <scheme>org.nuxeo.theme.jsf.negotiation.theme.RequestParameter</scheme>
      <scheme>org.nuxeo.theme.jsf.negotiation.theme.CookieValue</scheme>
      <scheme>org.nuxeo.theme.jsf.negotiation.theme.ViewId</scheme>
      <!-- local theme (specific to nuxeo5) -->
      <scheme>org.nuxeo.ecm.webapp.theme.LocalTheme</scheme>
      <scheme>org.nuxeo.theme.jsf.negotiation.theme.DefaultTheme</scheme>
      </negotiation>

As we can see in the example, the negotiation point defines the order in which the different methods for obtaining the current theme information are applied. This negotiation feature also applies to other Nuxeo Theme objects like the engine, the mode, the perspective.

Engine and filter are two notions that work together. An engine is the combination of different filters, and a filter is a "sub-unit" of rendering. So the engine is the global renderer of your web app. From the elements skeleton, it will generate the graphical appearance, passing each element through different black boxes, depending on the type of the element. Here is the definition of the default engine of Nuxeo.

<engine name="default"> <renderer
      element="theme"> <filter>add widget</filter>
      <filter>collect xmlns</filter> </renderer>
      <renderer element="page"> <filter>add widget</filter>
      <filter>set layout</filter> <filter>set
      style</filter> </renderer> <renderer
      element="section"> <filter>add widget</filter>
      <filter>set layout</filter> <filter>set
      style</filter> </renderer> <renderer element="cell">
      <filter>add widget</filter> <filter>set
      layout</filter> <filter>set style</filter>
      </renderer> <renderer element="fragment">
      <filter>control fragment visibility</filter>
      <filter>add widget</filter> <filter>set
      style</filter> <filter>write fragment tag</filter>
      </renderer> </engine>

The engine, that you register in the ThemeService component through the "engines" extension point lets you add for each type of element some "filters" that will do some work around the markup content at rendering time. Nuxeo already uses filters like the style fitler, that put the style definition you chose, the layout filter, the "drag'n drop" filter... One interesting use of the filters is illustrated with the Nuxeo Theme editor: when you type shift+alt+t, the display changes and you are in the WYSIWYG Nuxeo theme editor. But all the components that make your page are still here, they just look a bit different because, some different filters are used. For instance, because of the drag'n drop filter presence, you can move the fragments.

Graphical components may need some external resources such as CSS or JavaScript libraries. Nuxeo theme has an embedded resource management system that at rendering time automatically computes the list of the files needed for rendering a page. Resources are served using gzip compression when supported by the browser. JavaScript resources are also compressed using Dojo's ShrinkSafe. Finally all files of a same type (.css or .js) are concatenated. This reduces the number of individual downloads and it enables to manage dependencies between resources. Indeed, at declaration time you can specify the dependencies for a given resource:

<extension
      target="org.nuxeo.theme.services.ThemeService" point="resources">
      <resource name="controls.js">
      <path>nxthemes/jsf/scripts/scriptaculous/controls.js</path>
      <require>effects.js</require>
      <require>prototype.js</require> </resource>
      </extension>

Then, when you register the view associated to an element, you specify the resources it needs:

<view name="nuxeo5
      clip board"> <format-type>widget</format-type>
      <class>org.nuxeo.theme.jsf.views.JSFView</class>
      <template>incl/user_clipboard.xhtml</template>
      <resource>dragdrop.js</resource>
      </view>

The last concept you need to know about to completely control the look and feel of your application is the application extension point:

<extension
      target="org.nuxeo.theme.services.ThemeService" point="applications">
      <application root="/nuxeo"> <negotiation>
      <strategy>nuxeo5</strategy>
      <default-engine>default</default-engine>
      <default-theme>default/default</default-theme>
      <default-perspective>default</default-perspective>
      </negotiation> <resource-caching>
      <lifetime>36000</lifetime> </resource-caching>
      <view id="/create_relation_search_document_popup.xhtml">
      <theme>default/popup</theme> </view> <view
      id="/user_dashboard.xhtml">
      <theme>default/user_dashboard</theme> </view> <view
      id="/view_calendar.xhtml">
      <perspective>view_calendar</perspective> </view>
      <view id="/print.xhtml">
      <perspective>print</perspective> </view>
      </application> </extension>

As you can see in the example, an application is associated to a web-app root context. There you specify the strategy (a negotiation grouping feature), the default engine, the default theme and perspective. You also specify the caching policy and there you also declare the JSF view id / theme association that we went through earlier in this tutorial.

The file theme-default.xml is structured as follows:

In theme-contrib.xml we have our theme called:

<!-- themes --> <extension
        target="org.nuxeo.theme.services.ThemeService" point="themes">
        <theme> <src>META-INF/theme-default.xml</src>
        </theme> </extension>

In the editor, in Manage Themes tab, it gives:

This file is deployed in JBoss. If you modify the theme using the editor all changes will be lost so think of downloading the theme to your Desktop, to replace the theme-default.xml in your local copy of Nuxeo EP 5.

A good way of working with this file is to add your working copy in theme-contrib.xml. It is possible in NXThemes to load several themes and page.

Add your file(s) in themes-contrib.xml, for example:

<theme>
        <src>file:///path/to/sources/nuxeo/nuxeo-platform/nuxeo-platform-webapp-core/src/main/resources/META-INF/nxthemes-setup.xml</src>
        </theme>

After a redeployment, in the 'Manage Themes' section we now have a theme that can be reloaded directly from the file-system!

Starting from there, here are two ways of developing smartly:

<!-- Styles presets --> <extension
          target="org.nuxeo.theme.services.ThemeService" point="presets">
          <palette name="Nuxeo default fonts"
          src="themes/palettes/nxfonts.properties" category="font" />
          <palette name="Nuxeo psd colors"
          src="themes/palettes/nxcolors.aco" category="color" />
          <palette name="Nuxeo default backgrounds"
          src="themes/palettes/nxbackgrounds.properties" category="background"
          /> </extension>

default=11px Verdana, Arial,
          sans-serif

default=12px Courier, serif

<style name="default buttons"> <selector
          path="input.button">
          <background>url(/nuxeo/img/button_1.gif) 0 0 repeat-x
          #e3e6ea</background> <font preset="default (Nuxeo default
          fonts)"/> <margin>5px 10px 10px 0px</margin>
          <color>#000</color>
          <border-style>solid</border-style>
          <border-width>1px</border-width>
          <border-color>#ccc #666 #666 #ccc</border-color>
          <padding>2px 5px 2px 5px</padding>
          <cursor>pointer</cursor> </selector> <selector
          path="input.button:hover"> <color preset="white (Nuxeo psd
          colors)"/> <font preset="default (Nuxeo default fonts)"/>
          <background>url(/nuxeo/img/button_2.gif) 0 0 repeat-x
          #3f89ef</background> <border-color>#0099ff #0066cc
          #0066cc #0099ff</border-color>
          <border-style>solid</border-style>
          <border-width>1px</border-width> </selector>
          <selector path="input.button[disabled=disabled],
          input.button[disabled=disabled]:hover">
          <color>#c1c1c1</color> <font preset="default (Nuxeo
          default fonts)"/>
          <background>url(/nuxeo/img/button_disabled.gif) 0 0 repeat-x
          #ebeff4</background> <border-color>#ccc #999 #999
          #ccc</border-color> <cursor>default</cursor>
          <border-style>solid</border-style>
          <border-width>1px</border-width> </selector>
          </style>

 <!-- user services --> <style
          element="page[1]/section[1]/cell[2]/fragment[1]|page[3]/section[1]/cell[2]/fragment[1]"
          inherit="default buttons"> 

We rarely create a theme from scratch. Since the default, popup and dashboards are used in every projetc, we usually duplicate the default theme and use it as a basis. But let's pretend you want to add a completely new and custom theme to your project. Here are the steps.