Skip to main content

Image Tag Reference

info

The Image tag is an extension of the Out and Import tags that is more use-case specific. It is equivalent to the Out and Import tag with the type property set to BITMAP.

Image Tag Functionality​

The Image Tag tells the template to retrieve BITMAP image data from the specified location. This tag is unique in that it is represented in the document as an image object, rather than text. This allows certain properties such as wrapping and size applied to the image object to also be applied to the resulting image in your report.

Image tags can reference image data contained directly in the datasource as Base64 encoded string of an image file, or image data linked externally at a URL or file path. This behavior is determined by the reference-type Tag Property. Image tags with a direct reference-type value will pull image data directly from the datasource, while tags with an indirect reference-type will assume the image is being linked from an external location.

info

Here is a sample template that demonstrates the Image tag and reference-type usage: Image Tag Sample Template Download

Image Properties​

Tag Properties​

reference-type (default: direct)

Determines how to reference the data in the tag.

  • direct - Data will be treated as a Base64 encoded string of an image file
  • indirect - Data will be treated as an external link to an image file view a path or url

nickname (optional)

The nickname to reference the tag rather than the generic "[imageBitmap]" label. Descriptive nicknames can be very important in designing complex templates.

default (optional)

This property is set to the URL or file name of an image file to reference in case the Image Tag's query returns no rows or nodes, or causes an error such as "file not found".

connection-string (optional)

Use this property to select an Authentication Protocol and its properties. For more details, see Data Access Providers and Authentication Protocols.

Bitmap Properties​

image-alt-text (optional)

An alternative description of the image used when generating PDF/UA-1 output.

image-crop (optional)

The image-crop setting allows the size of an image to be specified, and the image will be output maintaining it’s aspect ratio and constrained by the specified dimensions. The image-crop setting only has an affect when the image-size is set to specified or container.

  • fit - maintain the images aspect ratio and display the full image constrained by the specified dimensions with extra space in the margins of a single dimension.
  • fill - maintain the images aspect ratio and display part of the image constrained by the specified dimensions with excess image cropped in a single dimension.

image-size (optional)

This setting allows the user to specify their image size. The options are:

  • bitmap - Output the image at it’s actual size.
  • specified - Output the image constrained to the specified width and height (set image-crop fill or image-crop fit to maintain the aspect ratio).
  • specified-width - match the specified width of the image in the document, but size the height to maintain the aspect ratio.
  • specified-height - match the specified height of the image in the document, but size the height to maintain the aspect ratio.
  • container - The image size when the container setting is set is the size of the current container of the tag (ex. the current page in DOCX, the current cell in XLSX, or the current slide in PPTX).

image-source (optional, default: inline)

When reference type is indirect, whether the resulting image in the output document should be embedded (inline) or linked to. When reference type is direct, the resulting image is always embedded in the document.

  • inline - the resulting image is embedded in the document
  • linked - the resulting image is linked to from the document

Standard Properties​

description (optional)

A brief description of this Tag.

enabled (default: on)

Controls whether a Tag is executed when generating output. This can be useful when debugging a template.

  • on - this Tag will be executed when output is generated.
  • off - this Tag will not be executed when output is generated.
  • engine-only - this Tag will be executed only if output is generated using one of the Report Engines.
  • autotag-only - this Tag will be executed only if output is generated using Report Designer.

Advanced Properties​

display (optional, default: always)

Set this property to determine whether or not to display data. The default value can always be overwritten using the display.default setting in the properties or configuration file. Options for display are:

  • notEmpty - display the output data only if the data returned is not an empty value or empty string
  • notNull - display if the data node or field exists, even if it is an empty string (an empty string is not NULL since NULL is an actual value in a database)
  • always - (default) display even if the data does not exist (a blank will show if the data does not exist).
  • A Boolean expression that evaluates to true or false. For example, if you have a Set Tag variable "${variable}" whose value is a number, and you want your Image Tag to display its contents only if that variable's value is greater than two, then set display to "${variable} > 2".

error-handling (optional)

Selects which types of errors produce warnings rather than exceptions, which allows output to be generated despite the error.

  • Ignore type error - these errors occur when a Tag's defined data type is different than the data type of the data returned by the Tag's query
  • Ignore formatting error - these errors occur when a Tag's specified format is not compatible with the format of the data returned by the Tag's query
  • Ignore select error - these errors occur when a Tag's query fails to find valid data
  • Node must exist - these errors occur when a row or node is queried which doesn't exist in the data source. These errors typically return an empty value that is output without warning.
  • Node must not return NULL - these errors occur when a query returns an empty or NULL value. These errors typically return an empty value that is output without warning.
  • Treat warning as error - forces all of the above error-handling warnings to appear as errors (not exceptions). This is useful when used with Report Designer's Verify feature.