Select value fields

Select Values

Introduction to Select Values

There are input fields you can define different kinds of predefined selections for. These select values are stored in separate documents. The mode of operation of select values is as follows: Select value documents provide a mapping of internally saved keys ("Value") and associated labels ("Label") that are displayed to the user. Depending on whether or not such select values are required in the delivery the according document need to be published.

You can set default values that apply for the entire repository and you can define certain values that only account partly, i.e. for an individual site or structure node. Furthermore, you can determine the ordering in which the given values appear in the dropdown menus as well as the value that should be selected in advance.

To create a new list of select values,

1. Mark the left-hand menu item "SelectValues" within the administration view, open its context menu and select "New: SelectValue".
2. Specify the structure node and the ID stem to store the document at within to emerging dialog.
3. Click "Finish" and an empty select value document opens with three smaller sections to provide information:

• Base – Here you have to specify the name of the select value document. This will be the label that appears in the list of all select value documents within the administration view. The checkbox "Category SelectValue" determines whether this document should belong to the Enhanced Categories and thus might be visible (and editable) to non-administrative users (compare to section Enhanced Categories of the user guide).
• Icon – This will be the icon that represents the entire list of values (in contrast to the icons which might be assigned to individual values as explained below). If this select value document is marked as "Category SelectValue" (in the "Base" section above), this icon will be shown upon the enhanced categories toogle buttons within the search view when this category is picked by the user.
• Select Values – The are two possibilities to define the actual select values:
• Select the line "(Default values)" within the table and click the "New subvalue" button next to it in order to specify a globally valid select value or
• click "New node", select a certain structure node or site you want to define special values for and click the "New subvalue" button.

1. To define a standard value, that should be pre-selected in the drop-down menu, mark an entry and click the "Default" button.
2. To define an icon for a select value click the button in the corresponding table cell and upload an icon (valid file formats are JPEG, GIF, PNG or SVG) with a resolution of 24x24 px (except SVG files, which are automatically scaled to the appropriate resolution).
3. When you are finished, save the select value document.

The following screenshot presents five select values that apply for all websites and structure nodes and the default value is "Story". The structure node "/demosite/trendcities" has a different setting: Here, only two values are available and the default value is "File". Thus, when this select value is configured to an input field of a certain document type, the provided set of value is different within documents that are located at the structure node "/demosite/trendcities" and document that are located elsewhere.

Icons within Select Values

Each select value may be arranged with an individual icon. To define an icon for a select value click the button in the corresponding table cell and upload an icon (valid file formats are JPEG, GIF, PNG or SVG) with a resolution of 24x24 px (except SVG files, which are automatically scaled to the appropriate resolution). To delete or save an icon, mark the according select value and apply the desired button on the right side of the table. These actions are also available in the context menu of each select value.

Exemplary Usage of Select Value Icons with Components

In this example, a text alignment can be set for referenced stories. The alignment has to be set in the component details view and is shown as an icon upon the components tab of the document editor.

As a first step, create a select value called "Alignment" with the following values and icons: "left" [ICALIGNLEFT], "centered" [ICALIGNHORIZONTALCENTER], and "right" [ICALIGNRIGHT]. The created select value is shown in the following image:

Within the administration view, open the document type "sophora-content-nt:storyref". Insert the following text on the CND tab:

<'sophora-content-nt'='http://www.subshell.com/sophora-content-nt/1.0'>
<'sophora-content'='http://www.subshell.com/sophora-content/1.0'>
 
['sophora-content-nt:storyref'] > 'sophora-content-nt:refBase'
  orderable
  - 'sophora-content:alignment' (string)

Change to the properties tab of this node type configuration after saving the CND. There is now a new property called sophora-content:alignment in the section Display tab: system. Move the property to the section Display tab: base and edit its properties. Select "Selection value (list)" as the InputFieldType, choose "SelectValue document" as SelectValue provider and select Alignment from the List of SelectValue documents

The configured property is shown in the following image:

Switch to the Attributes tab and add the sophora-content:alignment property to the selected Search result properties.
The configuration of the sophora-content-nt:storyref document type is now finished. Save and close the document.
To use the alignment property within a document reference, execute the following steps:

