Widget reference

Checkbox widget

A single checkbox to set a 'true' or 'false' value in the XML document.

Add a boolean element to your schema:

<xs:element name="tobeornottobe" type="xs:boolean"/>

Add a checkbox widget to your layout:

<checkbox id="/document/tobeornottobe"/>

That's all!

Checkboxgroup widget

A multivalue field, represented as checkboxes.

Using a static list of values

Add an element to your schema, and define an enumeration within a restriction:

<xs:element name="chubbychecker" minOccurs="1" maxOccurs="unbounded">
  <xs:simpleType>
    <xs:restriction base="xs:string">
      <xs:enumeration value="Dutch"/>
      <xs:enumeration value="English"/>
    </xs:restriction>
  </xs:simpleType>
</xs:element>

In the layout file, add a 'checkboxgroup' widget and set the 'maxWidth' attribute to the desired value:

<checkboxgroup id="/document/chubbychecker" maxWidth="5"/>

Using a dynamic list of values

Add a string element to your schema, and specify a 'maxOccurs' of 'unbounded'. The value for 'minOccurs' can be any positive number or zero.

<xs:element name="chubbychecker" type="xs:string" minOccurs="1" maxOccurs="unbounded"/>

In your business logic, add a rule for the element and specify a list source (just as you would for a dropdown widget, see description above):

<rule for="/document/chubbychecker">
  <selectionsource src="cocoon://pipeline/generating/list.xml" type="list" dynamic="false" />
</rule>

In the layout file, add a 'checkboxgroup' widget and set the 'maxWidth' attribute to the desired value:

<checkboxgroup id="/document/chubbychecker" maxWidth="5"/>

Datefield widget

A text input box with a calendar popup date picker.

Add a date element to your schema:

<xs:element name="doomsday" type="xs:date"/>

In the layout, add the datefield widget:

<datefield id="/document/doomsday"/>

Optionally, you can specify the input and output format of the date in the business logic file:

<rule for="/document/doomsday">
  <convertor use="storage" datatype="date" type="formatting" pattern="yyyyMMdd"/>
  <convertor use="datamodel" datatype="date" type="formatting" pattern="dd-MM-yyyy"/>
</rule>

The storage pattern is an example. You can customize it to your needs using the Java SimpleDateFormat syntax. Both patterns may contain hours, minutes and seconds, but the calendar for this widget does not support them.

Datetimefield widget

The datetimefield widget was introduced in CMS version 6.05.04

A text input box with a calendar popup date plus time picker.

Add a date element to your schema:

<xs:element name="countdown" type="xs:date"/>

In the layout, add the datetimefield widget:

<datetimefield id="/document/countdown"/>

Optionally, you can specify the input and output format of the date in the business logic file:

<rule for="/document/countdown">
  <convertor use="storage" datatype="date" type="formatting" pattern="yyyyMMddHHmmss"/>
  <convertor use="datamodel" datatype="date" type="formatting" pattern="dd-MM-yyyy HH:mm:ss"/>
</rule>

The storage pattern is an example. You can customize it to your needs using the Java SimpleDateFormat syntax. The datamodel pattern should not be altered.

Documentlist widget

Add a string element to your schema:

<xs:element name="list" type="xs:string"/>

Add a documentlist widget to the layout:

<documentlistpreview id="/document/list"/>

To select documents for inclusion in the list, we use the clipboard. So, define a clipboard picker in the business logic:

<pickers>
  <picker id="searchpicker" class="ClipboardPicker"/>
</pickers>

And create a rule for your list element:

<rule for="/root/list">
  <picker id="searchpicker" label="pickerlabel" class="ClipboardPicker"
          uriPrefix="/content/" uriPostfix=".xml" listElementName="list"
          itemElementName="article" uriAttributeName="id"/>
  <binding-class>nl.hippo.cocoon.forms.binding.XmlAsStringBinding</binding-class>
</rule>

As you can see, the searcpicker has some attributes:

In the example above the resulting structure will look like:

<root>
  <list>
    <article id="somelocation"/>
    <article id="otherlocation"/>
  </list>
</root>

Dropdown widget

To configure a dropdown, you need to add some code to:

• your schema
• your layout
• optionally your businesslogic (depending on whether you need a dynamic list or a static list , see below).

The layout is the easiest, just add:

<dropdown id="/document/dropdeadfred"/>

Static lists

If you need a STATIC list of items to populate your dropdown (the values are not going to be changed) :

XSD:

