Clarion Community Help

The Report to XML Procedure template provides exact control as to when to use this Extensible Markup Language output document format, global overrides of selected string settings, and report controls that need to be hidden or skipped when this output format is enabled.

The following options are provided (and only available if the associated Global Extension is active):

Populate on Report

The Report to XML Global Extension populates this template in all reports by default. Select Never if you do not want this report to be directed to an XML document. Select Always if you want to have this capability available always for this report at runtime. Select Conditional if you need to make this output available based on a certain condition, specified in the next prompt.

Condition

This prompt is available if you have specified Conditional in the Populate on Report prompt above. A condition can be a simple variable or an expression. If the variable or expression evaluates to non-zero, the XML document output capability will be active for this report at runtime.

Press the “E” button to call the Expression Editor. This dialog is used to help you construct syntactically correct expressions to use in the Condition prompt.

General Tab Options

Output Name Type

If you have directed that the report print to an XML document file specify a Fixed, Variable or Runtime name here. Fixed will use a default name, and add page numbers and other extensions (as discussed on the tab control). Variable can be used to designate a fixed name based on a variable condition at runtime, like a date, user name, order number, etc.

Runtime allows the end user to specify a custom name and optional folder to direct the XML document to.

Save output as separate files

By default, an XML document will be a continuous single document, regardless of the size of the contents of the generated report. Check this box to designate that XML documents are generated based on the number of pages generated by the report.

XML Options

The following prompts allow you to add additional XML text to your generated output:

Each XML document contains one or more elements, the boundaries of which are either delimited by start-tags and end-tags, or, for empty elements, by an empty-element tag. Each element has a type, identified by name, sometimes called its “generic identifier” (GI), and may have a set of attribute specifications. Each attribute specification has a name and a value.

Encoding

Select an encoding standard from the drop list, or None to default to the standard encoding method. In certain cases, inconsistencies between the character encoding specified in the XML declaration and the actual character encoding used to serialize the XML document could occur.

This can cause a “Switch from current encoding to specified encoding not supported.” error when you load your XML document.

Character encodings provide a map between a series of numbers and the characters people expect to see when they enter text into computers. Some XML documents can contain foreign characters like Norwegian æøå, or French êèé.

For reliable processing, XML documents that use character encodings other than UTF-8 or UTF-16 must include an encoding declaration in the XML declaration. This makes it possible for a parser to read the characters correctly or report errors when it cannot process an encoding.

Root Tag Name

A root tag name is required by all XML documents. Enter a hard coded string value, or specify a variable that will hold the root tag name (using the !variablename format)

Use Pages as Parent Tag

Check this box to create a parent XML tag for each page generated by the report. These tags are used to navigate from page to page in a browser.

Support Name Spaces

In editing XML documents, it is often convenient to use “white space” (spaces, tabs, and blank lines) to set apart the markup for greater readability. Such white space is typically not intended for inclusion in the delivered version of the document. On the other hand, “significant” white space that should be preserved in the delivered version is common, for example in poetry and source code.

Check this box to enable name spaces support in your output XML document.

Omit XML Header

Check this box to omit the generation of the XML header from your output documents. Some programs that are used to process XML documents may require this.

Which XML format?

This option allows you to designate how the report data generated will be formatted in the XML document. Select from the drop list one of the following supported formats available with the Clarion templates:

Tags ' Considered the standard format of XML. Similar to the tag format used in HTML documents. This format is best used when you need to add other XML elements to the report data output.

By default, the tag format derives its tag information based on the field name (label) defined.

Example:

<;phone_number>

 <;location>Home<;/location>

 <;number>555.555.1111<;/number>

<;/phone_number>

Attributes

The attributes format is used to simplify data elements that have complex information to output. Using the attributes format is less verbose and easier to use. As with tags, an attribute derives its name from the control name (field equate label) by default.

Example:

<;phone_number location=“home”>555.555.1111<;/phone_number>

Metadata Tags

Metadata, loosely defined, is information about information. Additional information about a data element, like a reference URL and author, can be embedded within the XML document.

By default, the metadata tag format derives its tag information based on the control name (field equate label) defined.

Metadata Attributes

You can also embed metadata information using the shorthand attributes format. As with metadata tags, a metadata attribute derives its name from the control name (field equate label) by default.

Refresh values by type

Based on the type of XML format you have selected, press this button to automatically seed all individual report controls with the proper default settings used for the selected format.

Controls Tab Options

The Controls tab displays a list box of every report control's Field equate label that is populated on the report structure. A Field equate label (FEQ) can represent text displayed on the generated report output, but can also identify report logic for Headers, Footers, Detail Bands, Form Bands, and Break structures. Select a control in the list box, and press the Properties button to modify a report's target FEQ.

Controls' XML Properties

HIDE (Omit printing)

If a report's FEQ (Field Equate Label) targets a field used specifically for special documents generation (i.e., Hyperlinks, Bookmarks, etc.), check this box to hide (omit) this FEQ from the report's printed output.

SKIP (Omit processing)

A report's contents can be redirected to multiple types of output documents when using the new Advanced Report Generation templates. Check this box to designate that the selected FEQ will not be used for this type of generated document output (e.g., XML). For example, you would want to skip a control used to generate a special HTML tag when generating to XML.

Tag Type

There are a variety of XML tags supported and available with the included template. Select from the following tag types:

Tag

These tags are the heart of the XML document. They usually represent data elements that are grouped within a Root Tag Child (required by all XML documents). When Tag is selected as the Tag Type, the Parent Tag prompt is enabled and required.

Root Tag Child

The Root Tag Child is a report control FEQ that represents the primary root tag of the output document. There can only be one root tag defined.

Attribute

A report's FEQ can also be used as an XML attribute tag. This is used to assign additional XML attributes to an existing XML tag. Use the Parent Tag prompt below to attach the attribute to a target tag.

Value

Select this tag to designate that the report's FEQ is used as “metadata” in the XML document output. Use the Parent Tag prompt below to attach the attribute to a target tag.

Html Comment

Select this tag type if the selected control's FEQ will be used as a document comment, similar to a remarks line in programming languages.

Header Attribute

Select this tag type if the selected control's FEQ will be used as an attribute in the XML Header, or document declaration. There are a variety of attribute types supported (e.g., version number, schema name, name spaces settings.)

Parent Tag

This option is enabled when you have selected a standard tag type for the selected report's FEQ. You must specify a parent control that this tag will be assigned to.

Name Type

This option defines the actual name of the tag that will be output to the XML document. From the drop list, select Control Name to use the name of the selected control's FEQ with the question mark removed. Select Control Text to use the actual contents of the control's use variable as the tag name. Select HardCoded to enter string text to use to define the tag name, or Dynamic to use the contents of a selected variable to use as the tag name.

Value Type

This option defines the actual value that will be assigned to the XML tag associated with this control. From the drop list, select Control Name to use the name of the selected control's FEQ with the question mark removed as the tag value. Select Control Text to use the actual contents of the control's use variable as the tag value. Select HardCoded to enter string text to use as the tag value, or Dynamic to use the contents of a selected variable to use as the tag value.

No Value specifies that the tag name contains an empty element, and that the tag name itself is used to format a part the XML document.

The Value is CDATA

Check this box to indicate that this control will contain binary data, special characters, etc. that should be ignored by the XML parser. Only text inside a CDATA section is ignored by the parser.

Process only once

Check this box to indicate that the document generator should only process the selected control once.