- Page restrictions apply
- Added by Anahide Tchertchian, last edited by Solen Guitter on Jul 07, 2016 (view change)
Content Views can be configured using Studio, check out the Content Views documentation.
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 perform several actions.
- Defining the NXQL query that will be used to retrieve the documents, filtering some of them (documents in the trash for instance).
- Passing on contextual parameters to the query (the current container identifier).
- Defining a filtering form to refine the query.
- Defining what columns will be used for the rendering of the list, and how to display their content.
- Handling selection of documents, and actions available when selecting them (copy, paste, delete...).
- Handling sorting and pagination.
- Handling caching, and refresh of this cache when a document is created, deleted, modified, etc.
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 what query will be performed. Here it is a query on a core session, using a pattern with one parameter.
parameter and property elements
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. 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 "1000" 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 1000 items will be returned. This is configurable by contributing the property
nuxeo.pageprovider.default-max-page-size to the Configuration service.
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 by contributing the property
org.nuxeo.ecm.platform.query.nxql.defaultNavigationResultsto the Configuration service.
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 be 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
parameter elements. It can also accept "named parameters", e.g. parameters prefixed by a comma, that can also match the search document model properties (for instance:
SELECT * FROM Document WHERE dc:title = :searchdoc:title ).
fixedPart element also accepts attributes to better control its behaviour:
statementmakes is possible to declare the select statement to use (as contrary to the
fixedPartelement is not supposed to hold the select statement). This optional parameter default to "Select * from document" for default core page providers.
escapeParametersis a boolean value that allows to avoid escaping parameters when building the fixed part (defaults to true).
quoteParametersis a boolean value that allows to avoid adding quotes around the parameter (defaults to true). This is useful when parameters actually hold a complete predicate, for instance (and in this case, the
escapeParameterselement must also be set to true.
Note that when using an Elasticsearch page provider you can use NXQL hints inside predicates like this:
quoteParameters are also accepted on the
It might be useful to add the ContentViewDisplay facet (this facet includes the
content_view_display schema, using the
cvd prefix) to the definition of the
AdvandedSearch document type, when configuring one of the elements described below:
The searchDocumentType element is an alternative way to define the search document type to use on the whereClause element. It's been made available to make it possible to define such a search document model, even if no whereClause is defined. This can be useful when defining aggregates without any other filtering, for instance.
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. This element accepts a
filterDisplayType attribute: when set to value
quick, it will 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.
showFilterForm element makes it possible to show this form above the content view results.
waitForExecution element waits for a boolean value, and defaults to false. When set to true, the query will not be executed right away: this is useful when user has to submit filtering criteria first, when search criteria are presented on the side of the page, for instance. When submitting the filtering form, the content view will be marked as executed (it can also be explicitely marked as executed by using the content view API) and search results will be presented.
waitForExecutionSentence element can also be used to customize the text presented to the user when the content view is not executed yet. Note that the sentence will be translated if the
translateEmptySentence element is set to true.
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.
Listing layouts with a name that ends with
2_columns will be displayed on two columns by default. The layout name will be used as a message key for the selector label.
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 Selection 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.
Note that default actions usually hard-code their usage of a given selection list (whether when filtering the action visibility, whether when performing the action on the list of documents).
searchDocument variable can be used in EL expressions to bind the page size, the sort information 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 selected columns set on the search document model already defined for filtering:
resultLayout element can be filled on a content view using an EL expression: it will be used to resolve the current result layout.
Sample usage, showing how to reuse the selected result layout set on the search document model already defined for filtering:
Additional rendering information
Additional rendering information can also be set, to be used by templates when rendering the content view:
showTitle 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 used to display the message stating that there are no elements in the content view.
showRefreshCommand are used to control the display of the page size selector, and of the "refresh current page" button. They both default to true.
Since version 7.3, the
pageSizeOptions element allows to configure available options for page size selection in the UI. If not filled, values 10, 20, 30, 40 and 50 will be displayed by default, as well as the page provider default
pageSize element value (as well as the current page size, if not already present in this list).
Check out chapter Content Views Display for more display information and customization.
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.
cache size "0" behaviourIcon
When using value "0", the content view is cached anyhow, but its page provider is refreshed every time it is rendered.
As this behavior is costly, using refresh events can be enough most of the time. But it is not possible to trigger a refresh for other users when using Seam events, so this configuration makes it possible to make sure that the content view is up to date when other users may have an impact on its content.
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.