4.12.15 p:forEach

Executes publisher instructions for each document in a list of documents. The list of documents on which to operate can either result from a query or an expression.

4.12.15.1 Request

4.12.15.1.1 Query

Syntax:

<p:forEach useLastVersion="true|false">
  <p:query>select ... where ... order by ...</p:query>
  <p:document>
    [ ... child instructions ... ]
  </p:document>
</p:forEach>

If the useLastVersion attribute is false or not specified, the live version of each document will be used, otherwise the last version.

If there is a context document available then the ContextDoc function can be used in the query or expression.

4.12.15.1.2 Expression

Syntax:

<p:forEach useLastVersion="true|false">
  <p:expression [precompile="true|false"] [hierarchyElement="all|an integer"]>...</p:expression>
  <p:document>
    [ ... child instructions ... ]
  </p:document>
</p:forEach>

The expression is an expression using the Daisy query language syntax, and should return link values.

The optional precompile attribute indicates whether the expression should be compiled just once or recompiled upon each execution. Usually one should leave this to its default true value.

When the value returned by the expression is a hierarchy path (or a multivalue of hierarchy paths), then p:forEach will by default run over all the values in the hierarchy path. The optional hierarchyElement attribute can be used to select just one element from the hierarchy path. This attribute accepts integer values and 'all'. If you do not specify the hierarchy element attribute then 'all' will be used by default.

• all wil use all the elements in the path as context documents.
• A positive number will select the n^th element starting from the beginning of the path.
• A negative number will select the n^th element starting from the end of the path.

An illustration. Consider the following hierarchy: /domain/kingdom/subkingdom/branch/infrakingdom. Using 2 as hierarchyElement will get you documents at the level of kingdom. Using -2 will get you documents at the level of branch. As you can see the hierarchyElement specification is 1-based. Choosing level 12 will get you nothing since the hierarchy does not have 12 levels.

4.12.15.1.2.1 Examples

If the current context document has a link field (single or multi-value) called MyField, then you could run over its linked documents as follows:

<p:forEach useLastVersion="true|false">
  <p:expression>$MyField</p:expression>
  <p:document>
    <p:annotatedDocument/>
  </p:document>
</p:forEach>

If you have a number of documents which are linked in a chain using a certain field (e.g. Category documents with a link field pointing to their parent category), then the GetLinkPath function is a useful tool:

<p:expression>GetLinkPath('CategoryParent')</p:expression>

4.12.15.2 Response

Zero or more p:document elements.