Defining and Using a Collection Field

A collection field is defined in the content-type resource as a field element with the type attribute collection. It also has a src attribute for specifying the data source, which you can use in two different ways:

Only using an Atom feed

In this case, you set the src attribute to point directly to an Atom feed. When the user types in the collection field, CUE searches through the entries in this feed and displays the results in a list below the field.

Using OpenSearch

In this case, you set the collection field's src attribute to point an Atom feed that contains a search link referencing an OpenSearch document. If the specified feed contains a link to an OpenSearch document, then the entries in the feed are not used (it can, in fact, be an empty feed). Instead, CUE retrieves the OpenSearch document and composes a query URL by combining the search template it contains with whatever the user types in the collection field. It displays the results of this search in the list below the field. In order for this method to work, the composed search query must return an Atom feed.

The text items displayed in the "search as you type" field are the title elements of entries that match the string the user has typed. When the selects one of the options that are offered, a value is extracted from the corresponding Atom entry and stored as the collection field's value. The extracted value is taken from one of the Atom entry's sub elements, as specified by the field element's select attribute. This attribute can have one of the following values:

content

The field value is taken from the Atom entry's content element.

title

The field value is taken from the Atom entry's title element (that is, it will be the same value as is actually displayed in the field).

locator

The field value is taken from a proprietary viz:locator element in the Atom entry. (Not currently used.)

link

The field value is taken from one of the Atom entry's link elements. An additional linkrel attribute specifies which link attribute is to be used.

For a full description of the collection field element, see here.

The following example shows a collection field definition that allows the CUE user to select images from a Flickr public feed:

<field name="pwImage" 
  type="collection" 
  src="http://api.flickr.com/services/feeds/photos_public.gne?tags=creativecommons,norway" 
  select="link"
  linkrel="enclosure"
  mime-type="text/plain">
  <ui:label>Images of Norway</ui:label>
</field>

This is a simple test you can use to see how the field works. If you add a field like this to a content type and then try using it in CUE, you will see that image descriptions taken from the entry title elements are displayed under the input field like this:

If you select one of the displayed options, then a value is taken from the related Atom entry, and stored as the field's value. Exactly which entry element the value is copied from is determined by the field definition's select element. In this case it was set to "link", which means the value will be copied from one the Atom entry's link elements. Since an Atom entry can contain many link elements, an additional linkrel element is required to specify which link element to use: in this case, the one with a rel attribute set to "enclosure".

You can retrieve collection field values in your publication templates using JSTL as follows:

<img src="${article.fields.pwImage.value.value}"/>