Placeholder Mapping (PlaceholderMapping)

---

Purpose and use

Placeholders are required so that dynamic data can be displayed in layouts.

The placeholder mapping is used to fill the placeholders in the content template or a PowerPoint template with the desired data, which were previously "promised" in a parent template - e.g. a layout or a master template - using the Placeholder Definition (PlaceholderDefinition) function.

The data can come from the Forms document function or via the Fields document function (user data, JavaScript functions).

The following example assigns the Field FooterGeneral from the Fields document function to the placeholder with the name Footer:
<Text Name="Footer" SourceField="FooterGeneral" />

note

Every placeholder that has been defined in the layout must be mapped, otherwise an error message appears.

tip

In the context of snippets, the mapping can be generated automatically with $.createAutoMapping() instead of writing every entry by hand.

Basic Structure

<PlaceholderMappingConfiguration>
  <Mappings>
    <!-- Placeholders -->
  </Mappings>
</PlaceholderMappingConfiguration>

---

Attributes

The following attributes must be set for all available element types (Text, Picture, YesNo):

Attribute name	Description
Name (required)	Is required for identification, can be named the same as the field from Forms or Fields. Must not contain any spaces.
SourceField (required)	Is required to map the field from Forms or Fields. Accordingly, the ID of the corresponding field is entered here.

There are three sources for placeholders that can be addressed in the SourceField attribute:

• a user field: Profile.User.FirstName
• a Forms field: Forms.MyTextfield / Forms.MainSigner.FirstName
• a Field: MyField (Caution: the name of a Field must not contain a dot, because grouping is only possible via Objects and ObjectCollections).

info

In the vast majority of cases, a Field is created that dynamically combines and returns content - and is then assigned to a placeholder. User fields are practically never assigned without a detour via a Field.

---

Elements

Text

<Text Name="CreateDate" SourceField="Forms.Date" />

Picture

<Picture Name="PartnerLogo" SourceField="PartnerLogo" />

YesNo

<YesNo Name="ShowClassification" SourceField="Forms.ShowClassification" />

note

YesNo is currently only supported for PowerPoint binding (not in Word or Excel templates).

GlobalMappings

The GlobalMappings element can be used to retrieve a globally stored placeholder mapping.

<GlobalMappings Key="Placeholders.Map.Letter" />

More information about the global configurations can be found here: Global Configurations.

A concrete example for recognising the connection between the global entry and the reference to a global entry can be found here: Global Configurations.

Attributes for GlobalMappings

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.

---

Taking over placeholders from the layout

So that the mapping does not have to be transferred placeholder by placeholder from the layout by hand, the placeholder-mapping editor offers the "+ Insert layout configuration" action. It reads the Placeholder Definition (PlaceholderDefinition) of the underlying layout or master template and reconciles it with the current mapping.

When run:

• For every placeholder defined in the layout that is still missing from the mapping, an empty mapping entry is inserted. The SourceField is then assigned by hand.
• Existing mappings are left unchanged; no duplicates are created.
• Mappings that no longer correspond to any placeholder in the layout (orphaned entries) are not deleted but commented out — so no information is lost and the cleanup stays under your control.

The reconciliation also resolves referenced global entries: both the GlobalDefinitions of the layout definition and the GlobalMappings of the mapping are flattened before the comparison.

tip

Which global mapping the action pulls its defaults from is controlled by the layouter in the placeholder definition via the DefinitionMappings block.

Example XML configuration

<PlaceholderMappingConfiguration>
  <Mappings>
    <!-- Data for header -->
    <Text Name="CreateDate"      SourceField="Forms.Date" /><!-- from Forms -->
    <Picture Name="PartnerLogo"  SourceField="PartnerLogo" /><!-- from Fields -->
    <!-- Data for footer -->
    <GlobalMappings Key="Placeholders.Map.Page" /><!-- globally stored -->
    <Text Name="Footer" SourceField="Profile.Org.Footer" /><!-- from user profile -->
  </Mappings>
</PlaceholderMappingConfiguration>