16.5.0 Import Tag Reference
Import Tags are used to import an external file into your report template output at the time the output is generated. The embedded document may be an image, a text file, a PDF file, or even another template! For example, you might want to import a cover sheet or company logo.
Your data source must contain the location (either a URL or filename) of the content to import, not the actual content itself. For example, with HTML and images, the actual HTML tags or image must not be in the data source. Since you are importing the actual content of the external file into your report, your Import Tag query must return the specified external file’s path or URL (e.g. “C:\users\smithj\documents\filename” or “http://www.sitename.com/filename”)
If the actual content is in the data source, you must use the Out Tag instead.
Although a data source may not be necessary to refer to the file to import, ensure the Import Tag has a data source defined anyway, to avoid unpredictable behavior.
Import Tag Properties
The rest of this article describes each section of the Import Tag properties:
Tag Properties
connection-string (optional)
Use this property to select an Authentication Protocol and its properties. For more details, see Data Access Providers and Authentication Protocols.
default (optional)
This property is set to the URL or file name of a file to import in case the Import Tag's query returns no rows or nodes, or causes an error such as "file not found".
display (optional, default: always)
Set this property to determine whether or not to display the imported file. Options for display are:
- notEmpty - display the imported file only if the data returned is not an empty value or empty string
- notNull - display the imported file 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 the imported file 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 Import Tag to import a file only if that variable's value is greater than two, then set display to "${variable} > 2".
nickname (optional)
The nickname will appear in the template rather than the generic "[import]" 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 specifies the type of file to import. If this property is set, the file’s extension is ignored.
BITMAP - the file to import is an image file.
PDF - the file to import is a PDF file (not supported for PowerPoint)
TEMPLATE - the file to import is a subtemplate or HTML file with no special encoding.
TXT - this type is the same as the default no setting. It is used in rare cases where an Import Tag type is required to be set.
Import Tag of type TEMPLATE are not supported by Windward PowerPoint Templates, so HTML cannot be rendered
If you output to PDF, the imported PDF file(s) are separate pages inserted at the beginning of your report. The Report Designer and Report Engines start a new page, add the imported file as the next N pages, then resume the report at the top of a new page following the imported PDF. If there are two PDF imports in a row, the second starts on a new page after the first. In other words, the imported PDF pages are not modified or combined with any Windward Reports commands; they are inserted at the start of your report.
Other formats that are page-based (DOCX, XLSX) will have a single blank page for each imported PDF file. Other formats that are not page-based (HTML) will skip the PDF file. For the Java engine you need the JAI Image I/O libraries installed. Please note that this is not the entire JAI library. It is just a set of additional reader-writer plug-ins for the java 1.4 javax..image.io classes. AutoTag uses the .NET engine to generate reports and so this is not an issue for AutoTag.
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
Document Properties
break (optional)
before-page - places a section page break before the import
after-page - places a section page break after the import
before-inline - places a section page break before the import
after-inline - places a section page break after the import
distinct - places the section page break before and after the import, removing empty paragraphs before and after the Import Tag. If preceded by a section break or document start, the imported section will be assigned to that section and there will not be a preceding section break. The original settings in the master document will be assigned to the trailing section break.
page -
even -
odd -
inline (optional, default: false)
To understand when to use the use-child-styles property, it is important to distinguish between the two ways to format text in templates and subtemplates: direct formatting and Word Style formatting.
Here are some examples to illustrate the two different formatting methods using a Word document with the Reveal Formatting Pane enabled (SHIFT-F1).
By default, when a Word document is first opened, there is no direct formatting - only the Word Normal Style is in effect, which basically means "no formatting has yet been applied by the user".
Changing settings in the Font or Paragraph sections of the Home tab of the Word ribbon, such as font size, paragraph line settings, etc., is direct formatting.
Applying a Style from the Styles section (the Styles Gallery) of the Home tab is formatting with a Word Style.
Both Word Styles and and direct formatting can be, and often are, combined.
use-child-styles (optional)
This property has effect only when the master template and imported subtemplate use Word Styles with the same name, but different settings. It has no effect if the master template and imported subtemplate use Word Styles with different names, or don't use non-default (i.e. Normal) Word Styles. In the latter case, the imported subtemplate Word Style is applied to the report output.
If the master template and imported subtemplate use Word Styles with the same name, but different settings, then:
- true - use the Word Style settings of the imported subtemplate
- false - use the WordStyle settings of the master template
In any case, direct formatting in the imported subtemplate is applied to the report output. This property only effects Word Style formatting, not direct formatting.
use-parent-format
This property is deprecated.
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 imported by Import 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.
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
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.
Page Numbering with Imported Documents
When a DOCX document or template is imported into a template, page numbering counts across the template and any imported templates. As an example, if page numbering is enforced such as "Page X of Y," Y would be the total number of pages in the output document (not just the pages in the imported document for that documents pages) and X would be the current page in the output document.