Placeholder

An alternative to an alternative to “search and replace”, a mapped placeholder is a marker that represents the content of a metadata property present in the root document of a publication. The content of the property is a short, simple text string: text, a date, or time, that is often repeated throughout a publication, for example, [Company Pty Ltd]. Displaying the value of a metadata property in place of the marker in the content, allows updates of the value throughout a publication, with a single edit. Where a document belongs to more than one publication, different metadata property values are possible depending on which publication is published.

Other use cases could be the name of a legal entity or significant date throughout a contract, or the product name in user documentation. 

To reuse longer amounts of content, see transclusion.

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 consistency should be higher.
• Centralizing any explanatory or guidance material should contribute to better quality data.

States

There are two states mapped and unmapped. The following table shows what is displayed in the content when in either state.

Mapped state – usage

User wants to display the value of the metadata property in one or more places in the content.

• Mapped: – has been mapped to a corresponding metadata property.
• Resolved – the mapped placeholder displays the value of the metadata property it is mapped to.
• Unresolved – the mapped placeholder displays the placeholder text. It is unresolved if you haven’t clicked the icon to resolve the placeholders.

Unmapped state – usage

When user wants to leave placeholder text in the content as a prompt to create a corresponding metadata property later. 

• Unmapped – placeholder text has been inserted in document content, but it has not yet been mapped to any metadata property. The user can create the property later.
• Resolved – an unmapped placeholder is standalone, and it displays a metadata property name. This name is automatically generated from the placeholder text when the user types it in the content as a prompt. The metadata property to map to can be created later.
• Unresolved –  the unmapped placeholder displays with a icon and the placeholder text, and the of metadata property can be created later.

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 “unresolved”.

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 & 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.

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

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 will display the name when resolved.

What displays in the document depends on the placeholder state, and to which publication it is resolving. See the table in States above.

Add a new placeholder while editing

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 later 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 some placeholder text, then type "]]". Press Enter.

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 unresolved. 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 later. For more information, see how to create metadata properties for placeholders.

Add a placeholder to an existing property while editing

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. 

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.