Selection Values

There are four different options to configure an input field, where the user can choose one or more out of a predefined set of documents, properties or the like - intelligent, list, editable list and tree selection values. Except for the tree selection value field, you have to choose a SelectValue provider and then a SelectValue. There are two different kinds of SelectValue providers available:

The SelectValue Document requires a reference to a select value document as Select Value and a property of type string. This document can be chosen from a list of all available SelectValue documents. While the selected value will be saved internally, the editor will always display its label if available.
The Document Query offers the SelectValues based on an XPath query. You will find more information about that below.

Selection Value (List)

If a select value is configured as Select Value (List), the field's content in the document has to be selected from a predefined list of values (a drop-down menu). Only the internal key of the selection is saved.

Selection Value (List, Editable) / Selection Value (List, Editable, Multi)

A property of this type may contain a value from a predefined list, but also a manually added value is allowed. Thus, the value that is saved for this property is either the key of the selected one, or the property that has been entered by the user.

This input field type is available for both single and multiple properties.

Select Value Filled with Document Queries

For list and intelligent select values, it is possible to configure the selectable values with content from documents based on XPath queries. This content will be collected according to a previously specified query. In addition, you may also define the appearance of the query results (the values) within the drop-down menu, respectively the pop-up window for intelligent select values.

An example:

In documents of the type Story (sophora-content-nt:story) it should be possible to select the author. Information about individual authors is stored in individual documents of the type Person (sophora-content-nt:person). The CND of the Person document looks like this:

<'sophora-content-nt'='http://www.subshell.com/sophora-content-nt/1.0'>
<'sophora-content'='http://www.subshell.com/sophora-content/1.0'>
<'nt'='http://www.jcp.org/jcr/nt/1.0'>
 
['sophora-content-nt:person']
orderable
- 'sophora-content:firstname' (string)
- 'sophora-content:lastname' (string)
- 'sophora-content:city' (string)

To provide an author list within stories, the first step is to add a new string property (e.g. sophora-content:author) to the CND of the document type Story. A basic version of the Story-CND is shown here:

<'sophora-content-nt'='http://www.subshell.com/sophora-content-nt/1.0'>
<'sophora-content'='http://www.subshell.com/sophora-content/1.0'>
<'nt'='http://www.jcp.org/jcr/nt/1.0'>
 
['sophora-content-nt:story'] > 'sophora-content-nt:objectBase'
orderable
- 'sophora-content:author' (string) 
+ 'sophora-content:copytext' ('sophora-extension-nt:copytext')
+ 'sophora-content:box' (nt:base) multiple

Next, you have to configure the property sophora-content:author in the property configuration of the document type sophora-content-nt:story. As input field type, you should select Selection Value (List) or Selection Value (intelligent). Ensuing, you have to choose Document Query as Select Value Provider.

In the field select value, you then have to define the actual query and the formatting of the label which will be used for displaying the selectable entries in the editor.

Query Syntax

In order to find the desired documents, each query must match the syntax query="<XPath query>":label="<label>".

Therefor, the string <XPath query> needs to be a valid XPath expression like this one from our example:
element(*, sophora-content-nt:person)[not(@sophora:isDeleted='true')]

Meanwhile, the syntax to integrate a property into the label shall follow the pattern ${@<propertyName>}. Ensuing from this syntax, you can design a term to replace <label> with. In our example, we would use:
${@sophora-content:lastname}, ${@sophora-content:firstname} (${@sophora-content:city})

Hence, a complete example for an entry in the property configuration's SelectValue field, if Document Query is selected as SelectValue Provider, would be:
query="element(*, sophora-content-nt:person)[not(@sophora:isDeleted='true')]":label="${@sophora-content:lastname}, ${@sophora-content:firstname} (${@sophora-content:city})"

This example would result in the formatting that is shown in the following illustration:

Since the XPath query might return plenty of documents, the results are cached.You can set the update interval within the server configuration using the parameter sophora.cache.selectValues.refreshInterval. Thus, the following changes will apply after reopening the document only if the time interval elapsed:

• Adding/creating documents that match the query
• Deleting documents that match the query and thus are already contained in the cache
• Changing the content of documents that match the query, i.e. properties that are used either within the query or within the label

Using Query Select Values as an Enhanced Category

You can use a query select value as an enhanced category. For this purpose, you need to specify a name for the category as an additional parameter of the select value configuration. The name of this category must be unique.

query="element(*, sophora-content-nt:person)[not(@sophora:isDeleted='true')]":label="${@sophora-content:lastname}, ${@sophora-content:firstname} (${@sophora-content:city})":categoryName="Person"

Selection Value (Tree)

This input field type embodies values from a XML tree structure. Hence, each of the individual XML elements must contain the two attributes id and name. The value that is actually saved for this property is the ID of the selection, while the value of the attribute "name" is displayed in the document editor. The XML which should be used by the selection tree may be located in any document type and any string property.

In contrast to other select value input field types, the tree select value does not require you to further specify an expression within the SelectValue field. All information should be defined in the XML property which you refer to in the property configuration using the parameters from above. In the following example, the property sophora-content:xml of the document xml100 contains the required XML data:

<?xml version="1.0" encoding="UTF-8" ?>
<list>
	<node id="id1" name="Value 1">
		<subnode id="id11" name="Value 11" />
		<subnode id="id12" name="Value 12" />
		<subnode id="id13" name="Value 13" />
	</node>
	<node id="id2" name="Value 2">
		<subnode id="id21" name="Value 21" />
		<subnode id="id22" name="Value 22" />
	</node>
	<node id="id3" name="Value 3">
		<subnode id="id31" name="Value 31" />
		<subnode id="id32" name="Value 32" />
	</node>
</list>

The following illustrations show the resulting input field for a single...

... and a multiple string property.

Select Value (Intelligent)

An intelligent select value creates an appropriate editor (either dropdown menu or tree), depending on both the property type (multiple/not multiple) and the structure given in the actual select value document:

• For a single property and a flat list selection value, a dropdown menu is generated.
• For a multiple property or a tree-like selection value, a text field with a selection-dialog is used. Select values may be selected either using the dialog or by being entered directly into the text field. Content assistance will be provided if you are typing in the text field or pressing Ctrl+Space.

Dependent Select Values

You can use intelligent selection value fields to configure dependent select values. A dependent select value uses a hierarchical select value (at least some values have subvalues) where each level of the tree logically defines a new select value. You can configure multiple single-value input fields to use the exact same select value document. Then, you assign a tree level to each input field, thus they all display just a flat list. Now, if an element is selected, the input field covering the next tree level will be updated with the subvalues of the selection.

Example: You want to store a location partitioned in its three different characteristics continent, country and city. The document type which shall contain the location has been already assigned the single-value properties sophora-example:continent, sophora-example:country and sophora-example:city. A corresponding select value document may look like the following:

To configure three input fields, where the choice of cities depends on the selected country, and the choice of countries depends on the selected continent, proceed as follows: First, configure all three properties with the input field type Selection Value (Intelligent), with the Select Value Provider set to Select Value Document and choose the desired select value document from the list. With this configuration, all three fields will use a tree to select one out of all the document's values.

To determine the dependency, you have to set the parameter Tree Level for each of the three properties: Level 1 for the continents, 2 for the countries, and 3 for the cities. Now, each field displays just the values of that tree level in a flat list. Furthermore, if the selection within the field Continent is changed, the possible values of the field Country will change to only those countries which are defined for the selected continent.