api:enum
The api:enum keyword can be used to enumerate over the attributes within an item, a delimited list, a supplied range of values, and the values of a multivalued attribute. The body of api:enum is executed for each element of the set that is being iterated upon.
Parameters
- item: The name of the item whose attributes you want to iterate over.
- attr: The expression to match that specifies which attributes are iterated over. For example, "api:*". You can also provide this parameter to iterate over the values of a multivalued attribute.
- prefix: The prefix based on which the item is enumerated.
- expand: The boolean value that specifies how api:enum behaves when multivalued attributes are encountered. If expand is set to true, the body of api:enum will be executed once for each value of the attribute. If false, all values will be concatenated in a single string value, and only a single iteration will be performed. By default, api:enum will not expand all values.
- sep[arator]: The separator to be used to concatenate values of a multivalued attribute if the expand parameter is false. Additionally, separator is used to tokenize the values in a list if listseparator is not defined. The default value is the new-line character "\n".
- list: The list of separated values to enumerate over. For example, if the list of values is "violet, indigo, blue, green, yellow, orange, red" and the separator is a ',' the scope of api:enum is executed for each color in the rainbow.
- range: The range of numbers or characters to enumerate over in ascending or descending order; for example, "a..z", "Z..A".
- recurse: Whether to enumerate over nested attributes. The default is true.
Control Attributes
- _attr: The name of the attribute being iterated over. When you are iterating over the values of a multivalued attribute, the attribute name will be the same except that it will also have the index as part of the name. The index is separated from the name by the hash symbol (#). For example, name#1, name#2, etc.
- _index: The index at which the attribute appears within an item or the position of the list element currently being enumerated over.
- _value: The value of the attribute being iterated over. For a multivalued attribute, the expand and separator parameter settings determine whether _value is a reference to one attribute value or a reference to all attribute values.
- _count: The number of values in an attribute or in a list.
- _separator: The separator used to separate the values in a list.
Examples
Display the attribute names and attribute values of the item named "input":
<api:set item="input" attr="Greeting" value="Hello" />
<api:set item="input" attr="Goodbye" value="See ya" />
<api:enum item="input">
[_attr] is [_value]
<br/>
</api:enum>
goodbye is See ya greeting is Hello
To enumerate over a list of values use the list and separator parameters of api:enum. For example, the code below lists the colors specified in the colors attribute:
<api:set attr="colors" value="violet, indigo, blue, green, yellow, orange, red"/>
<api:enum list="[colors]" separator=",">
[_value]
</api:enum>
To enumerate over a range of values, use the range attribute. For example, the code below lists the character set from a to z, from Z to A, and the numbers from 1 to 25:
<api:enum range="a..z">
[_value]
</api:enum>
<api:enum range="Z..A">
[_value]
</api:enum>
<api:enum range="1..25">
[_value]
</api:enum>
To enumerate over all the values of a multivalued attribute, use the attr argument to specify a multivalued attribute and set expand to true:
<api:set attr="foo.email#1" value="[email protected]"/>
<api:set attr="foo.email#2" value="[email protected]"/>
<api:enum attr="foo.email" expand="true">
([_index]) [_attr] -> [_value]
</api:enum>
The example above results in the following output:
(1) email#1 -> [email protected] (2) email#2 -> [email protected]