Layouts (forms and views)

Last night a widget saved my life

– ui:Indeep

Layouts are used to generate pages rendering from an xml configuration.

In a document oriented perspective, layouts are mostly used to display a document metadata in different use cases: present a form to set its schemas fields when creating or editing the document, and present these fields values when simply displaying the document. A single layout definition can be used to address these use cases as it will be rendered for a given document and in a given mode.

In this chapter we will see how to define a layout, link it to a document type, and use it in XHTML pages.

Online demo You might want to check out the Layout Showcase for a demo.

Layouts

A layout is a group of widgets that specifies how widgets are assembled and displayed. It manages widget rows and has global control on the rendering of each of its widgets.

Widgets

There's a widget in the closet

– R. Kellise

A widget defines how one or several fields from a schema will be presented on a page. It can be displayed in several modes and holds additional information like for instance the field label. When it takes user entries, it can perform conversion and validation like usual JSF components.

Widget types

A widget definition includes the mention of its type. Widget types make the association between a widget definition and the JSF component tree that will be used to render it in a given mode.

Modes

Both layouts and widgets have modes.

The layout modes can be anything although some default modes are included in the application: create, edit, view, listing and search. Since 5.4.2, some new default modes are included: bulkEdit, header, csv, pdf and plain.

The widget modes are more restricted and widget types will usually only handle two modes: edit and view. The widget mode is computed from the layout mode following this rule: if the layout is in mode create, edit or search, the widget will be in edit mode. Otherwise the widget will be in view mode. Since 5.4.2, new widget modes have been added: pdf, csv and plain. 'plain' is the new default mode, as it is very close to the view mode except it's not supposed to include HTML tags.

Since Nuxeo 5.4, the mapping between the layout mode and the widget more is more loose: if the layout is in mode create, edit, bulkEdit or search, or if its mode starts with one of these mode names, the widget will be in edit mode. Otherwise the widget will be in the default mode ('view' before 5.4.1, and 'plain' after).

Here is a table of the default mappings:

It is possible to override this behavior in the widget definition, and state that, for instance, whatever the layout mode, the widget will be in view mode so that it only displays read-only values. The pseudo-mode "hidden" can also be used in a widget definition to exclude this widget from the layout in a given mode.

The pseudo mode "any" is only used in layouts and widgets definitions to set up default values.

The following pages explain how to work with layouts:

• Manage layouts
• Field binding and expressions
• Document layouts
• Layout display
• Standard widget types
• Custom layout and widget templates
• Custom widget types
• Generic layout usage
• Layout how-tos
• Widgets known limitations