DefinitionA content view is a notion to define all the elements needed to get a list of items and perform their rendering. The most obvious use case is the listing of a folderish document content, where we would like to be able to:
- define the NXQL query that will be used to retrieve the documents, filtering some of them (documents in the trash for instance);
- pass on contextual parameters to the query (the current container identifier);
- define a filtering form to refine the query;
- define what columns will be used for the rendering of the list, and how to display their content;
- handle selection of documents, and actions available when selecting them (copy, paste, delete...);
- handle sorting and pagination;
- handle caching, and refresh of this cache when a document is created, deleted, modified...
The Nuxeo Content View framework makes it possible to define such an object, by registering content views to the service. Here is a sample contribution, that will display the children of the current document:
The Content View Query
coreQueryPageProvider element makes it possible to define whet query will be performed. Here it is a query on a core session, using a pattern with one parameter.
coreQueryPageProvider element accepts any number of property elements, defining needed context variables for the page provider to perform its work. The
coreSession property is mandatory for a core query to be processed and is bound to the core session proxy named
documentManager available in a default Nuxeo application.
It also accepts any number of
parameter elements, where order of definition matters: this EL expression will be resolved when performing the query, replacing the '?' characters it holds.
The main difference between
parameters is that properties will not be recomputed when refreshing the provider, whereas parameters will be. Properties will only be recomputed when resetting the provider.
sort element defines the default sort, that can be changed later through the interface. There can be any number of
sort elements. The
sortInfosBinding element can also be defined: it can resolve an EL expression in case the sort infos are held by a third party instance (document, Seam component...) and will be used instead of the default sort information if not null or empty. The EL expression can either resolve to a list of
org.nuxeo.ecm.core.api.SortInfo instances, or a list of map items using keys
sortColumn (with a String value) and
sortAscending (with a boolean value).
pageSize element defines the default page size, it can also be changed later. The
pageSizeBinding element can also be defined: it can resolve an EL expression in case the page size is held by a third party instance (document, seam component...), and will be used instead of the default page size if not null.
maxPageSize element can be placed at the same level than
pageSize and is available since version 5.4.2. It makes it possible to define the maximum page size so that the content view does not overload the server when retrieving a large number of items. When not set, the default value "100" will be used: even when asking for all the results with a page size with value "0" (when exporting the content view in CSV format for instance), only 100 items will be returned. Since 5.6 (and some previous hotfixed versions, see NXP-9052) this is configurable globally using the runtime property
Since version 5.6, you can set a maximum number of results. This is useful for performance reasons, because it takes time to get the total number of results (and thus the number of pages). If there are more results than the limit, then the number of pages will be unknown. Nevertheless you can still navigate to the next page if it exists.
To set this limit you need to add a
maxResults parameter to
coreQueryPageProvider, either using an integer value or one of the following keywords:
DEFAULT_NAVIGATION_RESULTS: Used by most of the navigation page provider, the default is 200 and it can be overridden using Java options:
or you can directly add this line in nuxeo.conf:
- PAGE_SIZE: this is useful when you are interested in a single page or if you don't need a total count.
This kind of core query can also perform a more complex form of query, using a document model to store query parameters. Using a document model makes it easy to:
- use a layout to display the form that will define query parameters;
- save this document in the repository, so that the same query can be replayed when viewing this document.
Here is an example of such a registration:
The above definition holds a
whereClause element, stating the search document type and predicates explaining how the document model properties will translated into a NXQL query. It can also state a
fixedPart element that will added as to the query string. This fixed part can also take parameters using the '?' character and
searchLayout element defines what layouts needs to be used when rendering the search document model: it will be in charge of displaying the search form. Since 5.5, this element accepts a
filterDisplayType attribute. When set to "quick", it'll display a form showing only the first row of the layout, visible directly above the content view results. The whole filter form is then displayed in a popup. Otherwise, the default rendering is used, and the filter form is visible in a foldable box.
Since 5.4.2, the
showFilterForm element makes it possible to show this form above the content view results.
The Content View Result Layouts
The result layouts control the display of resulting documents. It states different kinds of rendering so that it's possible to switch between them. They also accept a title and an icon, useful for rendering.
The layout configuration is standard and has to follow listing layouts configuration standards. The layout template, as well as widgets displaying selection checkboxes, need to perform an Ajax selection of documents, and re-render the action buttons region.
The Content View Selection List
selectionList element will be used to fill the document list with given name.
Selection is done through Ajax, so that selection is not lost when not performing any action thanks to this selection.
The Content View Actions
actions element can be repeated any number of times: it states the actions category to use to display buttons applying to this table ("copy", "paste", "delete",...). Each
actions element will generate a new row of buttons.
These actions will be displayed under the table in default templates, and will be re-rendered when selecting an item of the table so that they are enabled or disabled. This is performed using adequate filters, performing checks on selected items.
Since 5.4.2, the
searchDocument variable can be used in EL expressions to bind the page size, the sort infos and the result columns to the search document properties.
searchDocument element can be filled on a content view using an EL expression: it will be used as the search document model. Otherwise, a bare document will be generated from the document type.
Sample usage, showing how to add a clause to the search depending on title set on the current document (will display non deleted document with the same title):
resultColumns element can be filled on a content view using an EL expression: it will be used to resolve the list of selected columns for the current result layout. If several result layouts are defined, they should be configured so that their rows are always selected in case the selected column names do not match theirs.
Sample usage, showing how to reuse the same selected columns than the one selected on the advanced search page:
Additional rendering information
Additional rendering information can also be set, to be used by templates when rendering the content view:
showTitle is available since version 5.4.2. It can be used to define a title for the content view, without displaying it on the default rendering. It can also be used when exporting the content view in CSV format, for instance.
translateEmptySentence are available since version 5.4.2. They are used to display the message stating that there are no elements in the content view.
showRefreshCommand are available since version 5.4.2. They are used to control the display of the page size selector, and of the "refresh current page" button. They both default to true.
cacheKey element, if filled, will make it possible to keep content views in cache in the current conversation. It accepts EL expressions, but a static cache key can be used to cache only one instance.
cacheSize element is useful to use a queue of cached instances. In the example, 10 instances of content views with a different cache key will be kept in cache. When the 11th entry, with a new cache key, is generated, the first content view put in the cache will be removed, and will need to be re-generated again. This cache configuration will make it possible to navigate to 10 different folderish document pages, and keep the current page, the current sort information, and current result layout.
When caching only one instance, setting the
cacheSize element to more than "1" is useless. Caching only one instance can be useful when several features need to retrieve information from the same content view.
If a cache key is given, but no cache size is set, "5" will be used by default. Using "0" means no caching at all (and the cache key will be ignored).
Caching is done by a Seam component named
contentViewActions . Although the cache key, cache size and events configurations handle the most common use cases, it is sometimes useful to call this bean methods directly when forcing a refresh.
reset elements configurations make it possible to refresh/reset this content view when receiving the listed Seam event names. Only
documentChildrenChanged are handled by default, but it is possible to react to new events by adding a method with an observer on this event on a custom Seam component, and call the method
contentViewActions.refreshOnSeamEvent(String seamEventName) or
Refresh will keep current settings, and will force the query to be done again. Reset will delete content views completely from the cache, and force complete re-generation of the content view, its provider, and the search document model if set.
Document Content Views
It is possible to define content views on a document type. This makes it easier to define folderish documents views.
Here is the default configuration of content views for Nuxeo folderish documents:
document_content content view will be displayed on this folder default view, and the
document_trash_content content view will be displayed on the Trash tab.
category attribute is filled from XHTML templates to render all content views defined in a given category.
showInExportView attribute is used to check whether this content view should be displayed in the document export view (and PDF export).
If several content views are filled in the same category, both will be displayed on the same page.
Rendering is done using methods set on Generic Seam components:
org.nuxeo.ecm.webapp.contentbrowser.DocumentContentViewActions) to handle document content views categories.
A typical usage of content views, to render the results, would be:
/incl/content_view.xhtml handles generic rendering of the given content view (content view title, pagination, result layout selection, list rendering, actions rendering) . It inserts names region that can be overridden when using the
The current version of this template is here: https://github.com/nuxeo/nuxeo-jsf/blob/master/nuxeo-platform-webapp-base/src/main/resources/web/nuxeo.war/incl/content_view.xhtml.
Here is the sample rendering of the search form defined on a content view named "document_content_filter":
Here is a typical way of refreshing or resetting a provider named "advanced_search" from the interface: