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, Content Studio 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 asearch
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, Content Studio 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 additionallinkrel
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 Content Studio 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
Content Studio,
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}"/>
Note the extra value
component in the above
example. This is always required when retrieving values from
collection fields.