Pages UI extension examples

Dialogs and Widgets

Everything is a component - a dialog widget also. Widgets are used in the edit dialog components to declare the forms for property editing, see the following dialog examples:

Each widget is rendered using the 'widget' tag of the Pages tag library (cpp):

<cpp:widget label="Link Title" property="linkTitle" type="textfield" i18n="true" hint="the text for the link tooltip (optional)"/>

This 'widget' tag is using the WidgetManager service which is collecting all implemented widgets of a system to determine the implementation of a widget type and delegate the rendering to this implementation.

The widget implementation itself is a Sling component. The resource name of this component declares the widgets 'type'. Widgets are searched in the resolvers search path with the known overriding mechanism.

Pages Tools Definition

Similar to the tools set of the Composum Console (part Composum Nodes) the set of available tools in the Composum Pages editing frame can be configured, extended and restricted.

In the Console the children of each resource of the resource type composum/nodes/console/page are used as console tool definitions to embed additional tools in the console view; the Pages UI is embedding a hook to switch to 'Pages' from the Console:

The Composum Pages UI has a similar tools registry. The children of each resource of the resource type composum/pages/tools/collection are used as Pages tool definitions to embed additional tools in the Pages UI view; e.g. the Composum Platform Workflow extension is embedding the workflow inbox in the Pages main navigation on the left side:

Also similar to the console in the Pages UI the category is important to declare the context in which the tool is useful. The combination of categories controls the tools visibility:

  • navigation / context (one only):
    the tool is placed on the left (navigation) or on the right sidebar (context); navigation tools are general tools - they must be independent from the current selection; the context tools are shown only if the element type category matches...
  • site / page / container / element (combination possible):
    if one or more of the element type categories specified for a tool (useful for context tools only) the tool is shown if the current selection matches to one of the specified element types
  • preview / browse / edit / develop (combination possible):
    if display mode categories defined the tool is shown only if the current display mode matches to one of the specified display mode categories

The access to the registered tools can be restricted by ACLs. If a child resource of a registered tools collection is not readable for the current user this tool is not available for that user in the user interface.

All tools of the Composum Pages edit frame are declared as described above. So it's easy to customise the editing user interface.


A custom Widget

The simplest way to implement a new widget is the creation of a new widget resource derived from an existing widget component. The demonstration example in the prototype project contains such a widget.

The 'confidentiality' widget is extending the standard 'select' widget. Some attributes of the 'select' widget are predefined in the new widget ('-t-/-d-/-p-' = 'tenant/domain/project'):

apps/-t-/-d-/-p-/widgets/confidentiality xml
<?xml version="1.0" encoding="UTF-8"?> <jcr:root xmlns:cpp="http://sling.composum.com/pages/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:sling="http://sling.apache.org/jcr/sling/1.0" jcr:primaryType="cpp:Widget" sling:resourceSuperType="composum/pages/commons/widget/select"> <attributes jcr:primaryType="nt:unstructured" default="internal" options="secret,confidential,internal,public" required="true"/> </jcr:root>

All resources of the primary type 'cpp:Widget' are registered by the widget manager using their names as the type key. All predefined tag attributes (the <attributes> node) are merged with the attributes specified in the 'widget' tag of the dialog which is using that widget (with precedence of the dialog attributes over the predefined attributes).</attributes>

Let's add a new property to our new image component using the 'confidentiality' widget...

... and we can use our new widget:

Such a widget component can be arbitrarily complex. Necessary CSS or JS code should be added to an appropriate client library. All widgets of the Composum Pages component development framework are implemented as such components - look at the 'Commons Widgets'  of the Pages implementation to find examples:

An additional Context Tool

As an example let's create a new panel (a tab) in the context tools area (right sidebar) which is shown if an element (not a container) is selected in 'de' edit mode.

We need a Sling component which is implementing the new context tool:

This simple panel is presenting a headline and the path and name of the selected element. The DIV element structure adopted from the other Pages tools - this makes it easy to integrate the new tool using the CSS style of the other tools.

After adding  the resource which describes our new tool...

... and with a small extension of the Pages client library for the edit frame composum.pages.edit.frame...

...our new context tool is working and looks like this: