Skip to main content
Windward

Out Tag Reference

Overview

Tag: Out: <wr:out ... > 

 

An Out Tag is the most basic and most common tag. It tells the template to go to the data source, grab one piece of data – such as a number, a last name, an image, etc. – and place it in the template. Unless told otherwise, the Out Tag will retrieve one data item from the returned data group. It is commonly used in conjunction with the ForEach Tag to retrieve multiple lines or cells of data.

 

The content is displayed and formatted based on the properties you provide 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. The Out Tag can display simple text, images or even HTML formatted content.

Article Contents

Use the Table of Contents (on the right) or the section headings below to navigate through the information on this page.

 

Latest New Features 

Advanced Uses

Properties
Using the Out Tag 

Tag Limitations

Usage and Syntax Examples

Common Uses

Deprecated Features

Related Articles

 

Common Troubleshooting

Advanced Definition

 

Latest New Features

Version 14

  • Additional Refinement for HTML Output
    • Better handling for background images and colors
    • Improved indentation for ordered and unordered lists
    • Better handling of template header and footer images
  • Tag color coding

Version 13

 

 

Back to Top

 

Using the Out Tag

See the linked articles below on ways to use the Out Tag.

 

Out Tag Icons

(v14 and earlier; v15)

Tag Default Color AutoTag Ribbon Properties Interface
Out_Tag1.png  [out]

Sample Templates

The Out Tag is used in almost every sample as its primary purpose is to print data in the final report.  Below are some tag specific and general examples that show off the Out Tag's capabilities.

 

Out Tag Specific Templates

SQL

XML

 

General Templates

 

Back to Top

Common Uses

  • The main use of the Out Tag enables a user to ask a data source a question (based on your data source choice) and the return Output is printed in the final report.
  • Can be used to fetch Images
  • Can be used to fetch HTML snippets and format HTML tags as word settings, i.e. <b> will bold the text in Word output.
  • Used to format output of dates, currencies, time, percentage and many other text formatting requirements in the final report.
  • Used commonly in conjunction with ForEach Tags. The set of data is defined in the ForEach tag and given a variable name. The Out Tags within the ForEach Loop will reference elements of the set of data by variable name and column name (for programmers: ${variable_name.column_name}). Each time the ForEach Tag iterates, the Out Tags contained within will print a new row of data from the data set.
  • Used to add conditional output to Out Tags based on returned value conditions. For example, you can change the font color of  the text if a number returned is negative.

 

Common Troubleshooting

  • HTML snippet tags are not being correctly translated into Word formatting. This is usually because the type property in the tag was not set to template.
  • Date formatting is not applied to text on output. There are 2 possible causes here. First, the type property need to be set to the value date in order to interpret date format output settings. Second, your data may not be formatted in an standard way that Windward can understand. You may need to use the input property to define an input pattern to transform the date data into a format Windward can understand.
  • Images are not being displayed in report output. This could be due to how your image is stored. Refer to the Advanced Uses section to understand when the Out Tag is appropriate for inserting images into a document.
  • Variable values are not appearing in final report output. This is most likely due to the fact that the tag property is not properly set to value.
  • Equations in the select are not being properly calculated in the final report output. This is due to the fact that the tag property is not properly set to evaluate.
  • When using the Out Tag in Excel you may find that your data isn't returning as expected. Excel's native formatting may conflict with settings in your tag to give you unexpected results. Remember that Excel formatting determines what appears in the cell. The tags do not change that value, and whenever possible we use/defer to Microsoft Office's format and settings.

    Example Excel Formatting 

    Suppose you have an Out Tag with native formatting in a cell, and a select that reads as follows:

 

<wr:out select='=ROUND(861.9,0)' format='category:number;decimals:0;useThou:false;negFormat:0;format:0;'/>

 

You want the value returned to be "862". The function ProcessOut() handles this format and produces a correctly rounded value, 862, without a decimal point.

 

However, the cell has a Number format applied to it as well, which dictates to use a decimal point with two digits after it. In the XLSX Output, Excel's format becomes applied and presents a value with a decimal point: "862.00"

 

In this case, you would simply remove the Excel formatting for that cell, or change the tag format to show 0 decimal places.

Advanced Uses

When to use Import Tag versus Out Tag

You can also use almost any format to show an image (including PNG, GIF, TIFF, JPG, BMP, DIB, and more). If your data source contains the actual data to create your image (i.e. it is UUEncoded in an XML file), use the Out Tag. If your data source contains the location of your image (i.e. the file location or URL), use the Import Tag instead.

Using HTML

