Image Placeholders

An image placeholder is a shape in the template that is replaced with an image from the record’s data during generation. Image placeholders work in all three template formats: DOCX, XLSX, and PPTX.

Like all placeholders, the name inside the braces is the machine name of a field on the entity type the template is attached to. The field must be of type File or Image (see data types).

How image placeholders work

An image placeholder is a shape (or text box) whose entire text content is a single placeholder tag.

In this example, the template is attached to an entity type that has a File/Image field with the machine name companyLogo:

{{companyLogo}}

During generation, the engine checks whether the data value for that field is an image reference. If it is, the shape is replaced with the image. If the value is not an image reference (for example, it is a plain string), the shape is left for normal text substitution instead.

The placeholder tag must be the only content of the shape. If the shape contains any other text alongside the placeholder, the engine treats it as a text placeholder, not an image placeholder.

Setting up an image placeholder

To create an image placeholder in your template:

  1. Insert a shape or text box at the position where the image should appear.

  2. Size the shape to the desired maximum dimensions of the output image — the image will scale to fit within this bounding box.

  3. Set the shape’s text content to the placeholder tag — for example, {{companyLogo}}, where companyLogo is the field’s machine name on the entity type.

  4. Remove any other text, formatting, or content from the shape.

The shape’s position and size define the bounding box. During generation, the image is scaled to fit within the bounding box while preserving its original aspect ratio. The image is centered within the bounding box.

Aspect ratio

The engine always preserves the image’s aspect ratio. If the bounding box is wider than the image’s proportions, the image is scaled to match the box height and centered horizontally. If the bounding box is taller, the image is scaled to match the box width and centered vertically.

The image never stretches, crops, or overflows the bounding box.

Supported image formats

The following image formats are supported across all three template types:

  • PNG

  • JPEG

  • GIF

  • TIFF

  • BMP

  • EMF

  • WMF

  • SVG

  • EPS

  • PICT

  • WPG

  • DIB

Format-specific notes

DOCX

Insert a text box for the image placeholder and place the placeholder tag inside it. The entire text box is replaced with the image during generation.

XLSX

Image placeholders are shapes on the sheet. The shape is replaced with the image at the same anchor position.

PPTX

Image placeholders are shapes on a slide. The shape’s text is checked before text substitution — if the resolved value is an image reference, the shape becomes an image; otherwise it receives text substitution as normal.

Common uses

Typical uses for image placeholders in OOH advertising templates include:

  • a company logo on invoices and contracts — the entity type has a File/Image field (for example, machine name companyLogo),

  • a display photo on a campaign proposal or media kit — the display entity type has a field like photo,

  • a map snapshot showing the display location,

  • a creative proof image on an approval document.

Troubleshooting

If an image placeholder is not being replaced:

  • Verify that the shape’s entire text content is the placeholder tag and nothing else.

  • Verify that the field in the record’s data contains an image reference, not a text value.

  • Verify that the image format is one of the supported formats listed above.

  • Check that the field’s machine name in the placeholder matches the field’s machine name in the entity type definition exactly.

Related pages