Layouts and Widgets (Forms, Listings, Grids)

Updated: April 15, 2021

JSF UI Deprecation
This requires to have the JSF UI addon installed on your server that is deprecated since Nuxeo Platform LTS 2019.
Please refer to the Web UI documentation.

Layouts and widgets have been originally designed to display forms, and have been improved to handle listings as well as summary pages. These configuration elements are used to generate page fragments from XML configurations contributed to Nuxeo Runtime extension points.

In this chapter we will see how to define layouts and associated widgets, and use them in XHTML pages.

Layouts and Widgets can be configured using Studio: Check out the Form Layouts documentation.

Key Concepts


In a document oriented perspective, layouts are mostly used to display a document metadata in different use cases: present a form to set its schema 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.

 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.


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.

Widgets have been made more generic to handle rendering of elements in listings, for instance, or to render information that is not directly linked to a document metadata, like presenting its relations.

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 or xhtml template that will be used to render it in a given mode.

Table of Content

The following pages explain how to work with layouts and widgets.

We'd love to hear your thoughts!

All fields required