If your data source contains the actual HTML used to create an web element (usually marked by <![CDATA[]]>), then use the Out Tag. If your data source contains the location of your HTML page (i.e. a URL), use the Import Tag.

Using Java Engine to Determine Output Format

If you’re using the Windward Java Engine, you can use the program net.windward.tools.OutTagFormat to determine the resulting format of an input string based on a given set of type and pattern properties. This program allows you to quickly try different combinations.

 

 

Back to Top

 

Tag Limitations

Parsing Limitations 

Parsing is when the Windward reads the text in the data source element and attempts to determine its value.

 

In the case of using the property ‘value=’ in your tag syntax, no intelligent parsing of the string (a group of characters) occurs. It performs a simple text substitution for all Windward variable (${variable}) entries, then displays the final value. The string is not passed to the data source provider for evaluation. All of the optional properties can be used in this case. For example, if ‘value=’ is a number, it can be displayed as a currency or date.

 

Several attempts are made to parse the input string of data returned from your data source. For a number or currency value, it first attempts to parse the string using the appropriate NumberFormat.parse() method and using NumberFormat.applyPattern() in the Engine. If this fails, it tries Double.parseDouble(). If that fails, it throws a NodeFormatException.

 

For more information parsing in the Engine, please view the Java documentation for the Java classes DateFormatDecimalFormatNumberFormat and SimpleDateFormat.

 

For full details on how to format Out Tag data as dates, numbers, currencies, etc. please refer to the article below.

Format Dates and Numbers with the Out Tag

 

Deprecated Features

  • Beans - Java beans were used to apply special transformations to data output by the Out Tag.   For more information on this deprecated feature please refer to the Bean Guide.

 

 

Back to Top

 

Advanced Definition

The Out Tag is used to display (or output) the contents of a single value in your document or report. The content is displayed and formatted based on the properties you provide in the Out Tag. The Out Tag can display simple text, images or even HTML. A list of support HTML tags and properties are listed below. Keep in mind that you must set the property type = "TEMPLATE" in order for the HTML to be properly interpreted. In doing this, the HTML tags will be converted to their Microsoft Office equivalents. For example, if an HTML snippet has a bold tag <b> applied it will convert the text it surrounds to be bold when printed in the final Microsoft Office output report.

Supported HTML And CSS For Type=”TEMPLATE” 

Windward supports a limited subset of HTML 4.01 for use in templates. The supported tags, attributes, and units/formats are listed below:

Supported Tags and Attributes

Tag​

​HTML Attributes

CSS Attributes​

​<a>

​href, style

color, font-size​

<b>​

style​

color, font-size​

​<body>

style​

color, font-size​

<br/>​

 

 

<div>

bgcolor, style

background-color

<em>​

style​

color, font-size​

<font>​

color, face, size, style​

color, font-size​

<i>​

style​

color, font-size​

<img/>​

alt, src

 

<li>​

style​

color, font-size​

<ol>​

style​

color, font-size​

<p>​

align, bgcolor, class, style​

background-color, color, font-size​

<span>

bgcolor, style

background-color, color, font-size

<strike>​

style​

color, font-size​

<strong>​

style​

color, font-size​

<sub>​

style​

color, font-size​

<sup>​

style​

color, font-size​

<table>​

bgcolor, border, style, width​

color, font-size, width​

<tr>​

bgcolor

 

<td>​

bgcolor, style, width​

background-color, color, font-size, width​

<u>​

style​

color, font-size​

<ul>​

style​

color, font-size​

Supported Formats For HTML

HTML Attribute

Supported Formats

alt

Any text

align

left, center, right, justify

bgcolor

  • Hex values, eg, #F03, #FF0033
  • black, silver, gray, white, maroon, red, purple, fuchsia, green, lime, olive, yellow, navy, blue, teal, aqua

border

px values

class

Any text

color

  • Hex values, eg, #F03, #FF0033
  • black, silver, gray, white, maroon, red, purple, fuchsia, green, lime, olive, yellow, navy, blue, teal, aqua

face

Any text

href

Any text

size

  • 1-7 (standard HTML sizes)
  • pt and px values

src

Any text

style

CSS

width

  • px values
  • percent values
  • numbers (px)

Supported Formats For CSS

CSS Attribute

Supported Formats

background-color

  • Hex values, eg, #F03, #FF0033
  • black, silver, gray, white, maroon, red, purple, fuchsia, green, lime, olive, yellow, navy, blue, teal, aqua
  • rgb(R,G,B) where R, G, B are integers

