Placeholder Definition
Purpose and use
Placeholders are required in order for dynamic data to be displayed in layouts.
This function can be used to define placeholders in layouts for Word and in PowerPoint master templates. This specifies in the layout which fields must be filled in the content without the layout knowing the promised content.
The configured placeholders are inserted into the template via the primedocs editor and then filled with the correct data during document generation via Placeholder Mapping in the content.
An error message appears in the content if a placeholder has not been filled.
Basic structure
<PlaceholderDefinitionConfiguration>
<Definitions>
<!-- Placeholders -->
</Definitions>
</PlaceholderDefinitionConfiguration>
Attributes
The following attributes must be set for all available element types (Text, Picture):
| Attribute name | Description |
|---|---|
Name (required) | Is required for identification. Must not contain any spaces and must be unique. |
Elements
Text
<Text Name="CreateDate" />
Picture
<Picture Name="PartnerLogo" />
How an image is fitted into a PowerPoint shape (exact dimensions or fitted) is not defined here in the placeholder definition, but via the shape tag PRIMEDOCS.PICTUREMODE (values Fit/Exact) on the target shape. See Setting the image size for details.
YesNo
<YesNo Name="ShowClassification" />
YesNo is currently only supported for PowerPoint binding (not in Word or Excel templates). There, the type controls the visibility of shapes and slides — via the tags PRIMEDOCS.PLACEHOLDER.VISIBILITY, PRIMEDOCS.VISIBILITY and PRIMEDOCS.REMOVEIFNOT — and does not output any text itself.
In Word the type therefore does not appear at all in the «Insert placeholder» ribbon command's «Select placeholder» dialog — if a definition contains only YesNo placeholders, the selection stays empty and Word reports «There are no placeholders available to insert.» For Word layouts, control visibility through logic or represent the value with Text/FormattedText instead. See Overview: field type per Office application.
GlobalDefinitions
The GlobalDefinitions element can be used to retrieve a globally stored placeholder definition.
<GlobalDefinitions Key="Placeholders.DefNeutral" />
More information about the global configurations can be found here: Global Configurations.
A concrete example for recognizing the connection between the global entry and the reference to a global entry can be found here: Global Configurations .
Attributes for GlobalDefinitions
The reference to a global entry is made using the Key attribute. If you select it, a list of all available global entries is automatically displayed.
| Attribute name | Description |
|---|---|
Key (required) | The ID of the global entry to be referenced. |
DefinitionMappings
A placeholder definition can optionally contain a DefinitionMappings block. It has no effect on the placeholders themselves; instead it tells the content template's "+ Insert layout configuration" action which global mappings should additionally be inserted into the Placeholder Mapping (PlaceholderMapping) when the layout is taken over.
<PlaceholderDefinitionConfiguration>
<DefinitionMappings>
<GlobalMappings Key="Placeholders.Map.Footer" />
</DefinitionMappings>
<Definitions>
<GlobalDefinitions Key="Placeholders.Def.Footer" />
<Text Name="CreateDate" />
</Definitions>
</PlaceholderDefinitionConfiguration>
When the action runs, the GlobalMappings listed here are added to the content template's Mappings; keys that already exist are skipped.
| Element name | Description |
|---|---|
GlobalMappings | References a globally stored placeholder mapping via the required Key attribute. Can be repeated any number of times. |
Example XML configuration
<PlaceholderDefinitionConfiguration>
<Definitions>
<!-- Data for header -->
<Text Name="CreateDate" />
<Picture Name="PartnerLogo" />
<!-- Data for footer (globally stored) -->
<GlobalDefinitions Key="Placeholders.Def.Footer" />
</Definitions>
</PlaceholderDefinitionConfiguration>