Storing and Recalling Context Lists

A context list is a list of files or links. Such a list is normally created with an NPSOBJ-list instruction in which a field name such as children or toclist or the name of a linklist field is specified.

Such lists can be stored in export variables. This alone would not have any advantages over using a built-in context list like toclist in an NPSOBJ-list instruction. The context list stored in an export variable, however, can be extended, i. e. other context lists can be appended to it. Additionally, the list stored in the variable can be sorted or truncated. The code in the following example assumes that the current file is a folder containing subfolders. The subfiles of all subfolders are to be stored in the variable named mylist if their respective showInList custom field has the value YES :

<npsobj list="toclist">
  <npsobj condition="isEqual" name1="objType" value2="publication">
    <npsobj list="children">
      <npsobj condition="isEqual" name1="showInList" value2="YES">
        <npsobj modifyvar="append" varname="mylist" name="self" />
      </npsobj>
    </npsobj>
  </npsobj>
</npsobj>

In the inner list the modifyvar append instruction appends to mylist the file currently processed in the list. This file is referred to with self, yielding, like parent, previous and next, a context list with exactly one element. Instead of the inner list we could have used

<npsobj modifyvar="append" varname="mylist" name="children" />

if it had not been necessary to use a condition instruction in order to select the files by showInList.

The code also shows that a modifyvar-append instruction can even be used if the export variable does not yet exist. This means that it is not necessary to initialize variables.

An export variable can be assigned a context list using the following instruction:

<npsobj modifyvar="set" varname="mylist" name="toclist" />

Next to toclist, all names returning a single context or a context list can be specified. These are, among others: self, parent, children, the names of variables to which a context list has been assigned, and the names of linklist fields.

The context lists in export variables can be truncated by means of a modifyvar-range instruction. For example, the following code removes the first element (i. e. the first context) from the list mylist:

<npsobj modifyvar="range" varname="mylist" start="2" />

As with the NPSOBJ list instruction, you can combine start with either length or end to specify the desired part of the list. While length is used to indicate the number of desired elements, end lets you specify the index of the last element. The index of the first element is 1.

For sorting the context list stored in an export variable, the modifyvar-sort instruction is available. It is is described in section npsobj_modifyvar_sort.

You can use the variables in which you have stored context lists in NPSOBJ-list and NPSOBJ-table instructions in order to generate a link list, for example:

<npsobj list="export.mylist">
  <npsobj insertvalue="anchor" name="self">
    <npsobj insertvalue="var" name="title" /><br>
  </npsobj>
</npsobj>

Context lists are not restricted to file contexts but can also contain free links. Furthermore, file and link contexts can be mixed, if required. The code that processes such a mixed list, however, would have to test the type of each context. For this purpose one could, for example, read out in a switch instruction the value of a field (such as objType) which is never empty for files and always empty for links:

<npsobj list="export.mymixedlist">
  <npsobj switch="objType">
    <npsobj casecond="isEmpty">
      Must be link context
    </npsobj>
    <npsobj casecond="default">
      Must be file context
    </npsobj>
  </npsobj>
</npsobj>

From version 6.5.0, it is possible to access context lists containing exactly one context as if they were this context, i.e. it is no longer necessary to iterate over the list using npsobj list. Example:

<npsobj modifyvar="set" varname="savedContext" name="self" />
...
<npsobj condition="isNotEmpty" name="export.savedContext">
  <npsobj insertvalue="var" name="savedContext.path" />
</npsobj>