Table of Contents
The User Interface framework uses different kinds of concepts to make the interface configurable in the same way that the application itself is.
Links and pages that appear on the site can be the result of a "static" template written in the XHTML language, but can also be the result of a configuration change, taken into account thanks to more "generic" XHTML pages.
The following chapters will explain how configuration and templating combine to achieve the UI of the site.
In this chapter, an action will stand for any kind of command that can be triggered via user interface interaction. In other words, it will describe a link and other information that may be used to manage its display (the link label, an icon, security information for instance).
Custom actions can be contributed to the actions service, using its extension point. Their description is then available through this service to control where and how they will be displayed.
An action can be registered using the following example extension:
<extension target="org.nuxeo.ecm.platform.actions.ActionService"
point="actions">
<action id="logout" link="#{loginLogoutAction.logout}"
label="command.logout">
<category>USER_SERVICES</category>
</action>
</extension>
Example 6.1. Example of an action registration
The above action will be used to display a "logout" link
on the site. Here are its properties:
id: string identifying the action. In
the example, the action id is "logout".
label: the action name that will be
used when displaying the link. In the example, the label is
"command.logout". This label is a message that will be
translated at display.
link: string representing the command
the action will trigger. This string may represent a different
action given the template that will display the action. In the
example, a JSF command link will be used, so it represents an
action method expression. The seam component called
"loginLogoutAction" holds a method named "logout" that will
perform the logout and return a string for navigation.
category: a string useful to group
actions that will be rendered in the same area of a page. An
action can define several categories. Here, the only category
defined is "USER_SERVICES". It is designed to group all the
actions that will be displayed on the right top corner of any
page of the site.
Other properties can be used to define an action. They are
listed here but you can have a look at the main actions contributions
file for more examples:
nuxeo-platform-webapp-core/srs/main/resources/OSGI-INF/actions-contrib.xml.
filter-ids: id of a filter that will be
used to control the action visibility. An action can have
several filters: it is visible if all its filters grant the
access.
filter: a filter definition can be done
directly within the action definition. It is a filter like
others and can be referred by other actions.
icon: the optional icon path for this
action.
confirm: an optional Javascript
confirmation string that can be triggered when executing the
command.
order: an optional integer used to sort
actions within the same category. This attribute may be
deprecated in the future.
enabled: boolean indicating whether the
action is currently active. This can be used to hide existing
actions when customizing the site behavior.
Actions extension point provides merging features: you can change an existing action definition in your custom extension point provided you use the same identifier. Properties holding single values (label, link for instance) will be replaced using the new value. Properties holding multiple values (categories, filters) will be merged with existing values.
Actions in the same category are supposed to be displayed in the same area of a page. Here are listed the main default categories if you want to add an action there:
USER_SERVICES: used to display actions
in the top right corner of every page. The link attribute should
look like a JSF action command link. See the example
above.
VIEW_ACTION_LIST: used for tabs
displayed on every document. As each tab is not displayed in a
different page, but just includes a specific template content in
the middle of the page, the link attribute has to be a template
path. For instance:
<action id="TAB_VIEW" link="/incl/tabs/document_view.xhtml" enabled="true"
order="0" label="action.view.summary">
<category>VIEW_ACTION_LIST</category>
<filter-id>view</filter-id>
</action>
<action id="TAB_CONTENT" link="/incl/tabs/document_content.xhtml" order="10"
enabled="true" label="action.view.content">
<category>VIEW_ACTION_LIST</category>
<filter-id>view_content</filter-id>
</action>
SUBVIEW_UPPER_LIST: used to display
actions just below a document tabs listing. As
USER_SERVICES, these actions will be
displayed using a command link, so the link attribute has to be
an action method expression. For instance:
<action id="newSection" link="#{documentActions.createDocument('Section')}"
enabled="true" label="command.create.section"
icon="/icons/action_add.gif">
<category>SUBVIEW_UPPER_LIST</category>
<filter id="newSection">
<rule grant="true">
<permission>AddChildren</permission>
<type>SectionRoot</type>
</rule>
</filter>
</action>
<action id="newDocument" link="select_document_type" enabled="true"
label="action.new.document" icon="/icons/action_add.gif">
<category>SUBVIEW_UPPER_LIST</category>
<filter-id>create</filter-id>
</action>
An action visibility can be controlled using filters. An action filter is a set of rules that will apply - or not - given an action and a context.
Filters can be registered using their own extension point, or registered implicitly when defining them inside of an action definition:
<filter id="view_content">
<rule grant="true">
<permission>ReadChildren</permission>
<facet>Folderish</facet>
</rule>
<rule grant="false">
<type>Root</type>
</rule>
</filter>
Example 6.2. Example of a filter registration
<action id="newSection" link="#{documentActions.createDocument('Section')}"
enabled="true" label="command.create.section"
icon="/icons/action_add.gif">
<category>SUBVIEW_UPPER_LIST</category>
<filter id="newSection">
<rule grant="true">
<permission>AddChildren</permission>
<type>SectionRoot</type>
</rule>
</filter>
</action>
Example 6.3. Example of a filter registration inside an action registration
A filter can accept any number of rules. It will grant
access to an action if, among its rules, no denying rule
(grant=false) is found and at least one granting
rule (grant=true) is found. A general rule to
remember is that if you would like to add a filter to an action that
already has one or more filters, it has to hold constraining rules: a
granting filter will be ignored if another filter is already too
constraining.
If no rule is set, the filter will grant access by default.
The default filter implementation uses filter rules with the following properties:
grant: boolean indicating whether this
is a granting rule or a denying rule.
permission: permission like "Write"
that will be checked on the context for the given user. A rule
can hold several permissions: it applies if user holds at least
one of them.
facet: facet like "Folderish" that can
be set on the document type
(org.nuxeo.ecm.core.schema.types.Type) to
describe the document type general behavior. A rule can hold
several facets: it applies if current document in context has at
least one of them.
condition: EL expression that can be
evaluated against the context. The Seam context is made
available for conditions evaluation. A rule can hold several
conditions: it applies if at least one of the conditions is
verified.
type: document type to check against
current document in context. A rule can hold several types: it
applies if current document is one of them. The fake 'Server'
type is used to check the server context.
schema: document schema to check
against current document in context. A rule can hold several
schemas: it applies if current document has one of them.
Filters do not support merging, so if you define a filter with an id that is already used in another contribution, only the first contribution will be taken into account.
It is important to understand that an action does *not* define the way it will be rendered: This is left to pages, templates and other components displaying it. Most of the time, actions will be rendered as command links or command buttons.
For instance, actions using the USER_SERVICES
category will be rendered as action links:
<nxu:methodResult name="actions"
value="#{webActions.getActionsList('USER_SERVICES')}">
<nxu:dataList layout="simple" var="action" value="#{actions}"
rowIndexVar="row" rowCountVar="rowCount">
<h:outputText value=" | " rendered="#{row!=(rowCount-1)}" />
<nxh:commandLink action="#{action.getLink()}">
<t:htmlTag value="br" rendered="#{row==(rowCount-1)}" />
<h:outputText value="#{messages[action.label]}" />
</nxh:commandLink>
</nxu:dataList>
</nxu:methodResult>
The nxu:methodResult tag is only used to
retrieve the list of actions declared for the
USER_SERVICES category. The
nxh:commandLink is used instead of a simple
h:commandLink so that it executes commands that
where described as action expression methods.
Another use case is the document tabs: actions using the
VIEW_ACTION_LIST category will be rendered as
action links too, but actions are managed by a specific seam component
that will hold the information about the selected tab. When clicking
on an action, this selected tab will be changed and the link it points
to will be displayed.
XXX AT: make the difference between a view in a JSF way (navigation case view id, navigation case output) and views in a nuxeo 5 (type view, action link...)
Please refer to the tag library documentation available at http://doc.nuxeo.org/5.1/tlddoc/.