npsobj list

Syntax

npsobj_list ::=

  <npsobj list = "name"
    [ sortkey1 = "sortKey1" 
      [ sortmodifier1 = sortModifier ]
      [ sortkey2 = "sortKey2"
        [ sortmodifier2 = sortModifier ]
        [ sortkey3 = "sortKey3"
          [ sortmodifier3 =  sortModifier ]]]]
    [ start = "startIndex" ]
    [ ( length = "length" ) | ( end = "end" ) ] 
    [ reverse = "" ] >
    content
  </npsobj>

sortModifier ::=
  "alpha" | 
  "numeric" | 
  "ascending" | 
  "descending" |
  "alpha ascending" | 
  "alpha descending" |
  "numeric ascending" | 
  "numeric descending"

Task

The instruction is frequently used to automatically generate tables of contents. It creates a list of file or link contexts by evaluating name. name stands for an identifier that yields a context list, for example toclist or children. Also, the name of a linklist field or an export variable to which a context list has been assigned can be specified.

For each list element, content is evaluated once (however, see npsobj_break). For the evaluation of content, the current context is temporarily set to the respective list element. Therefore, all names (such as field names) refer to the current list element as long as the context in the content part is not changed.

Sorting elements

The context list can be sorted by comparing the values of sortKey1 in the contexts. If two values are equal, the values of sortKey2 are compared. If these values are equal as well, the order of the contexts is determined using sortKey3. If the contexts remain unsorted because the values of every sortkey are identical in all contexts then the final order of the contexts is undefined. If sortkey1 has not been specified, the context list will be sorted by the sortkeys that have been specified for the folder containing the respective files.

Using the sortModifier modifier, it is possible to specify how the values of two sortkeys are to be compared with each other. alpha sorts by character value, numeric numerically, i. e. the character sequence is interpreted as a number. ascending sorts in ascending, descending in descending order. One of the two keywords of each modifier pair (alpha/numeric and ascending/descending) can be combined with each other (e.g. numeric descending). The default sort mode is alpha and the default sort direction is ascending. Thus, the default modifier combination is alpha ascending.

Selecting elements

If the attribute start is specified and if startIndex has a value greater than 0, then startIndex is the index of the first element of the context list to be considered. The first element has the index 1. If startIndex has a value less than 0, then the first element to be considered will be determined from the end of the context list. If startIndex equals 0, then the attribute will be ignored.

The attribute length allows you to specify the number of elements in the context list. If length equals 0 (default) then the elements beginning at start up to the end of the list will be returned. A value greater than 0, on the other hand, determines the maximum number of elements to be returned, beginning at start. If length is less than 0, then start specifies the last element in the list whose maximum number of elements is determined by the absolute value of length. For example, start="-1" and length="-2" returns the second last and the last element of the list.

As an alternative to length, the end attribute can be specified. If end is a positive number, then this number specifies the index of the last element in the original list to be considered. The first element has the index 1. If end is a negative value, then the absolute value of end specifies the number of elements to be removed from the end of the list.

The effect of start and length or end, respectively, is shown in the following overview. The element selected with start is colored green.

Selected elements	start	length	end
	3	2
	5	-2
	-3	2
	-1	-3
	3		5
	2		-2
	-3		5
	-4		-1

Legend: Not selected element   First selected element   Other selected element

If the reverse attribute has been specified, the order of the elements is reversed. This is done after the elements have been sorted and before they are truncated using start and length or end, respectively.

Example

<npsobj list="toclist" start="2" length="3" sortkey1="title" sortmodifier1="ascending">
  <!-- This is processed for each element of the list -->
  <npsobj insertvalue="anchor" name="self">
    <npsobj insertvalue="var" name="title" /><br />
  </npsobj>
</npsobj>