22.2 Creating XML Customizations

22.2.1 Required XML Tags

Every XML customization must contain the following required tag pair:

<report></report>

For example, the following is the most minimal XML customization possible:

<report name="emp" DTDVersion="9.0.2.0.0">
</report>

This XML customization would have a null effect if applied to a report because it contains nothing. It can be parsed because it has the needed tags, but it is useful only as an example of the required tags.

The <report> tag indicates the beginning of the report customization, its name, and the version of the Data Type Dictionary (DTD) file that is being used with this XML customization. The </report> tag indicates the end of the report customization.

The report tag's name attribute can be any name you wish, either the name of the report the XML file will customize, or any other name.

This example represents a minimal use of the <report> tag. The <report> tag also has many attributes, most of which are implied and need not be specified. The only required <report> attribute is DTDVersion.

<report DTDVersion="9.0.2.0.0" beforeReportTrigger="BeforeReport">

A full report definition requires both a data model and a layout and therefore also requires the following tags and their contents:

• <data></data>

• <layout></layout>

The data tag has no accompanying attributes. The layout tag has two attributes, both of which are required: panelPrintOrder and direction. If you use the default values for these attributes (respectively acrossDown and default), you need not specify them. Examples of the data and layout elements are provided in the following sections.

22.2.2 Changing Styles

The example in this section demonstrates the use of XML to change the fill and line colors used for report fields F_Mincurrent_pricePersymbol and F_Maxcurrent_pricePersymbol.

<report name="anyName" DTDVersion="9.0.2.0.0">
  <layout>
    <section name="main">
      <field name="F_Mincurrent_pricePersymbol"
             source="Mincurrent_pricePersymbol"
             lineColor="black"
             fillColor="r100g50b50"/>
      <field name="F_Maxcurrent_pricePersymbol"
             source="Maxcurrent_pricePersymbol"
             lineColor="black"
             fillColor="r100g50b50"/>
    </section>
  </layout>
</report>

We assume in this example that the section and field tags' name attributes match the names of fields in the Main section of the report this XML file will customize. In keeping with this assumption, the other attributes of the field tag will be applied only to the fields of the same name in the report's Main section.

22.2.3 Changing a Format Mask

The example in this section demonstrates the use of XML to change the format mask used for a report field f_trade_date.

<report name="anyName" DTDVersion="9.0.2.0.0">
  <layout>
    <section name="main">
      <field name="f_trade_date"
             source="trade_date"
             formatMask="MM/DD/RR"/>
    </section>
  </layout>
</report>

Notice that the field tag provides its own closure (/>). If the field tag used additional sub-tags, you would close it with </field>.

22.2.4 Adding Formatting Exceptions

The example in this section demonstrates the use of XML to add a formatting exception to highlight values greater than 10 in a report's f_p_e and f_p_e1 fields.

<report name="anyName" DTDVersion="9.0.2.0.0">
  <layout>
    <section name="main">
      <field name="f_p_e" source="p_e">
      <exception textColor="red">
       <condition source="p_e" operator="gt" operand1="10"/>
        </exception>
      </field>
      <field name="f_p_e1" source="p_e">
        <exception textColor="blue">
       <condition source="p_e" operator="gt" operand1="10"/>
        </exception>
      </field>
    </section>
  </layout>
</report>

In this example, the value for operator is gt, for greater than. Operators include those listed in Table 22-1:

Notice also that, unlike the previous example, the field tags in this example uses sub-tags, and, consequently, closes with </field>, rather than a self-contained closure (/>).

22.2.5 Adding Program Units and Hyperlinks

The example in this section demonstrates the use of XML to add a program unit to a report, which in turn adds a hyperlink from the employee social security number (:SSN) to employee details.

<report name="anyName" DTDVersion="9.0.2.0.0">
  <layout>
    <section name="header"> 
      <field name="F_ssn1" source="ssn1">
        <advancedLayout formatTrigger="F_ssn1FormatTrigger"/> 
      </field>
    </section>
    <section name="main">
      <field name="F_ssn" source="ssn">
        <advancedLayout formatTrigger="F_ssnFormatTrigger"/>
      </field>
    </section>
  </layout>
  <programUnits> 
    <function name="F_ssn1FormatTrigger">
      <textSource>
        <![CDATA[
          function F_ssn1FormatTrigger return boolean is
          begin
            SRW.SET_HYPERLINK('#EMP_DETAILS_&<' || LTRIM(TO_CHAR(:SSN)) || '>');
            return (TRUE);
          end;
        ]]>
      </textSource>
    </function> 
    <function name="F_ssnFormatTrigger">
      <textSource> 
        <![CDATA[
          function F_ssnFormatTrigger return boolean is
          begin
            SRW.SET_LINKTAG('EMP_DETAILS_&<' || LTRIM(TO_CHAR(:SSN)) || '>');
            return (TRUE);
          end;
        ]]>
      </textSource>
    </function> 
  </programUnits>
</report>

A CDATA tag is used around the PL/SQL to distinguish it from the XML. Use the same tag sequence when you embed HTML in your XML file. In this example, the functions are referenced by name from the formatTrigger attribute of the advancedLayout tag.

22.2.6 Adding a New Query and Using the Result in a New Header Section

The example in this section demonstrates the use of XML to add a new query to a report and a new header section that makes use of the query result.

<report name="ref" DTDVersion="9.0.2.0.0">
  <data>
    <dataSource name="Q_summary">
      <select>select portid ports, locname locations from portdesc</select>
    </dataSource>
  </data>
  <layout>
    <section name="header">
      <tabular name="M_summary" template="BLAFbeige.tdf">
      <labelAttribute font="Arial" fontSize="10" 
                        fontStyle="bold" textColor="white"/>
      <field name="F_ports" source="ports" label="Port IDs" 
               font="Arial" fontSize="10"/>
      <field name="F_locations" source="locations" label="Port Names" 
               font="Arial" fontSize="10"/>
      </tabular>
    </section>
  </layout>
</report>

This example XML can be run by itself because it has both a data model and a complete layout.

Use aliases in your SELECT statements to ensure the uniqueness of your column names. If you do not use an alias, then the default name of the report column is used and could be something different from the name you expect (for example, portid1 instead of portid). This becomes important when you must specify the source attribute of the field tag, which requires you to supply the correct name of the source column (the field).

The labelAttribute element defines the formatting for the field labels in the layout. Because it lies outside of the open and close field tag, it applies to all the labels in the tabular layout. If you wanted it to pertain to only one of the fields, then you place it inside the <field></field> tag pair. If there is both a global and local labelAttribute element (one outside and one inside the <field></field> tag pair), the local overrides the global.

22.2.7 Encoding the URL

To ensure that spaces and control characters are passed correctly, you may need to turn URL encoding on or off for the fields in your report. You can turn URL encoding on or off with the RW:FIELD tag in a report:

<rw:field
...
urlEncode=yes|no
...
/>

The default value for urlEncode is no.