npsobj insertvalue template

Syntax

npsobj_insertvalue_template ::=

  <npsobj insertvalue = "template"
    ( name = "name" ) | ( key = "key" ) 
    { other_attribute } >
    content
  </npsobj>

other_attribute ::= string = "string"

Task

The instruction replaces the element by an evaluated layout. If the name attribute is present, its value is used as the layout name, otherwise the layout name is looked up in the field named key in the current context.

The search for a layout file named as determined by the rules mentioned above starts in the current context. (When a file is exported, the current context initially corresponds to this file. However, in the course of the export, context changes may be caused by other export instructions.) If the current context is a folder, the search starts in this folder. Otherwise it starts in the folder containing the CMS file that provides the current context. If the current context is a link, the search starts at the file or folder containing the link.

If the layout file does not exist at the location determined as described above, the search will be continued further and further in the parent folders until the layout is found or the base folder is reached. If even the base folder does not contain the layout file, a corresponding error message is used as the result.

Up to version 6.7.0, additional attributes next to name and key as well as the content of this element are ignored.

Extensions from version 6.7.1

In addition to name and key, other attributes can be specified in the NPSOBJ tag for passing arguments to the layout file being included. The value of such an argument can only be text, not a context list. If desired, the value of an argument can also be computed using an @-reference.

The arguments are treated just like export variables are, however, they are only visible inside the layout which is called, meaning that they are local variables. To avoid name conflicts with global variables created using modifyvar set or modifyvar append, the names of the local variables should be unique. A local variable can be modified by means of modifyvar set or modifyvar append and deleted using modifyvar clear. If the local variable specified in one of these instructions does not exist, the instructions are applied to the global variable with the same name, if it exists.

In addition to the arguments, the content of the element is passed to the layout file being included using the npsobjContent variable. NPSOBJ instructions contained in the content are evaluated in the respective local context, i.e. when npsobjContent is read, not when the content is written to npsobjContent.

In the included layout file, the arguments and npsobjContent can be accessed like any other fields or export variables, for example by means of an insertvalue-var instruction.

Examples

The following code checks whether the file being exported or one of its parent folders contains the field listTemplateName. If so, the value of this field is interpreted as the name of a layout which is then used.

<npsobj condition="isNotEmpty" name="up.listTemplateName">
  <npsobj insertvalue="template" key="up.listTemplateName" />
</npsobj>

The following example demonstrates how an argument (as the showbody attribute) and a text (as the element body) can be passed to the included layout file which then outputs both. These techniques for passing values to layout files are available from version 6.7.1.

<!-- Instructions in the calling layout file -->
<npsobj insertvalue="template" name="TemplateName" showbody="1">
  <h1>Section Title</h1>
  <p><strong><npsobj insertvalue="var" name="title"/></strong></p>
</npsobj>

<!-- Contents of the TemplateName layout -->
<npsobj insertvalue="var" name="npsobjContent"/>
<npsobj condition="isEqual" name1="showbody" value2="1">
  <p><npsobj insertvalue="var" name="body"/></p>
</npsobj>

When the layout to be included is called, the following output is generated (the colors are just for the purpose of illustration):

  <h1>Section Title</h1>
  <p><strong>Title of the exported document</strong></p>
  <p>This is the body of the exported document.</p>