Custom layout and widget templates

Custom layout template

A layout can define an XHTML template to be used in a given mode. Let's take a look at the default template structure.

This template is intended to be unused in any mode, so the layout mode is checked to provide a different rendering in "edit", "create", "view" modes and other modes.

When this template is included in the page, several variables are made available:

• layout: the computed layout value ; its mode and number of columns can be checked on it.
• value or document: the document model (or whatever item used as value).

The layout system integration using facelets features requires that iterations are performed on the layout rows and widgets. The <nxl:layoutRow> and <nxl:layoutRowWidget /> trigger these iterations. Inside the layoutRow tag, two more variables are made available: layoutRow and layoutRowIndex. Inside the layoutRowWidget, two more variables are made available: widget and widgetIndex.

These variables can be used to control the layout rendering. For instance, the default template is the one applying the "required" style on widget labels, and translating these labels if the widget must be translated. It also makes sure widgets on the same rows are presented in the same table row.

Listing template

This layout intends to render columns within a table: each line will be filled thanks to a layout configuration. It is only used in view mode. Let's take a look at the default listing template structure.

As you can see, this layout make it possible to use the first defined widget in a given column to print a label, and maybe translate it. It also relies on properties defined in the layout or layout column properties to handle selection, column style class, sorting on the provider,...

Any custom template can be defined following this example to handle additional properties to display on the final table header and columns.

Custom summary template

The summary uses a custom template to use "div" elements instead of tables, more appropriate to a dashboard-like view.

Since version 5.6, it uses a "grid" rendering allowing fine-grained control over the place used by widgets. It combines the following layout template with the use of the standard "container" widget type. The container widgets pile up any number of widgets displaying information about the document metadata, its state, relations, publications, etc...

When using this layout template, the layout definition will use properties defined on rows to allow more or less place to the widgets. Here is the default summary definition:

Here the first widget, containing widgets to display on the left part of the page, will take approximatively 60% of the page. Here is a diagram to help you design layouts using grids:

Custom widget template

The template widget type makes it possible to set a template to use as an include.

Let's have a look at a sample template used to present contributors to a document.

This widget presents the contributors of a document with specific links on each on these user identifier information, whatever the widget mode.

Having a widget type just to perform this kind of rendering would be overkill, so using a widget with type "template" can be useful here.

Since 5.4.2, even template widgets should handle the new 'plain' and 'pdf' modes for an accurate rendering of the layout in PDF (content view and document export) and CSV (content view export). CSV export does not need any specific CSV rendering, so the widget rendering in 'plain' mode should be enough.

Some helper methods make it easier to check the widget mode, here is the complete current definition of the contributors widget type in Nuxeo.

Note that extra spaces have been removed when rendering in the "plain" mode as these spaces may appear on the final rendering (in CSV columns for instance).

When this template is included in the page, the "widget" variable is made available. For a complete list of available variables, please refer to the EL expressions documentation.

Some rules must be followed when writing XHTML to be included in templates:

• Use the widget id as identifier: the widget id is computed to be unique within the page, so it should be used instead of fixed id attributes so that another widget using the same template will not introduce duplicated ids in the jsf component tree.
• Use the variable with name following the field_n pattern to reference field values. For instance, binding a jsf component value attribute to #{field_0} means binding it to the first field definition. The expression #{field} is an alias to #{field_0}.

Builtin templates to handle complex properties

List widget template

The standard widget type "list" is actually a widget of type "template" using a static template path: /widgets/list_widget_template.xhtml. If this default behavior does not suit your needs, you can simply copy this template, make your changes, and use a widget of type "template" with the new template path.

This template assumes that each element of the list will be displayed using subwidgets definitions.

For instance, to handle a list of String elements, you can use the definition:

The empty field definition in the subwidget is used to specify that each element of the list is itself the element to display.

With Nuxeo version <= 5.3.0, to handle a list of complex properties (each entry of the list is a map with keys 'name' and 'email' for instance), you can use the definition:

With Nuxeo version > 5.3.0, to handle a list of complex properties (each entry of the list is a map with keys 'name' and 'email' for instance), you can use the definition:

Complex widget template

A builtin template has been added to handle complex properties. It is available at /widgets/complex_widget_template.xhtml. It assumes that each element of the complex property will be displayed using subwidgets definitions.

To handle a complex property (the value is a map with keys 'name' and 'email' for instance, you can use the definition:

Lists of lists

A builtin template has been added to handle sublists: the original "list" widget is equivalent to a widget of type "template" using the file /widgets/list_widget_template.xhtml. To handle the sublist, this template needs to be changed. The file list_subwidget_template.xhtml is available for it since Nuxeo version 5.2 GA.

To handle a sublist property, you can use take example on this definition: