How to hide an image conditionally

Introduction

When using dynamic picture, Carbone will print a white placeholder with crosses in case of errors:

• The image value is empty (empty string or attribute missing from the JSON dataset)
• The image URL or Data-URL format is not correct
• The image can't be downloaded from the provided URL

Three solutions are available to hide the image:

• NEW: drop formatter
• hideBegin/hideEnd formatters
• Insert an alternative image

First solution: Hide the image with the drop formatter

Since Carbone v4.3.0, the drop formatter is available to delete images and any element from a document. Be sure to request version 4 (or higher) of Carbone:

• For the Cloud API: set the header "carbone-version":4
• For the Cloud Studio: Click on the top-right "settings" icon > click on "version" > Select 4.X.X.

For the following exemple, we want to drop an image if the value is empty.
Include the Carbone tag {d.pic:ifEM:drop(img)} within the image' title, description or alternative text. Details:

• the d.pic value is an image URL coming from a JSON dataset
• the :ifEM is a conditional formatter checking if the value is empty
• the :drop(img) formatter is fired if the previous condition is true. The first argument img is required to defined the element to drop.

Locations to insert tags for:

• LibreOffice: Double click on the image > Select the Option tab > Insert the {d.pic:ifEM:drop(img)} tag on the alternative text.
• MS Word: Double click on the image > Select the Picture format tab > Click on "Alt text" button on the picture menu > Insert the {d.pic:ifEM:drop(img)} tag on the alternative text

Note: On the below screenshots, the first {d.pic} is used by Carbone to print a picture dynamically.

Second solution: Hide the image with hideBegin/hideEnd

Conditional formatters hideBegin/hideEnd are an alternative solution to the drop formatter.
For the following exemple, we want to hide an image if the value is empty.
The following statement checks if the image is empty, if true, the dynamic picture will be removed from the document:

{d.image:ifEM:hideBegin}
// IMAGE JUST HERE
{d.image:hideEnd}

As an example, an ODT template is created, and a temporary picture is inserted (1200x600 grey picture) with the alternative text {d.picture:imageFit(contain)} .
The temporary picture will be used by Carbone to insert the image coming from your JSON data-set. Conditional blocks are wrapping the image to hide it if the image value is empty. The {d.image:ifEM:hideBegin} should be place before the image, and the {d.image:hideEnd} after the image. Make sure the image as anchor set to As character or In line with text. Finally the imageFit(contain) expression will scale the image to fit within the temporary image container.

The following JSON data-set is used to generate the document:

{
  "image": ""
}

As the image is an empty string, the image is removed and the generated document prints nothing.

Third solution: insert an alternative image

As an example, an ODT template is created, and a temporary picture is inserted (1200x600 grey picture) with the alternative text {d.image:ifEmpty(.imageError, true):imageFit(contain)}. The temporary picture will be used by Carbone to insert the image coming from your JSON data-set. If the image is empty, the imageError will be injected inside the document ( imageError is a transparent image of 1 pixel). Finally the imageFit(contain) will scale the imageError to fit within the temporary image container.

The following JSON data-set is used to generate the document:

{
  "image": "",
  "imageError": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}

As the image value is an empty string, the imageError is injected inside the generated PDF:

Updated on: 03/07/2025