color

  • Hex values, eg, #F03, #FF0033
  • black, silver, gray, white, maroon, red, purple, fuchsia, green, lime, olive, yellow, navy, blue, teal, aqua
  • rgb(R,G,B) where R, G, B are integers

font-size

  • 1-7 (standard HTML sizes)
  • pt and px values

width

  • px values
  • percent values
  • numbers (px)

 

Back to Top

Properties

You may access the details or properties of a specific Out Tag by using the Tag Editor.

Required properties

When using Out Tags, one of these three properties must be set from the Tag Editor (all examples below are using XML as a data source):

 

  • select – (default) Displays the contents of the data returned by your select statement.

 

 

  • value – Displays the contents of a variable. Set this property to the name of the variable by dragging it from the Parameters tree to the select area or entering manually in the following format ${Variable_Name}. 

 

 

  • evaluate – Evaluates an expression and displays the result. Set this property to evaluate variables and expressions or a combination of both. 

 

 

Note select, value, & evaluate can include a ${variable} value from a ForEach, Query, or Set Tag. If the variable is for an XPath query (XML), it must be in the form ${variable.xpath}, NOT ${variable}/xpath (as would be expected from SQL).

Advanced

  • default – Set this property to the text to insert into the report if the data that your select points to does not exist. If the node or field exists but is empty, nothing prints in the report, so watch out for nodes that don't contain any data and fields that don't have any values.
  • display – Set this property to determine whether or not to display data. The default value for display is ‘always’ (unless overwritten in display.default in properties or configuration file). Values 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 as 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 (i.e. true or false). For example, you could use an expression like "=10 + 20" to display the Out Tag if it is true, or not display it if it is false.
  • input – Set this property to the pattern to use in order to format incoming data in a way Windward can understand. For example, if the value = $12.34 instead of 12.34, indicate the pattern of this field so the report generator interprets it correctly. The input pattern you select depends on the type of the data value that is returned.  You will need to set this if you store your data in a non standard way.  Once this property is set you will then need to use the format property in the Tag Properties section below to apply an output format.

 

For full details on how to format Out Tag data as dates, numbers, currencies, etc. please refer to the article below.

Format Dates and Numbers with the Out Tag

 

Note, in the case of a Number or Currency, the pattern is passed to the DecimalFormat.applyPattern() class in the Engine code. In the case of type=DATE, the pattern is passed to SimpleDateFormat.applyPattern class in the Engine code.

Bitmap

  • height - set a defined height for the image in twips (twips are a word processing measurement unit consisting of one twentieth of a point).
  • horz-align - sets the alignment of the image in relation to surrounding text.  Options are left, center, or right.
  • horz-position - sets 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 - allows the user to define specific dimensions an image should use when displayed in the final report
    • bitmap - use the size of the image defined in the image file (most bitmaps have a DPI setting. So pixels per DPI is inches.)
    • specified - specify an exact width and height setting for the image display dimensions.
    • specified-width - specify the width dimension which will automatically scale the height by the same amount.
    • specified-height - specify the height setting which will automatically scale the width by the same amount.
    • fill-width - this sets the width to the width of the paragraph or table cell the image is in and automatically scales the height by the same amount.
  • vert-align - sets the alignment of the image in relation to surrounding text.  Options are top, center, or bottom.
  • vert-position - sets the position of the image relative to the page vertical layout.  Options are setting the image relative to the inline, margin, page, or paragraph.
  • width - set a defined width for the image in twips (twips are a word processing measurement unit consisting of one twentieth of a point).
  • wrap – set this property to control how the image is placed in relation to surrounding items on the page.
    • 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. The text is not moved around the image.
    • behind – The image is placed behind the text. 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 to each side, depending on how tall the image is.

Datasource

  • datasource - allows a user to select the data source that the Out Tag will retrieve its data from.  Only appears if multiple data sources are added to a template

Standard

  • description - allows a user to enter notes about the tag.  This is useful if you need to give further instructions about the tag for maintenance purposes.
  • enabled - allows a user to turn a tag on or off when the report is run.  When a tag is turned off at report runtime, it will be ignored and not printed when the report is created.

