Placeholder
Key point: Displays the content of a single, text or date, metadata property in multiple places throughout a publication or document.

A placeholder is a marker that represents the content of a metadata property from your document or publication. When mapped to a property, it displays that property’s value wherever the placeholder appears.

Placeholders act as dynamic fields that automatically display metadata values throughout your document. They’re especially useful for content that appears multiple times, such as:

  • Company names.
  • Dates.
  • Product information.

When you update a placeholder’s source value once, all instances update automatically, saving time and ensuring consistency across your entire publication.

Unlike search and replace, placeholders maintain a permanent connection to their source values, making ongoing content maintenance straightforward and reliable.

For longer or more complex content reuse needs, consider using transclusion instead.

Usage

Placeholders are useful in the following circumstances:

  • Not all the necessary information is available at the time the content is being written.
  • Producing a new document can be done by substituting some strings of text, rather than duplicating the content.
  • There is a requirement to use a single value in multiple locations, for example, in forms-based documents (name, address or dates).

Creating and updating data in one location, but displaying it in many, has the following advantages:

  • Less editing time is necessary, fewer mistakes are likely, therefore providing higher consistency.
  • Centralizing any explanatory or guidance material contributes to better quality data.

In the user interface, the icon represents placeholders.

Example

Consider a typical software license, where the copyright holder’s name appears multiple times throughout the document:

Using placeholders lets you define the copyright holder’s name only once in the metadata, rather than updating every instance manually when changes are needed.

When you need to update the company name or the year across the entire document, you change the metadata property value only once, and all instances are automatically updated when the document is published or when placeholders are resolved.

States

A placeholder can be mapped or unmapped depending on whether a corresponding metadata property is defined.

You can also choose to resolve the placeholder to show the metadata value by clicking the icon, or leave it unresolved.

The following table summarizes what is displayed in the content:

Mapped state

When a placeholder is mapped, it means that a metadata property with the same name is defined, and it can display the actual value of that property when resolved.

  • Resolved – A mapped and resolved placeholder displays the value of the metadata property.

    For example, in a copyright statement, the ‘year’ and ‘copyright holder’ placeholders show the actual year and company name.



  • Unresolved – A mapped and unresolved placeholder displays the placeholder text.

    This lets you see what the placeholder represents rather than its value.

The name of a placeholder is different to its placeholder text. Typically the placeholder text has mixed case and spaces where the name is all lowercase with underscores instead of spaces. It is the same with the metadata property name and its title (hold the pointer over a property title to see its name). For a successful mapping the placeholder and property name must match exactly, not the placeholder text or title.

If a placeholder that has a corresponding metadata property appears unmapped then use the right-click Placeholder option to select the property from the placeholder dialog. This ensures an exact match.

Unmapped state

When a placeholder is unmapped, it exists in your content but doesn’t yet connect to any metadata property. PageSeeder displays a icon to remind you that this placeholder needs to be mapped.

  • An unmapped placeholder can NOT be Resolved. If you try to resolve it the placeholder displays a warning icon followed by the placeholder name.

    This serves as a reminder that you need to create a corresponding metadata property.



  • Unresolved – An unmapped and unresolved placeholder displays the placeholder text.



It’s okay for placeholders to be unmapped while you’re working on your document. PageSeeder supports unmapped placeholders so that you can focus on authoring and create the corresponding metadata property at another time.

The role of metadata properties in placeholders

A placeholder can be mapped to a corresponding metadata property.

Without a mapped property at the publication (or document) level, PageSeeder considers the placeholder to be “unmapped” and cannot resolve it to a value.

There are no order dependencies on the creation of placeholders. It doesn’t matter if the placeholder creation is before, or after, the property.

Metadata properties of a document are edited in the Metadata tab, in the document info and metadata panel. When a document is also a component in a publication, the metadata of the publication root document is available in the document’s publication tab.

  • When a document is part of a publication – only the root document’s metadata properties are used for placeholders throughout the publication. Where a component document has properties in its Metadata tab, these cannot be used elsewhere in the publication.
  • When a document is not part of a publication – the document’s metadata properties are used only in that document.

Where a placeholder is part of multiple publications, the metadata property can have different values in each publication root.

For more information, see how to create metadata properties for placeholders.

Metadata properties for placeholders can also be created upon document upload.

Resolve placeholders

In review mode, click the icon in the document toolbar to toggle between the placeholder text and the value of the metadata property that corresponds to the placeholder name. An unmapped placeholder displays the name when resolved.

What displays in the document depends on the placeholder state, and to which publication it is resolving. See the table summarizing what displays, in the preceding states section.

When placeholders are resolved, and the publication root document is published, the published content contains the following:

  • A mapped placeholder – has the value of the mapped property.
  • If not mapped – has the placeholder text.

Add a new placeholder while editing

Use this when adding a placeholder to content, before a corresponding metadata property has been created.

To insert a new placeholder in your content using the placeholder dialog:

  • In the editing context menu – click the  Placeholder icon to display the Insert/edit placeholder dialog. You can use this option to map your placeholder to an existing metadata property, or to create a new placeholder, then at another time, create a new metadata property to map it to.

To insert a new placeholder in your content using a shortcut – inline text pattern:

  • In the content – type "[[", then type the placeholder text, then type "]]". Press Space. In this case the placeholder name is generated from the placeholder text by converting it to lowercase and replacing space with underscore.

In both cases, the PSML content has a <placeholder> element in the PSML, for example, <placeholder name="country_of_origin">Country of origin</placeholder>.

Where a corresponding metadata property doesn’t exist yet, the placeholder state is unmapped. When the document is saved, in review mode, you see a icon and the placeholder text to remind you to map it to a metadata property. For more information, see how to create metadata properties for placeholders.

Add a placeholder to an existing property while editing

Use this when a corresponding metadata property has already been created and can be used as a placeholder.

To insert a placeholder and map it to an existing metadata property from the auto-suggested metadata properties available in the group, use a shortcut – an inline text pattern:

  • In your content, for existing properties, you can use the inline text pattern – Type "[" (left square bracket), followed by the first letter of the metadata property name. Press Enter when your name displays, or click another option if more than one is auto-suggested.

The auto-suggest lists all the available metadata properties, that can be used for placeholders, in the current group. Where a property name has an * asterisk at the end, that property is not currently available to use in your current document, but it can be added to your current publication or document.

Configuration

Metadata properties for placeholders don’t require any specific configuration, but they can only be mapped to single value properties with a type of: text, date, or datetime.

For developers: For more information on the <placeholder> element, see the PSML documentation on the PageSeeder developer’s website.