<xs:element name="dropdeadfred">
  <xs:simpleType>
   <xs:restriction base="xs:string">
      <xs:enumeration id="hippo" value="Hippo"/>
      <xs:enumeration id="rhino" value="Rhino"/>
      <xs:enumeration id="elephant" value="Elephant"/>
    </xs:restriction>
  </xs:simpleType>
</xs:element>

OR:

<xs:element name="dropdeadfred" type="myListType"/>

<xs:simpleType name="myListType">
  <xs:restriction base="xs:string">
    <xs:enumeration id="hippo" value="Hippo"/>
    <xs:enumeration id="rhino" value="Rhino"/>
    <xs:enumeration id="elephant" value="Elephant"/>
  </xs:restriction>
</xs:simpleType>

(I prefer the last one, since you can reuse the type definition)

If you want to i18n the values, you could add the following section to your businesslogic:

<type-rule type="myListType">
  <i18n><list-prefix>myproject.lists</list-prefix></i18n>
</type-rule>

This will auto-generate the i18n keys myproject.lists.value1 , myproject.lists.value2 in your dropdown element, etc. Add these to your i18n catalogue and you're done.

Dynamic lists

The 2nd option is a dynamic list.

Change the XSD:

<xs:element name="dropdeadfred" type="xs:string"/>

in businesslogic:

<businesslogic>
  <rule for="/document/dropdeadfred">
     <selectionsource src="cocoon://some/source/pipeline" type="nodetree" dynamic="true"/>
  </rule>
</businesslogic>