Tag

  • condition - allows a user to create one or multiple conditions that when evaluated will apply formatting changes to the Out Tag result. For more information on its usage, review the links below.
  • format – Set the format (pattern) to use when displaying the data. Use the format selector detailed in the article below for more details. You can also set the format manually if needed. The format set here determines the output of your data when it is generated.
  • nickname - the text defined here will be displayed for the tag placeholder in the template. If you wish to create a friendly name for your tag, enter it here. Note that square brackets [] will surround any text that you enter here when it appears in the template to identify it as a tag.
  • type – This property defines both how the data is read from your data source and how it is displayed. By default AutoTag should be able to detect and set the proper type of your incoming data, however with data sources like XML you may have to set it manually. See WindwardReports.Properties or app.exe.Config pages (depending on the Engine you are using) for details. This uses the Java formatting libraries NumberFormat and DateFormat. Numbers are read using DecimalFormat.parse(). You will need to tell the Out Tag which type of data is returned.
    • Bitmap - allows the incoming data to be interpreted as an image and is assumed to be a Base64 encoded string of a file image. The 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 systems 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.
    • Number - allows the incoming data to be interpreted as a number locale-specific equivalent. Once the type is set to number, use the format property above to format a number such as currency.
    • Template - used to insert a subreport or HTML snippet into a document. Use this when the subreport or HTML data is the actual value in the database (use the Import Tag if only a filename or URL is used to reference a template stored in a database). Any Windward input template format is supported for subreports. PDF files can also be inserted, but only if the output format is PDF. When inserting a subreport from XML data sources, use the UUEncoded value. When inserting HTML from XML data sources, the HTML must be wrapped in a <![CDATA[...]]> block.
    • Time - allows you to format incoming data as a time or date/time. By default the time or date/time will be displayed in the your systems region (locale-specific) format. Refer to the format property above for more details on advanced time and date/time formatting.
  • var - allows a user to set a variable name for the value returned to the Out Tag.  This can be referenced in other tags after it is set to be used for comparisons, additional printing, filtering, etc.

Other properties

For OleDB images, you need to set the check.for.ole.images property to true in the .NET or Java Engine Windward properties file. This is because OleDB types (such as Microsot Access) add a header to file data which needs to be stripped off before the image can be correctly displayed.

  • For AutoTag, it's easiest to set this in the registry (follow these steps):
  1. Open the Registry Editor (‘regedit’ from Windows Search bar).
  2. Create the key (not value, but key) ‘HKEY_CURRENT_USER\Software\Windward Studios\Reporting Engine’
  3. In the Reporting Engine key create a string value check.for.ole.images
  4. Set the value to true

 

Back to Top

Usage and Syntax Examples

XML Usage

<wr:out select="./name"/> - which will replace the tag with the text in the referenced XML node in the final report

 

or

 

<wr:out value="${item}"/> - which will replace the tag with the text in the referenced variable

 

The variable ${item} elements can come from a var and varStatus properties in a ForEach Tag, the var property in all other tags.  They can  from a key/value pair programmatically passed to the Engine.

 

Maps and Views are created in your by the programmer implementing your Windward report generation system. This person can inform you about the variables available for various reports.

SQL Usage

<wr:out select=”select DESCRIPTION from PRODUCTS where PRODUCT_ID = ${item.PRODUCT_ID}”/>

 

The select (like all selects) returns all matching rows of descriptions from the products table where the product is filtered by the item's product id. Next, the field in the first column of the first row returned is read, and this is the value that is displayed in the report. All additional rows are ignored as an Out Tag an only return a single row. For multiple rows you need to use an Out Tag inside a ForEach Tag.

 

Note: Using the select property with a SQL data source is identical to using the value property. This is because a SQL select returns a result set or rows of information, not a string or characters, and a result set cannot be directly displayed as text.

Complex Example

This is an example of a formatted Out Tag syntax using a date.

<wr:out select="./name" default”00/00/00” type=”DATE”/>

For full details on how to format Out Tag data as dates, numbers, currencies, etc. please refer to the article Format Dates and Numbers with the Out Tag

Evaluate Usage 

View the following syntax usage for the evaluate property.

evaluate=′${item.price} * ${item.quantity}′

The values (price and quantity) of the variable ${item} are an expression and the expression is multiplied for a final value. The evaluate substitutes Windward variables (in the form ${var}), yet evaluates the final text so that "${item.subtotal} / 100" will not appear as "1295 / 100" but as a total 12.95. This is useful for situations such as "${price} * ${quantity}" to retrieve a line item total from your data source.

Example of Value vs. Evaluate Property

View the following syntax usage of value versus evaluate.

value=′${item.price} * ${item.quantity}′

Value causes a substitution of the values of these variables results in returning “12.95 * 3”. However, using evaluate causes 

evaluate=′${item.price} * ${item.quantity}′

which substitutes the values of the variables, then evaluates the expression, resulting in 38.85.

 

Back to top

Related Articles

See these articles for further information:

 

See these articles for Tag-Specific information.