npsobj_modifyvar_set ::= ( <npsobj modifyvar = "set" varname = "name" name = "varValueKey" [ local = "( true | false )" ] /> ) | ( <npsobj modifyvar = "set" varname = "name" [ local = "( true | false )" ]>varValue</npsobj> )
During the export of a file, export variables can be used to store character strings or context lists under a name. The values can be accessed by referencing the names in the same manner as other names that are valid during the export process.
If the attribute local
, which is available from version 6.7.1, is specified with true
as its value, the new export variables are only visible in exactly the layout file in which they were created. In this case, their scope is restricted to the current layout, meaning that the variables are neither available in the calling layout nor in sublayouts. Please note that from version 6.7.1, variables can also be passed as arguments to layouts that are included by means of insertvalue
-template
instructions.
Up to version 6.7.0, or if local="true"
has not been specified, the export variables are globally available from the moment they are created until the export of the respective file finishes (unless the variable is deleted in the meantime using a modifyvar
-clear
instruction). This means that you can access a variable even after context switches, e.g. in an NPSOBJ-list
or NPSOBJ-context
instruction.
The names of export variables have precedence over other names such as field names. If, for example, an export variable named author
is created and subsequently assigned the string John Smith
via the instruction
<npsobj modifyvar="set" varname="author">John Smith</npsobj>
then <npsobj insertvalue="var" name="author" />
will always return John Smith
, even if the currently exported file also has a field named author
to which a different value has been assigned. It is possible, however, to use the self
prefix in order to explicitly refer to the value of a field. Analogously, the export
prefix can be used to explicitly include the value of an export variable.
The modifyvar-set
instruction is available in the two variants shown above.
Variant 1: Value assignment by means of a tag attribute
In the first version, the variable is assigned the value of the field or export variable named
varValueKey
. varValueKey
can (like parent.title
, for example) yield a string or a
list of link or file contexts. The names yielding file or link contexts
are listed in the sections
Available Names in
a Context of Type file und
Available Names in
a Context of Type link. The following instruction assigns the list
of the current file’s sibling files (including itself) to the variable
named siblings
:
<npsobj modifyvar="set" varname="siblings" name="parent.children" />
Using the modifyvar-append
instruction, you can append
further context lists to export variables containing link or file
context lists (see
npsobj_modifyvar_append).
Furthermore, the contexts in export variables can be sorted (see
npsobj_modifyvar_sort).
Variant 2: Value assignment by means of the element body
The second variant of the modifyvar-set
instruction can
be used to assign a character string to an export variable. NPSOBJ
elements in this string are evaluated. Thus, layouts in which the same
code is to be used several times can be written more efficiently.
Please note that using the modifyvar-set
instruction in
this way creates a new context. This context corresponds to its
predecessor context. If you need to address a context above the current
context, you therefore require an additional context
prefix as shown
in the following example:
<npsobj list="relatedLinks"> <npsobj modifyvar="set" varname="theLinkListCode"><p> <npsobj list="context.context.linkImage"> <npsobj insertvalue="image" name="destination" /> </npsobj> <npsobj insertvalue="anchor" name="self"> <npsobj insertvalue="var" name="destination.title"/> </npsobj></p> </npsobj> </npsobj>
You can also query the source
link property to determine the CMS file that contains the link.
The following code stores a link pointing to the parent file in a variable and then exports it.
<npsobj modifyvar="set" varname="uplink"> <npsobj insertvalue="anchor" name="parent"> <npsobj insertvalue="var" name="parent.title" /> </npsobj> </npsobj> <npsobj insertvalue="var" name="uplink" />