Nuxeo JSF Approach

We built Nuxeo JSF framework with two main ideas in mind:

Make the UI simple,

Make the UI pluggable.

For the first point, we choose to have an "File Explorer" like navigation. So you have tools (tree, breadcrumb, search, tags) to navigate in a document repository and when on a document you can see several views on this document (Summary, Relations, Workflows, Rights, History ...).

We also choose to make the UI very pluggable, because each project needs to have a slightly different UI. In order to achieve that, each page/view is in fact made of several fragments that are assembled based on the context. This means you can easily add, remove or change a button, a link, a tab or a HTML/JSF block. You don't need to change or override the Nuxeo Platform code for that, neither do you need to change the default Nuxeo Platform templates. The assembly of the fragments is governed by "Actions", so you can change the filters and conditions for each fragment. Of course each project also needs to define it's own views on Document, for that we use the Layout and Content View system.

All this means that you can start from a standard Nuxeo Platform, and with simple configuration have a custom UI.

JSF Page Layout System Overview

A Nuxeo Platform page is made up of several layers:

Nuxeo Theme (aka NXTheme)

Defines a page level layout (slots)

Defines CSS resources

XHTML/facelet

Fills the NXTheme slots

Uses Nuxeo Tags to render Layouts, Widgets, Actions

Layouts/Widgets/Actions

This is the application meta-model

This is the part that is configured via Nuxeo Studio

Here is a very quick walk-through of the main principles with some examples and links to code or documentation.

Nuxeo Theme

The Nuxeo Theme is a page layout engine that also handles resources management. See the page Theme for a general introduction. A part of the theme definition can be configured via Nuxeo Studio (the CSS and Flavor part).

As any other Nuxeo component, the Theme system uses extension points to define:

Both widgets are of type documentAction meaning they use the action system to resolve what are the subwidgets.

We use this Widget/Action association to provide a way to have Incremental Layouts: the idea being that the content of the screen is the result of the aggregation of:

What is contributed by the deployed plugin
If workflow is deployed you will have some WF related information displayed.

What is contributed by your Studio configuration

Using that principle, the damSingleAssetPanelLeft will display all widgets associated to the action category DAM_SINGLE_ASSET_PANEL_LEFT: you will find 10 of them in the same dam-layouts-contrib.xml contribution file, each of them being displayed according to the type of content.

Each of these tab is associated with a XHTML, that itself will also use layouts and widgets. If we take the documentView.xhml that corresponds to the default Summary tab in the platform we see that it takes the "summary" layouts defined for the type of document being currently displayed. The widgets and different possible layouts are defined on the layouts-summary-contrib.xml. By default unless defined otherwise all summary layout use grid_summary_layout.

However, looking at the type to layout configuration you can see that each document type can be associated with different layout and that there are several categories of layout.

Seam and Navigation

So far we have defined view level components. These views will need to get some data from the Nuxeo service and have some UI specific controllers.

This is the role of the Seam layer:

Seam Beans can be used as Controllers that access the Nuxeo Service to push/retrieve data.

Seam Context is used to manage the web context and the associated transient state.

Because of the way the screen are rendered inside the Nuxeo Platform, all Nuxeo navigations do not correspond to JSF navigation. Actually, in a lot of cases you always render the same JSF view, but thanks to the Actions/Layout/Widget model the actual content displayed in the page will change according to the context:

What is the document you are looking at

What is the currently selected tab

What is the lifecycle of the document

...

However, sometimes, there is an actual JSF level navigation that relies on standard JSF navigation case. For that, each Nuxeo Bundle can contribute navigation cases to the JSF config via a deployment-fragment.

In addition, the Nuxeo Platform provides a system to manage REST URL that combine JSF navigation and Actions: see the page Navigation URLs for more details.

About Possible Approaches

Pure Studio

Nuxeo Studio provides a high level configuration UI to configure Actions, Layouts, Widgets, etc. It hides a lot of the complexity of the underlying model, as well as some details.

For now, Nuxeo Studio allows you to customize pretty much everything that is inside the "slots" defined by the target XHTML/Theme template (DM or DAM). However, Nuxeo Studio does not give you direct access to the "low level" model.

In the context of 7.x, we are working on replacing all the low level model by layouts only.

Custom Web Templates

As the rest of the framework, the JSF web framework is extensible:

You can contribute new XHTML pages

You can extend the theme

You can contribute to the Action/Widget/Layout system

You an contribute new Seam beans

At the same time, as long as your screens logic depends on Action/Widgets/Layouts, you will be able to use Studio to configure it.

However, going that road requires more knowledge and skills:

You have to be familiar with underlying technologies

Java/JSF/Seam

Nuxeo Extension Point model

Actions/Layout/Widget

On the Studio side, things will be less polished
For example you will have to know the name of the layout you want to change since it won't be one of the default layout from DAM/DM

We are not saying that this road is not good, we just want to make it clear that the technical requirements are higher: more freedom but also more responsibilities.

If you are mainly interested in DAM, one option could be to review your mock-ups against the current Nuxeo DAM view. We switched from the 3 panes view to the 2 panes + lightbox because we think that from a user perspective it is better. It may be worth giving a try to this option since it would make things simpler.

However, if you think the custom UI is the way to go, we'll be happy to help you on that road. But you may want to consider a training.

JSF UI Limitations

This chapter presents the limitations to the Seam/JSF web application.

Back and Next Buttons Paradigm and JSF in the Nuxeo Platform

Nuxeo Platform navigation is based solely on the JSF library.

Although the JSF library is not designed to take advantage of the Back and Next buttons of the browser, these buttons work in most cases when called on GET actions, but some inconsistent display could happen if used after a user action modifying data. However, those cache-related display inconsistency aren't harmful in anyway for the system.

Those unwanted displays are hard to fix: it could be done by pushing "by hand" some history info into a queue whenever the Nuxeo Platform does a navigation, and try to return to that when an application-based back button is pressed. But this would be quite complex and browser dependent.

So if you're massively using POST action, the solution is to train the users to never activate/use the Back and the Next buttons when using the Nuxeo Platform.

Default Widget Types Known Limitations

Some widgets have limitations in some specific conditions of use. We maintain a list of known problems here.