the pipeline (or another InputSource like, repository://) generating the source for the dropdown can be of two formats: 'nodetree' or 'list'.
An example of a list document:

<document>
  <item>value1</item>
  <item>value2</item>
  <item>value3</item>
</document>

The list format is a flat list of values. The values are shown in the dropdown and are also stored in the XML.

An example of a nodetree document:

<nodes>
  <node id="someKey1" value="value1"/>
  <node id="someKey2" value="value2">
    <node id="someKey2_1" value="value2_1"/>
  </node>
</nodes>

The values are shown in the editor, the ids are stored in the XML. The values are presented as follows:

value2 > value2_1

From Hippo CMS release 6.04 , you can specify default values for list-based dropdowns. A default value is the value that will be selected in the dropdown when no value is stored in the XML. To specify a default item in a nodetree document, set it's default attribute to true, e.g.:

<nodes>
  <node id="someKey1" value="value1"/>
  <node id="someKey2" value="value2" default="true"/> <!-- default value -->
</nodes>

Example: using a ldap userlist as source for a dropdown

In the CMS, see /editing/dialogs/listpicker/plugins/ldap/sitemap.xmap for an example of how to generate a simple list of LDAP users on your local intranet. You have to configure the LDAP lookup in the above sitemap:

• LDAP server
• LDAP searchbase
• username / password of a LDAP user with rights to browse the LDAP directory

After you have successfully generated a list of LDAP users, apply the instructions in the section "dynamic lists" to populate a dropdown with LDAP users. For the selection-source, use cocoon://editing/dialogs/listpicker/general-plugins/ldap/list.xml , for the format , use "list".

Form field widget

The formfield widget is used to represent a html form. The datamodel and layout of the formfield is auto-generated by the CMS, so you don't have to anything! Sometimes though, you want to attach metadata to a form, such as "mailto address", or "successmessage" (is displayed when the user submits the form on the website). Here's an example of how to do that:

Schema code:

<xs:element name="form">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="mailto" type="xs:string" minOccurs="1"/>
      <xs:element name="successmessage" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>
</xs:element>

Layout code:

<template name="/form">
  <hbox>
    Mailto address: <textfield id="/form/mailto"/>
  </hbox>
  <hbox>
    Success message: <htmlfield id="/form/successmessage"/>
  </hbox>
  <formfield id="/form"/>
</template>

The XML output format of the formfield looks like this:

<form>
  <formElement type="[type]">
     <name>some_name</name>
     <title>label of the field</title>
     <description>some extended description of the field</description>
     <obligatory>true|false</obligatory> <!-- boolean value -->
     <!-- content below depends on "type" of formElement -->
  </formElement>
  <formElement type="[type]">
    <!-- .. -->
  </formElement>
  <!-- .... -->
  <formElement type="[type]">
    <!-- .. -->
  </formElement>
</form>

[type] can be any of these (as of version 6.03.06):

Every formElement always contains these elements:

Next to these elements, the form element contains elements which are specific to the type of the element. E.g. or type "optionboxes" there will be a list of option elements.

HTML Field widget

A rich text editing box.

Add a string element to your schema:

<xs:element name="worlddominationplan" type="xs:string"/>

In the business logic, define the javascript library to use for the richt text editing box. Hippo CMS contains a default library in /editing/cf2/js/htmlarea.js, but you can create your own (e.g. to define different configurations to add or hide certain buttons in the toolbar). Also add a rule for your element, defining the binding class and HTML converter for the field. Use the default ones provides by Hippo CMS.

<libs>
  <lib src="/editing/cf2/js/htmlarea.js"/>
</libs>

<rule for="/document/worlddominationplan">
  <binding-class>nl.hippo.cocoon.forms.binding.HTMLAreaBinding</binding-class>
  <convertor type="htmlcleaner" config="cocoon://editing/cf2/HtmlCleanerConfiguration.xml" use="datamodel"/>
</rule>

Finally, add the HTML Field widget to the layout. You need to define the initialization function to use ("myDemoHtmlArea" is the default one, but you can define your own in a custom javascript library).

<htmlfield id="/document/worlddominationplan" initFunc="myDemoHtmlArea"/>

What is important to realize is that the root element for the htmlfield needs to be present in the XML document! For the above example this element is /document/worlddominationplan. When you have a list of htmlfields, sometimes you have to insert the xml element containing the html. An example: suppose you have a container element /root/box which is repeated, and inside /root/box there is a field /root/box/html which is an htmlfield. The html element is not added automatically to the underlying XML, so you have to specifically insert the html element every time a box element is added, in the following way:

<rule for="/root/box">
  <binding>
    <insert-node>
      <html/>
    </insert-node>
  </binding>
</rule>

Note: As of version v6.03.05 of the Hippo CMS, the htmlfield element supports a new attribute (@preview) which triggers a lazy-load mechanism for the HtmlArea, when set to 'true'. This means the HtmlArea will always be rendered as plain html, with an edit button. Clicking on the button will hide the preview element and create a HtmlArea instance so the user can start editing. This is especially convient when a page contains multiple htmlfields, since page-loading is faster, or when users have memory problems because of HtmlAreas not being GC properly.

<htmlfield id="/document/worlddominationplan" initFunc="myDemoHtmlArea" preview="true"/>

When multiple previewable htmlfields are being used on a page, only one htmlfield can be edited at a time. You can also mix previewable and default htmlfields on a single page.

Listitempreview widget

The listitempreview widget lets you add one or more values from a list of values, using a javascript picker, usually in the form of a popup. You'll have to make changes to the schema, layout and businesslogic configuration files to get this to work.

Schema

To get a working listitempreview widget, you have to define a basic string element in your schema:

<xs:element name="root">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="items" type="xs:string"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

Business logic

Next, add these entries in your businesslogic file:

<sources>
    <source id="exampleSource" type="nodetree">repository://content/lists/exampleList.xml</source>
  </sources>

  <pickers>
    <picker id="examplePicker" class="GenericPicker">
      <arg><![CDATA['/editing/dialogs/listpicker/key-value-pairs?editor=cforms&source=repository://content/lists/exampleList.xml']]></arg>
    </picker>
  </pickers>

  <rule for="/root/items">
    <picker id="examplePicker"/>
    <value-lookup source-id="exampleSource"/>
  </rule>

There are four main elements here:

• sources/source

Defines a source, which you can later refer to to actually use it. The attribute id should be unique. The type attribute defines the XML format of the list document. The format can be any of (collection|list|nodetree). However, nodetree is the one most commonly used (see "Dynamic Lists" on this page for an example). The text value inside the source element should be a valid Cocoon source (repository://.. / cocoon://.., etc).

• pickers/picker

Defines a javscript picker. The id attribute should be unique. The class attribute is the Javascript classname of the picker object. There are two predefined pickers inside the editor's javascript code: ResourcePopup2 and GenericPicker. The first one is used for picking documents from the repository. The second one is a "generic" picker, in the sense that it can load values from any source. Use the last picker for a listitempreview widget. You have to provide one argument to the picker: the url to the actual popup. The CMS has this html code available for picking values from a nodetree list, just use this url:

/editing/dialogs/listpicker/key-value-pairs

and pass the following request parameters:

• rule/picker

Binds a defined picker (defined in pickers/picker to a specific widget.

• value-lookup

This configuration is needed to show the correct labels for the IDs stored in the widget. For example, when you pick a value using the listitempreview widget, you store the ID "0001", but you want to show it's corresponding label from the list document, e.g. "Label for item". value-lookup is used to make this mapping: the source-id attribute refers to a defined source (defined under sources/source.

Layout

The last step is to add a listitempreview widget to your layout file:

<listitempreview id="/root/items" value-type="comma-separated"/>

The value-type is used to control the display of the picked values. If you leave it empty, the picked values are shown in comma-separated format. If you use "comma-separated", the editor knows the picked value is in CSV format, and will display the values in a neater way: a bulleted list.

Picture Preview widget

Allows the user to select an image from the Assets repository, and shows a preview thumbnail of the selected picture in the editor.

Add a string element to your schema:

<xs:element name="mugshot" type="xs:string"/>

In your business logic, define a picker for Assets (if you haven't done it already):

<pickers>
  <picker class="ResourcePopup2" id="asset">
    <arg><![CDATA['/explorer/resource-picker/binaries/?mode=asset']]></arg>
  </picker>
</pickers>

Define a rule for your element, to link the picker with the widget:

<rule for="/document/mugshot">
  <picker id="asset"/>
</rule>

Finally, add the Picture Preview widget to the layout file. Optionally, you can define the width and height of the preview thumbnail using the attributes @pic-width and @pic-height. You can also define an icon (instead of the 'Browse' button) for the picker using @picker-icon.

<picturepreview id="/document/mugshot" pic-height="50"/>

Radiogroup widget

Using a static list of values

Add an element to your schema, and define an enumeration within a restriction:

<xs:element name="radiogaga">
  <xs:simpleType>
    <xs:restriction base="xs:string">
      <xs:enumeration value="Dutch"/>
      <xs:enumeration value="English"/>
    </xs:restriction>
  </xs:simpleType>
</xs:element>

In your layout, add the 'radiogroup' widget:

<radiogroup id="/document/radiogaga"/>

Using a dynamic list of values

Add a string element to your schema:

<xs:element name="radiogaga" type="xs:string"/>

In your business logic, add a rule for your element and define a selection source (just as you would for a dropdown widget):

<rule for="/document/radiogaga">
  <selectionsource src="cocoon://pipeline/generating/list.xml" type="list" dynamic="false"/>
</rule>

In your layout, add the 'radiogroup' widget:

<radiogroup id="/document/radiogaga"/>

Repeater widget

A repeater can repeat one or more fields in the editor form. The user can add and remove repeated field(s) as needed. As an example, suppose you want users to be able to add an arbitrary number of tags to a document. Your XML structure could look like this:

<document>
  <tags>
    <tag>cocoon</tag>
    <tag>hippo</tag>
    <tag>cms</tag>
  </tags>
</document>

In your schema, this structure could be defined as follows:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="document">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="tags">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="tag" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

The layout file could look like the example below. What is important here is that the repeated element MUST have a seperate template defined for it, e.g. the element /document/tags/tag has a corresponding template for it. This template must then be called by using the display tag. The script below also contains a macro for the 'repeater header', which contains (in this case) a button to add a tag element. The macro is also called from the main template, by a macro-call element.

<layout xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://repository.hippocms.org/schemas/cms/layout.xsd">
  <template name="/">

    <!-- editor messages -->
    <messagewidget class="demoMessages"/>
    <validationwidget class="demoValidationMessages"/>

    <!-- content fields -->
    <group type="columns">

      <!-- Repeater block -->
      <group type="container">
        <macro-call id="repeater-header">
          <param name="path">/document/tags/tag</param>
        </macro-call>
        <display id="/document/tags/tag"/>
      </group>

    </group>

  </template>

  <macro name="repeater-header">
    <grid width="100%">
      <cell row="1" col="1"> ${label} </cell>
      <cell row="1" col="1">
        <action action="add" ref="${path}"/>
      </cell>
    </grid>
  </macro>

  <template name="/document/tags/tag">
    <gridrow>
      <cell col="1" colspan="2">
        <action action="delete" ref="/document/tags/tag"/>
      </cell>
    </gridrow>
    <textfield id="/document/tags/tag"/>
  </template>

</layout>

Finally, make sure the initial document template contains the tags container element for the tag elements:

<document>
  <tags/>
</document>

Selectgroup

A multivaluefield represented as a select box.

Using a static list of values

Add an element to your schema, and define an enumeration within a restriction:

<xs:element name="multiculti" minOccurs="1" maxOccurs="unbounded">
  <xs:simpleType>
    <xs:restriction base="xs:string">
      <xs:enumeration value="Dutch"/>
      <xs:enumeration value="English"/>
    </xs:restriction>
  </xs:simpleType>
</xs:element>

No need for any business logic, so add the selectgroup widget to the layout straight away:

<selectgroup id="/document/multiculti"/>

Using a dynamic list of values

Add a string element to your schema:

<xs:element name="multiculti" type="xs:string" minOccurs="1" maxOccurs="unbounded"/>

Add a rule to the business logic and define the selection list containing the values:

<rule for="/document/multiculti">
  <selectionsource xsrc="cocoon://pipeline/generating/list.xml" type="list" dynamic="false" />
</rule>

Finally, add the selectgroup widget to the layout:

<selectgroup id="/document/multiculti"/>

Shootboxgroup widget

Version information The Shootboxgroup widget did not work correctly in Hippo CMS versions up to and including 6.03.05. This had been fixed in Hippo CMS 6.03.06 and newer versions.

Two multivalue select boxes, with buttons to move options from one to the other. Also know as Option Transfer.

Using a static list of values

Add an element to your schema, and define an enumeration within a restriction:

<xs:element name="shooter" minOccurs="1" maxOccurs="unbounded">
  <xs:simpleType>
    <xs:restriction base="xs:string">
      <xs:enumeration value="Dutch"/>
      <xs:enumeration value="English"/>
    </xs:restriction>
  </xs:simpleType>
</xs:element>

In the layout file, add a 'shootboxgroup' widget:

<shootboxgroup id="/document/shooter"/>

Using a dynamic list of values

Add a string element to your schema, and specify a 'maxOccurs' of 'unbounded'. The value for 'minOccurs' can be any positive number or zero.

<xs:element name="shooter" type="xs:string" minOccurs="1" maxOccurs="unbounded"/>

In your business logic, add a rule for the element and specify a list source (just as you would for a dropdown widget, see description above):

<rule for="/document/shooter">
  <selectionsource src="cocoon://pipeline/generating/list.xml" type="list" dynamic="true" />
</rule>

In the layout file, add a 'shootboxgroup' widget:

<shootboxgroup id="/document/shooter"/>

URL Preview widget

For internal links (link to another document in the repository) you can use the "urlpreview" widget.
It's also possible to use this widget for internal + external links.

In your schema, add a string element:

<xs:element name="href" type="xs:string"/>

In the layout xml file, add an urlpreview widget:

<urlpreview id="/document/href"/>

If you want users to be able to manually enter external links, add readonly="false" to the widget, like so:

<urlpreview id="/document/href" readonly="false"/>

Do not use READONLY="TRUE" on this element. It seems to work, but the content picked is not saved.

Finally, in the business logic, define a picker (to browse for the document to link to) and add a rule for the url element:

<pickers>
  <picker class="ResourcePopup2" id="content">
    <arg><![CDATA['/explorer/resource-picker/content/']]></arg>
  </picker>
</pickers>

<rule for="/document/href">
  <picker id="content"/>
</rule>

In the editor form you will now see a browse button. If you click on it, you can select a document to link to by double clicking on it. In the editor the relative URL will be shown.

If you save the document, the url element will look like this:

<href>/content/test.xml</href>

Value widget

Version information Available from version 6.04.01.

This widget outputs the value of an XML element. An example:

<value id="/root/title"/>

This will simply display the contents of the /root/title as text. Its content is not saved in the node, use it as (second/third) readonly display of the field. Can be used as a display of the original text for translation purposes.

Other elements

Document properties

From version: 6.04.xx

To show document properties inside the editor, simply include a property element somewhere inside your layout definition:

Last saved by <property name="lastModifiedBy" namespace="http://hippo.nl/cms/1.0" type="string"/>

The name and namespace attributes are the WEBDAV property's name and namespace, obviously. The type attribute is optional in this case, since the default datatype for property is string . There is one more datatype, the date datatype. An example:

<property name="modificationdate" namespace="DAV:" src-pattern="yyyy-MM-dd'T'hh:mm:ss" pattern="" type="date"/>

For date properties, the src-pattern , pattern and type attributes are mandatory. The src-pattern attribute specifies the format of the date property value. The pattern value is the format of the date value as shown in the editor. For the pattern you can also use 'short', 'medium', 'long' or 'full', besides a combination of "yyyy" / "MMM" / etc.