Picking elements from an array is a powerful method to set up alternation (e.g., in colors) as the program iterates through a loop.

The <#pick ...#> construct allows the extraction of certain elements from an array, in a repeating pattern as defined by the template designer. You have control over what element you extract and in what order the elements will be returned. The general format of the <#pick ...#> construct is as follows:

<#pick component number from @arrayname(sequence)#>

component is the name of the component of the element you wish to extract (see the page on defining arrays for details on component names). component is always alphanumeric.

number is the number that describes which element to extract, when related to the values in the sequence. More on this later.

arrayname is the name of the array containing the elements you want to extract. This can be either an array that you defined yourself, an array defined by the particular section of the Discus code you are executing, or a special array such as @_ALTCOLOR.

sequence is a comma-separated list of numbers that tell the program the order in which elements are extracted from the array. More on this follows in the next section.

The sequence allows the template designer to specify the order in which elements are extracted from the array.

The sequence is defined as a list of comma-separated numbers, where each number corresponds to an element of the array. For example, the sequence 7,8 tells the program to use the 7th element the first time and the 8th element the second time. The third time, the program will have reached the end, so it will start over at the beginning. So, the third time you will get the 7th element, and the fourth time you will get the 8th element. And so on.

The sequence 7,8,9 is also a valid sequence. The first time, you will get the 7th element. The second time, you will get the 8th element. The third time, you will also get the 9th element. The fourth time, you are back to the 7th element, and so on.

You are also free to repeat numbers when constructing a sequence. For example, if you were to use 7,7,8,8, the first and second times you would get the 7th element, the third and fourth times you would get the 8th element, the fifth and sixth times you would get the 7th element again, and so on.

For clarity, consider the above sequence examples into color terms. The 7,8 sequence might give you WHITE - RED - WHITE - RED - WHITE - RED - WHITE - ... The 7,8,9 sequence might give you WHITE - RED - BLUE - WHITE - RED - BLUE - WHITE - ... And the 7,7,8,8 sequence might give you WHITE - WHITE - RED - RED - WHITE - WHITE - RED - RED - WHITE...

There is one special sequence you can use. If you use "*" rather than a sequence, you will iterate among all elements of the array. (This prevents you from having to type out a long list of sequential numbers if you have a big array.)

Consider the array @_ALTCOLOR, which contains the ten alternating colors as elements in slots 1 through 10. Each element has the component 'color' which is the hex code for each alternating color. If you aren't familiar with @_ALTCOLOR, read the documentation on it.

<#foreach $message (@messages)#>
  <tr bgcolor="<#pick color $message->{_iteration} from @_ALTCOLOR(7,8)#>">
  ... other code here...
  </tr>
<#endloop#>

The above example would, on a Discus message page, iterate through the list of messages, displaying the first message in a table row whose background color is the 7th alternating color, the second message with the 8th alternating color, the third message with the 7th alternating color again, and so on.

If you are mathematically inclined, you may have figured out that the <#pick ...#> operation takes the modulus of your supplied number with the number of elements in your sequence and returns that element of the array. If you don't know what this means, don't worry about it.

It is possible to extract a certain component of an element in an array where another component equals some value you specify. The syntax of this is:

$@arrayname->{extract:compare="compare_value"}

The above code checks through @arrayname and returns the extract component of the first element of the array where the compare component equals compare_value. The following code is a less efficient way of writing the same thing:

<#foreach $element (@arrayname)#>
  <#if $element->{compare} eq "compare_value"#>
    $element->{extract}
    <#last#>
  <#endif#>
<#endloop#>

Besides the fact that the first example requires much less text, it can also be used within a comparison within an IF-THEN-ELSE statement or within a definition. This command is used in the tables2 skin to define the URL to the icon based on the name of the icon supplied:

<#define $icon = "$@subtopic_icons->{url:name="$subtopic->{property_emot}"}"#>