16.5.0 Out Tag Reference
The Out Tag is the most common Tag used in Word, Excel and PowerPoint report templates. It is used to retrieve a piece of data from your data source - such as a number, a last name, an image, etc. - and place it in the template's output. It is commonly used with the ForEach Tag to retrieve and display multiple lines or cells of data.
The content is displayed and formatted based on the properties you set in the Out Tag. The content is also displayed and formatted according to the native Microsoft Office font settings (font size, type, color, bold, italic, underline, cell formatting) you apply to the cell or text. The Out Tag can display simple text, images or even HTML-formatted content.
Out Tag Properties
Here we see the properties of an Out Tag. Below, each property is described in detail. Unless otherwise noted, each property is required.
Since the Out Tag in the screenshot above is a Text Tag, all of the Bitmap properties are shown. If the type is changed to BITMAP, only the 16.3.0 bitmap properties will be shown. Properties for bitmap type tag are shown bellow:
The rest of this article describes each section of the Out Tag properties:
Tag Properties
condition (optional)
Allows the creation of one or more conditions that when met apply formatting changes to the Out Tag output. For more information about its usage, see How Do I Conditionally Format an Out Tag's Output?.
format (optional)
Set the format pattern to use when displaying the data. See Using the Format Data Interface for more details. You can also set the format manually if needed. The format set here determines the output of your data when it's generated.
nickname (optional)
The nickname will appear in the template rather than the generic "[out]" label. Square brackets ("[]") will surround any text you enter here when it appears in the template to identify it as a Tag. Descriptive nicknames can be very important in designing complex templates.
type (optional)
This property defines both how the data is read from your data source and how it is displayed. By default Report Designer Office Edition (the Designer) should detect and set the appropriate type of your incoming data, however with data sources like XML you may have to set it manually. See the Java Report Engine Configuration File Reference or the .NET Report Engine Configuration File Reference articles for details. This property uses the Java formatting libraries NumberFormat and DateFormat. Numbers are read using DecimalFormat.parse(). Use the following values to tell the Out Tag which type of data is returned:
-
BASE64_TEMPLATE - use to insert a Base64-encoded subtemplate or HTML snippet into a document. Use this when the Base64-encoded subtemplate or HTML data is the actual value in the data source (use the Import Tag if only a filename or URL used to reference a template is stored in the data source). Any Windward input template format is supported for subtemplate. PDF files can also be inserted, but only if the output format is PDF. When displaying HTML from XML data sources, the HTML must be wrapped in a "<![CDATA[...]]>" block before it is Base64 encoded.
- BITMAP - allows the incoming data to be interpreted as an image and is assumed to be a Base64 encoded string of an image file. The Report Engine will decode the Base64 string, read it as a bitmap, and display the returned image in your report output.
- DATE - allows you to format incoming data as a date. By default the date will be displayed in the your system's region (locale-specific) format. The data does not need a time in this case. Refer to the format property above for more details on advanced date formatting. Report Designer will recognize widely-used date formats such as ISO 8601; to input date formats unrecognized by Report Designer, see the input property below.
- HEX_TEMPLATE - use to insert a hexadecimal-encoded subtemplate or HTML snippet into a document. Use this when the hexadecimal-encoded subtemplate or HTML data is the actual value in the data source (use the Import Tag if only a filename or URL used to reference a subtemplate is stored in the data source). For more details see BASE64_TEMPLATE above.
- NUMBER - allows the incoming data to be interpreted as a locale-specific number, with locale-specific decimal and thousands separators, etc. Once the type is set to number, use the format property above to format special numbers such as currency.
- PDF - use to insert a PDF file into a document. Use this when the PDF file is the actual value in the data source, such as a blob in a SQL database (use the Import Tag if only a filename or URL used to reference a template is stored in the data source). This can only be used when generating PDF output.
- TEMPLATE - use to insert a subtemplate or HTML snippet with no special encoding into a document. Use this when the subtemplate or HTML data is the actual value in the data source (use the Import Tag if only a filename or URL used to reference a template is stored in the database). For more details see BASE64_TEMPLATE above.
- TXT - this type is the same as the default no setting. It is used in rare cases where an Out Tag type is required to be set.
Out Tag of type TEMPLATE is not supported by Windward PowerPoint templates, so HTML cannot be rendered
var (default: varName1)
This property allows a user to set a variable name for the value returned to the Out Tag. The variable can be referenced in other Tags after it is set and used for comparisons, additional printing, filtering, etc.
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 the Report Designer
Document Properties
To understand when to use the use-child-styles and use-parent-format properties, it is important to first understand the two ways to "style" text in an Out Tag:
- Using a Word Style from the Style Gallery in the Styles section of the Word Home ribbon. If the imported text is in a Word document, by default it has the 'Normal' Style. You can also apply another Style from the Style Gallery, or create a custom Style and apply it.
- By "direct formatting", which is every other method for changing font attributes, like using the Font section of the Home Tab in the Word ribbon, HTML tags, etc.
In particular, for case #1 above, if the Word Style of the report template and the Word Style of the imported text have the same name, then use these properties to choose which Word Style to use.
use-child-styles (optional)
This property controls whether the Style settings of the text imported by the Out Tag is used, or the Style settings of the report template is used (as in case #1 above), when both Styles have the same name.
- true - use the Style settings of the imported text
- false - use the Style settings of the report template
This property has no effect on case #2 above.
use-parent-format (optional, default: false)
Use this setting to strip the direct formatting from the text to be imported as in case #2 above:
- true - use the direct formatting of the imported text
- false - use the direct formatting of the report template
This property has no effect on case #1 above.
Data Source
This property allows you to select which data source the Out Tag connects to. It only appears when the template is connected to multiple data sources.
Bitmap Properties for Tags as OOXML Objects
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).
Bitmap Properties for Text Tags
Bitmap properties control the layout of images on the page much like the Layout Options for images in Word. You can control the alignment, position, size, and word wrap of bitmaps displayed by Out Tags.
It is important to distinguish between images displayed by Out Tags, and images imported by Import Tags. Use an Out Tag to import images that are stored directly in a data source and retrieved by a query, such as a blob in a SQL database table, or a Base64-encoded bitmap in an XML file. Use an Import Tag when your data source contains the location (either URL or filename) of the image to import, rather than the actual image itself.
We strongly recommend using the native Word Layout Options for Out Tags displaying images in Word templates. However, in Excel and PowerPoint templates, where that feature doesn't exist, use the Out Tag Bitmap properties.
Bitmap properties are only applicable to Tags written as "Field Tags" or "Text Tags", which is specified in the Report Designer options.
height (optional)
Set the height of the image in twips ("twips" is a word processing measurement unit consisting of one twentieth of a point)
horz-align (optional)
Set the alignment of the image relative to any surrounding text. Options are left, center, or right.
horz-position (optional)
Set the position of the image relative to the page horizontal layout. Options are setting the image relative to the column, inline, margin or page.
image-size (optional)
This property allows the user to define the dimensions of an image when displayed in the output:
- bitmap - use the size of the image defined in the image file
- specified - specify an exact width and height for the image
- specified-width - specify the image width, and automatically scale the image height by the same amount
- specified-height - specify the image height, and automatically scale the image width by the same amount
- fill-width - set the image width to the width of the paragraph or table cell containing the image, and automatically scale the image height by the same amount
vert-align (optional)
Set the alignment of the image relative to any surrounding text. Options are top, center, or bottom.
vert-position (optional)
Set the position of the image relative to the page vertical layout. Options are setting the image relative to the inline, line, margin, page or paragraph.
width (optional)
Set the width of the image in twips ("twips" is a word processing measurement unit consisting of one twentieth of a point)
wrap (optional)
inline (default) - this is the way Microsoft Office normally places an image into a document, with text before and after it continuing to flow, but with only one line of text matched with the image.
front - the image is placed on top of the text, and covers the text behind it. The text is not moved around the image.
behind – the image is placed behind the text, and is covered by the text before it. The text is not moved around the image.
square – the text is placed on both sides of the image – if it fits – but will have multiple lines of text on each side, depending on how tall the image is.
If the wrap property is set to inline, all other bitmap property settings are ignored.
Advanced Properties
default (optional)
Set this property to the text to display if the Out Tag's query selects a node or field that doesn't exist. If the node or field selected does exist but is empty (has no value), then nothing is displayed; so if you see nothing in your output were you expect something to be displayed, your Out Tag query may have selected a node or field with no value.
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 Out 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.
input (optional)
Set this property when the format of the data in the data source to be displayed is unrecognized by Report Designer. For example, Report Designer automatically recognizes dates in some widely-used formats such as ISO 8601 and SQL datetime table columns. But a lesser-used format such as "Monday-2018.February.05" may be unrecognized by Report Designer as a date. In this case, enter a format pattern into the input property, so Report Designer will recognize data in that format as a date. For more details about using the input property see Advanced Formatting Using the Out Tag Format and Input Properties.
0 Comments
Add your comment