4.12.13 p:document

A p:document request is push a document on the context document stack, and thus to change the currently active context document. The context document is the document on which the document related requests apply.

4.12.13.1 Request

Any publisher request element can be nested within p:document.

The p:document request can work in three ways

4.12.13.1.1 (1) Specify the document explicitly

Syntax:

<p:document id="..." branch="..." language="..." version="...">
  [ ... child instructions ... ]
</p:document>

Using the attributes id, branch (optional), language (optional) and version (optional) the new context document is specified.

The branch and language can be specified either by name or ID. If not specified, they default to the main branch and default language.

The version can be specified as "live" (the default), "last" or an explicit version number.

4.12.13.1.2 (2) Specify a field attribute

Syntax:

<p:document field="..." hierarchyElement="...">
  [ ... child instructions ... ]
</p:document>

When the p:document is used in a location where there is already a context document (e.g. from a parent p:document), it is possible to use an attribute called field. The value of this attribute should be the name of a link-type field. This p:document request will then change the context document to the document specified in that link-type field in the current context document. If the current context document does not have such a field, the p:document request will be silently skipped. If the link-type field is a multivalue field, the p:document request will be executed once for each value of the multivalue field. This will then lead to multiple sibling p:document elements in the publisher response.

Exactly the same can also be achieved through the p:forEach request. In fact, the internal implementation uses p:forEach so this is just an alternative (older) syntax for the same thing.

See also p:forEach for an explication of the hierarchyElement attribute.

4.12.13.1.3 (3) Implicit

Sometimes the p:document instruction is used as the child of other instructions such as p:forEach or p:navigationTree. In that case the context document is determined by the parent instruction, and should hence not be specified.

4.12.13.2 Response

The p:document request will output a p:document element in the publisherResponse. This element will have attributes describing the exact document variant and version that the context document was changed to.