› KCM Template Scripting Developer's Guide › Keywords › Control Structures › FOREACH › FOREACH WIZARD/NODE

FOREACH WIZARD/NODE

The statements FOREACH WIZARD and FOREACH NODE enumerate selected Sections and Text Blocks in a Content Wizard.

The following is a definition of the statement. 

FOREACH WIZARD Element IN WIZARD id
DO
  <Template scripting part with declarations>
OD

The statement FOREACH WIZARD Element IN WIZARD id enumerates the top level Sections and Text Blocks the end-user selected in the last presented Content Wizard window with the label id. If no such Content Wizard was presented to the end user, a fatal error is reported. 

FOREACH WIZARD SubElement IN Element
DO
    <Template scripting part with declarations>
OD

The statement FOREACH WIZARD SubElement IN Element enumerates all Subsections and Text Blocks the end-user selected in the Element. You can use this statement only in the part DO … OD of another FOREACH WIZARD statement, and the Element must be the loop variable of such a statement. 

FOREACH NODE Element IN WIZARD id
DO
  <Template scripting part with declarations>
OD

The statement FOREACH NODE resources through the Content Wizard and performs the same functionality as a nested set of FOREACH WIZARD loops.

FOREACH NODE and FOREACH WIZARD loops can be nested but such nesting starts a new enumeration from the start of the Content Wizard.

The loop variables Element and SubElement are automatically declared and available in the loop DO … OD. You can choose the names but they must match the rules for valid FIELDSET names. These loop variables behave for all intents and purposes as read-only FIELDSET variables. You can copy Element and SubElement to regular FIELDSET variables.

The following fields are defined.

Type. The Type field indicates the object type of the current element. This field can have the following values:

  • "section". The object is a Section.
  • "textblock". The object is a Text Block or a Text Blocks List.
  • "group". The object is a Group.
  • "list". The objects is a Data Definition group representing a DATASTRUCTURE, an ARRAY of DATASTRUCTUREs, or an ARRAY of FIELDSETs.
  • "item". The object is an iteration in the Data Definition group. These objects only occur in "list" elements. Elements hidden by conditions in the Content Wizard are represented by an empty "item" element.

Name. If the current element is a Text Block, the Name field contains the name and the path to the Text Block as specified in the Content Wizard. If the element allows multiple selections, this field contains a comma-separated list (CSV format) of Text Blocks. For other elements this field contains the name of the element as shown in the Content Wizard.

TextBlock. The TextBlock field contains the name and the path to the Text Block containing the effective content of the element. If the element allows multiple selections, this field contains a comma-separated list (CSV) of Text Blocks. If the element is editable, this field contains a reference to the edited Text Blocks. The content of this field can be passed directly to the statement TEXTBLOCK to produce the content of the Text Blocks. This field is empty if the current element is not a Text Block.

MinElements and MaxElements. These fields contain respectively minimum and maximum elements that can be chosen in the group. If MaxElements contains 0, the maximum number of elements is unlimited. These fields are empty if the current element is not a group.

Wizard. This field contains the name of the Content Wizard.

QForm. This field contains the name of the QForm that was defined in the Section or subsection. This field is empty if the current element is not a Section.

WizardQForm. This field contains the name of the QForm that was defined at the top level of the Content Wizard. This field is empty except for top-level Sections and groups.

Editable. This field contains Y if the Text Block could be edited during a Content Wizard run. It contains N if the Editable option was not selected for the Text Block in the Content Wizard Editor.

Count.This field contains the total number of elements in a Data Definition group. This field is present in both "list" and "item" elements.

Current. This field contains the sequence number of the current iteration in a Data Definition group. This field is present in "item" elements.

Member. This field contains the DATASTRUCTURE member over which the Data Definition group is enumerating. This field is present in "list" elements.

Path. Internal path in the Data Definition that indicates which FIELDSETs in the Data Definition are currently visible. This value can be passed to the TEXTBLOCK statement to apply the correct data to the Fields in the Text Blocks and associated QForm.

The content of the Path field is intended for internal use only and remains valid only until the next time a Content Wizard with the same ID is presented or the Master Template ends. Its value can be copied to variables but cannot be stored externally. Any changes or manipulations are rejected.

Level. This field contains the nesting level of the element in the Content Wizard.

The content of this field is of type TEXT. Relative comparisons should use text_to_number() to convert the value to a NUMBER first. For more information on the text_to_number() function, see text_to_number.

Example 

# BEGIN
WIZARD "myID"
NAME "my wizard"

FOREACH WIZARD Element IN WIZARD "myID"
DO
  IF Element.Type = "section" THEN

#
Wizard @(Element.Wizard) [@(Element.WizardQForm)]
Section @(Element.Name) [@(Element.QForm)] at level: @(Element.Level)
#
  ELIF Element.Type = "textblock" THEN
    TEXTBLOCK VAR Element.TextBlock
  FI
  
    FOREACH WIZARD SubElement IN Element
    DO
      IF SubElement.Type = "section" THEN

#
SubSection @(SubElement.Name) [@(SubElement.QForm)] at level: @(SubElement.Level)
#
      ELIF SubElement.Type = "textblock" THEN
        TEXTBLOCK VAR SubElement.TextBlock
      FI
    OD
OD

END #


Result (for a sample Content Wizard):

Wizard my wizard []
Section one [] at level: 1
--text block 1.1--

SubSection one.two [qform 1] at level: 2
--text block 1.2.1--
--text block 1.2.2--
--text block 1.2.3--

SubSection one.three [] at level: 2

Wizard my wizard  []
Section two [qform 2] at level: 1
--text block 2.1--

The following is the same loop written using FOREACH NODE. 

# BEGIN
WIZARD "myID"
NAME "my wizard"

FOREACH NODE Element IN WIZARD "myID"
DO
  IF Element.Type = "section" THEN
    IF Element.Level = "1" THEN
#
Wizard @(Element.Wizard) [@(Element.WizardQForm)]
Section @(Element.Name) [@(Element.QForm)] at level: @(Element.Level)
#
    ELSE
#
SubSection @(SubElement.Name) [@(SubElement.QForm)] at level: @(Element.Level)
#
    FI
  ELIF Element.Type = "textblock" THEN
    TEXTBLOCK VAR Element.TextBlock
  FI
OD

END #

The FOREACH WIZARD example only processes two levels of elements in the Content Wizard. The FOREACH NODE example processes all elements in the Content Wizard.

Data Definition groups and Text Blocks. Any use of the statement TEXTBLOCK to insert a Text Block in a FOREACH WIZARD/NODE loop will by default apply the context of the FOREACH loop to the Text Blocks and associated QForm. Any Field Sets used in the Text Block and QForm are resolved in the context of the Data Definition first. If no Data Definition is defined, Field Sets are searched outside the Data Definition.

Text Blocks in a Data Definition group always refers to the Field Sets in the current iteration of the Data Definition group. This handles repeating elements automatically.

You can use the keywords DATA_DEFINITION and PATH on the statement TEXTBLOCK to either disable the context handing in a FOREACH WIZARD/NODE loop, or to simulate this behavior outside the loop FOREACH WIZARD/NODE by keeping track of the Path field associated with the Text Block.