1. Create a new story (or open an existing story document).
2. In the Component structure, add a new Teaserlist group.
3. Add two stories to the Teaserlist group
4. Select the first story in the Component structure.
5. In the Component details view, check the Alignment box and set the alignment to "Left".
6. Select the second story in the Component structure.
7. In the Component details view, check the Alignment box and set the alignment to "Right".
8. Finally, go to the Components tab of the opened document. It shows the two referenced stories with icons for their selected alignment.

The following picture shows the final story document:

Examples How to Use Select Value Icons Within Component Groups

Additionally to the aforementionend Components, Component Groups can also be configured to display Select Value Icons.
Select Value Icons of Component Groups are visible on the Components Tab and on Paragraph Boxes within the Copytext Editor.

In order to shorten this example we will use the "Alignment" Select Value from the first example.

Since we already got a Select Value, we can start right away with adding the new property to the nodetype of the Component Group.

Within the administration view, open the document type "sophora-content-nt:storylist". (If the document type does not exist, you may create it yourself. The only precondition is the nodetype must extend 'sophora-extension-nt:group'.) Insert the following text on the CND tab:

<'sophora-content-nt'='http://www.subshell.com/sophora-content-nt/1.0'>
<'sophora-extension-nt'='http://www.subshell.com/sophora-extension-nt/1.0'>
<'sophora-content'='http://www.subshell.com/sophora-content/1.0'>
 
['sophora-content-nt:storylist'] > 'sophora-extension-nt:group'
  orderable
  - 'sophora-content:alignment' (string)

After saving the CND, change to the properties tab of the node type configuration and move the property sophora-content:alignment from Display tab: system to Display tab: base. Now double click the entry to edit its configuration. Select "Selection value (list)" as the InputFieldType, choose "SelectValue document" as SelectValue provider and select the Alignment select value (created in the first example) from the List of SelectValue documents.

Now switch to the Attributes tab and add the sophora-content:alignment property to the selected Search result properties.

The configuration of the sophora-content-nt:storylist document type is now finished. Save and close the document.

Displaying a Select Value Icon on a Component Group in the Components Tab

Precondition: Open the document type sophora-content-nt:story and make sure your node type is configured as a valid child node type to the child node sophora-content:box.

To use the alignment property within a group in the Components Tab, execute the following steps:

1. Create a new story (or open an existing story document).
2. In the Component structure, add a new "Box: Teaser" group. ("Box" is the label of the child node and "Teaser" is the label of the Component Group node type.).
3. Add one or more documents to the group.
4. In the Component structure, select the group "Box: Teaser". The Alignment property should now be visible in the Component details view.
5. In the Component details view, set Alignment to "Left".
6. Finally, go to the Components tab of the opened document. The selected alignment icon should be visible in the title bar of the group.

The following picture shows the final story document:

Displaying a Select Value Icon on a Paragraph Box in the Copytext

Open the document type sophora-extension-nt:paragraph and make sure your node type is configured as a valid child node type to the child node sophora-extension:paragraphbox.

1. Create a new story (or open an existing story document).
2. Right-click on the Copytext and select New group > Paragraphbox > Teaser.
3. Select the newly created group by clicking its title. The Alignment property should now be visible on the Component details view.
4. In the Component details view, set Alignment to "Left".
5. The selected alignment icon should now appear in the title bar of the group.

The following picture shows the final story document:

Using Document References

Each value of the select values may have a reference to another document. You can enter a documents' external Id or Sophora-Id in the Referenced Document field. Alternative you can drop a Sophora document into that field, e.g. from Search. It is possible to drop a document into the select values table to create a new value, too. In that case, the value and label field are filled with the document reference label of that document automatically. In each case, the external Id of the document is stored as reference value. To open the referenced document either click on the underlined label of the select value field, double click on the entry in the table or use the context menu.

Usage of Enhanced Categories

Enhanced categories are modelled as select values so that some benefits are built in by default. First off all, you can create custom category trees by adding or extending as many according select value documents as you wish. Secondly, you can define different categories for individual sites or structure nodes so that they are available globally or locally as explained in the following subsection.

Note that only Sophora administrators can initially create a new enhanced category since you need to create a new select value document (where the checkbox "Category SelectValue" has to be selected). As soon as such an enhanced category document is saved the first time, it will be visible within the "Enhanced Categories" view und thus any user with according permissions (dependent on where this document is located) may edit this enhanced category. Therefore the user guide also contains a section about enhanced categories which might be interesting for you to read as well.

