Search

api:enum

Version 23.0.9145

api:enum

Use the api:enum keyword to enumerate over the attributes in an item, a delimited list, a supplied range of values, and the values of a multi-valued attribute. The body of api:enum is executed for each element of the set that is being iterated on.

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 multi-valued attribute.
  • prefix: The prefix based on which the item is enumerated.
  • expand: The boolean value that specifies how api:enum behaves when multi-valued attributes are encountered. If set to true, the body of api:enum executes once for each value of the attribute. If false, all values are concatenated in a single string value, and only a single iteration is performed. By default, api:enum does not expand all values.
  • sep[arator]: The separator to use to concatenate values of a multi-valued attribute if the expand parameter is false. separator is also used to tokenize the values in a list if listseparator is not defined. The default 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 comma (,), 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 or Z..A.
  • recurse: Whether to enumerate over nested attributes. The default is true.

Notes:

  • You can specify either the range attribute or the item attribute, but not both.
  • Attributes are enumerated in alphabetical order.

Control Attributes

  • _attr: The name of the attribute being iterated over. When you iterate over the values of a multi-valued attribute, the attribute name is the same except that it also has the index as part of the name. The index is separated from the name by a hash symbol (#). For example, name#1, name#2, and so on.
  • _index: The index at which the attribute appears in an item, or the position of the list element currently being enumerated over.
  • _value: The value of the attribute being iterated over. For a multi-valued attribute, the expand and separator 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 api:enum parameters. For example, this code 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, this code 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 values of a multi-valued attribute, use the attr argument to specify a multi-valued 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 previous example results in this output:

(1) email#1 -> [email protected] (2) email#2 -> [email protected]

See Also

  • api:break: Break out of api:call or api:enum iterations.
  • api:continue: Skip an api:call or api:enum iteration.
  • api:first: Provide special processing in the first iteration.
  • api:last: Provide special processing in the last iteration.