| **Navigation:**  [[templates.htm|Templates]] > [[templates by topic.htm|Templates by Topic]] > Advanced Report Generation > Report to XML Support Extension >====== Report to XML Procedure Support ====== | [[tplextensionglobalreporttoxml.htm|{{btn_prev_n.gif|Previous page}}]][[templates by topic.htm|{{btn_home_n.gif|Return to chapter overview}}]][[tplcontrolbrowsebox.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

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.

{{notebox.jpg|NoteBox.jpg}}

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.

{{notebox.jpg|NoteBox.jpg}}

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 (**F**ield **Eq**uate 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.