ReportListener XML Foundation Class

XmlListener provides the Report Output Application's default implementation of ListenerType 4 (XML output). Its properties include numerous settings you can use to adjust the VFP Report XML Schema to tune its output for different purposes. For example, if you send your report output XML to another application, for import into a database, you may not need the output from Page Header and Page Footer bands in your report. These portions of the report render at intervals based on the physical size of the original report layout page, and may not relate directly to rows of data in the report.

VFP Report XML includes data describing the original report or label file layout information (the frx or lbx table) as well as the run-time REPORT FORM command settings, printer instructions, open tables and relationships. This section of the XML structure is known as the VFP-RDL, or Visual FoxPro Report Definition Language. The schema elements for these items are different from the elements generated for the run-time expressions, lines, and other report layout controls as the Report Engine renders each record during a REPORT FORM command.

For full information on the VFP Reporting XML Schema, see Using VFP Report Output XML.

XmlListener and Report Continuation

XmlListener respects the NOPAGEEJECT keyword on REPORT FORM commands executed in a sequence, so a single VFP Report XML document can include details about multiple report runs.

The native NOPAGEEJECT keyword is only available from within programs (it has no effect when you issue a REPORT FORM command in the Command window). You can use the XmlListener's noPageEject property, rather than the standard keyword, if you want to try this capability out interactively.

XmlListener handles the REPORT FORM command's RANGE clause. However, in report documents containing multiple reports through use of the continuation feature, it only handles RANGE if you do not also use the NORESET clause.

XmlListener's XML Generation Process

XmlListener uses a mix of techniques to provide its XML results. The Visual FoxPro XMLAdapter class provides the portion of the schema that describes FRX and report run-time metadata (the VFP-RDL). It also uses MSXML objects directly to enhance the VFP-RDL nodes. The class generates the data portion of the schema using a "raw" output process that sends data to a file using Visual FoxPro's low-level file functions, and taking full advantage of other native string-handling capabilities to handle normal encoding chores.

#DEFINE OUTPUTXML_RAW             0
#DEFINE OUTPUTXML_DOM             1
#DEFINE XMLOUTPUT      OUTPUTXML_RAW
#DEFINE OUTPUTXML_DOMDOCUMENTOBJECT ;
  "Msxml2.FreeThreadedDOMDocument.4.0"
#DEFINE OUTPUTXML_DOMFREETHREADED_DOCUMENTOBJECT ;
  "Msxml2.FreeThreadedDOMDocument.4.0"
#DEFINE OUTPUTXML_XSLT_PROCESSOROBJECT ;
  "Msxml2.XSLTemplate.4.0"

XmlListener and XSLT

Once you have generated an XML document, you often have to move it from one format to another. XmlListener provides facilities for Extensible Stylesheet Language Transformations (XSLT). You can load XSLT documents and request that XmlListener supply the final result of your chosen transformation, rather than its native VFP Report XML schema document.

XmlListener and its Configuration Table

Like its superclass, UtilityReportListener, XmlListener leverages the same configuration table structure as the Report Output Application. It reserves a range of values in the OBJTYPE (1100 through 1199) as a way to look up XML node names for various reporting elements. Using the configuration structure to store node names is a way of localizing the XML elements for readability. For example, the default value of PH as a node name for Page Header bands might not be intuitive to a developer not working in English, or the developer might prefer a less terse notation. Because XmlListener can read your preferred values at run time, the VFP Report Xml schema should be regarded as a structural model; the actual node names at run time might be different.

XmlListener stores this information in the configuration table according to the scheme you see in the following table.

If XMLListener is the subclass of UtilityReportListener that generates the configuration table at run time, or if it cannot find its required records in the pre-existing configuration table, it will include appropriate records for all the elements it needs. It also adds the specialized index keys it requires to the configuration table, if needed.

Remarks

XmlListener adds the public following properties and methods to its parent class, UtilityReportListener.

Example

In this example, the code tunes XmlListener's properties to suit a particular data transfer scenario (a customer list being transferred between a Visual FoxPro application and a CRM application hosted in a different environment).

The code provides the object's xsltProcessUser property with a suitable XSLT transformation document, using one of the three methods described in the table above for loading the processor object. It instructs the object to apply the XSLT transformation automatically after the report run. It then runs the report. The resulting XSLT fits the requirements of the CRM application and can be imported without further change.

oXml = NEWOBJECT("XmlListener","_REPORTLISTENER")
WITH oXml
  .xmlMode = 0 && data only, 
               && no RDL is needed for this 
               && particular transform
  .xsltProcessorUser = "Customer.xslt"
  .applyUserTransform = .T.
ENDWITH  
REPORT FORM Customer OBJECT oXml
MODIFY FILE (oXml.TargetFileName)

See Also

Reference

Visual FoxPro Foundation Classes A-Z
ReportListener Utility and File-handling Foundation Class

Concepts

Guidelines for Using Visual FoxPro Foundation Classes

Other Resources

Report Output Application