To enable the assignment of enhanced categories to documents, you have to configure a select value input Field for each individual category.

Enhanced Categories Across Several Site or Structure Nodes

As with conventional select values, you can mark a certain entry as default and change the ordering by clicking the corresponding buttons when the desired entry is selected.

If you wish to differentiate your categories between individual sites in your repository, execute the following steps:

1. Click the button "New node" next to the table in section "Select values" of the editor.
2. Select the site you want to define custom categories for.
3. Next, click on the "New subvalue" button besides the table.
4. Provide a value or let it be generated automatically and a label in the pop-up dialog (this label is what will be displayed later). You can even provide an icon here, if you want to.
5. Click "Ok" or "Add Another Value" to continue.
6. Finally save the document and all values subordinate to the inserted site will only be available in documents that belong to this particular site.

If you wish to share some categories across sites, thus use them globally, execute the following steps:

1. Mark the entry "(Default values)" in the table in section "Select values" of the editor.
2. Next, click on the "New subvalue" button besides the table.
3. Provide a value or let it be generated automatically and a label in the pop-up dialog (this label is what will be displayed later). You can even provide an icon here, if you want to.
4. Click "Ok" or "Add Another Value" to continue.
5. Finally save the document and all values subordinate to "(Default values)" will be available throughout your repository.

Note that the steps as illustrated above account for structure nodes as well.

Using Query Select Values as an Enhanced Category

Query select values may also be used for an enhanced category. Since query select values are not configured with a corresponding select value document, such an enhanced category has to be configured in its property configuration. Please refer the documentation of the corresponding input field types for further information.

Exporting Select Values

To export a select value document,

1. Expand the left-hand menu item "SelectValues" within the administration view.
2. Mark the select value documents you want to export, open the context menu and select "Export...". You can select multiple documents at once by pressing the CRTL key and clicking the individual documents.
3. In the emerging dialog, you have to specifiy, amongst other things, the Sophora XML version as well as the target directory.
4. Click "Finish" to start the export procedure.

To export all select value documents at once,

1. Mark the left-hand menu item "SelectValues" within the administration view, open the context menu and select "Export...".
2. In the emerging dialog, you have to specifiy, amongst other things, the Sophora XML version as well as the target directory.
3. Click "Finish" to start the export procedure.

Select value documents are exported according to the Sophora XML Schema and can be imported againg using the Sophora Importer.

Selection Values

There are four different ways 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 a manually added value is also allowed. Therefore, 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.

Selection Value (sortable, multi)

A property of this type may contain a value from a predefined list, but a manually added value is also allowed (if the field is not configured otherwise). Therefore, 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.

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 or SoQL 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.

It is important to note that only Query Select Values can be configured with reference properties.

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 a list of authors 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 the input field type, you should select Selection Value (List) or Selection Value (intelligent). Finally, 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 (SoQL)

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

The string <SoQL query> needs to be a valid SoQL expression, like this one from our example:
primaryType = 'sophora-demo-nt:person'

The syntax to integrate a property into the label should follow the pattern ${@<propertyName>}. Based on 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})

As a result, a complete example for an entry in the property configuration's SelectValue field, if Document Query is selected as SelectValue Provider, would be:
soql="primaryType = 'sophora-demo-nt:person'":label="${@sophora-content:lastname}, ${@sophora-content:firstname} (${@sophora-content:city})"

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

Query Syntax (XPath)

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

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')]

The syntax to integrate a property into the label should follow the pattern ${@<propertyName>}. Based on 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})

As a result, 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})"

Caching of Query Select Values

Since the query might return a lot of documents, the results are cached. Some changes (like changing, adding or deleting documents of a node type that is used in the query) will invalidate the cache immediately. However, not all changes relevant for a Query Select Value can automatically be detected. Thus, all Query Select Values are refreshed regularly. You can set the update interval within the server configuration using the parameter sophora.cache.selectValues.refreshInterval.
Note that you have to reopen a document in the DeskClient for a Select Value change to become effective in that document editor.

Using Query Select Values as an Enhanced Category

You can use a query select value as an enhanced category. To do so, 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.

soql="primaryType = 'sophora-demo-nt:person'":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. Each of the individual XML elements must contain the two attributes: id and name. "id" refers to the value of the property, while "name" is what will be displayed in the document editor.

<?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 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:

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.