ReportListener XML Foundation Class

Artículo
06/24/2008

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.

Category	Reporting
Default Catalog	Visual FoxPro Catalog\Foundation Classes\Output\Report Listeners
Class	XmlListener
Base Class	ReportListener
Class Library	_REPORTLISTENER.vcx
Parent Class	UtilityReportListener (ReportListener Utility and File-handling Foundation Class)

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.

Important Note:
You must observe the same constraints when applying continuation to XML generation as you would use when printing. You are responsible to issue a final REPORT FORM without a NOPAGEEJECT clause to tell XmlListener to stop writing to the file, just as you would need the final REPORT FORM command to close the print queue. However, if you forget to do this, the Destroy method of the class will end the output job and close the file.

You must observe the same constraints when applying continuation to XML generation as you would use when printing. You are responsible to issue a final REPORT FORM without a NOPAGEEJECT clause to tell XmlListener to stop writing to the file, just as you would need the final REPORT FORM command to close the print queue. However, if you forget to do this, the Destroy method of the class will end the output job and close the file.

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.

Tip

You can recompile the class to adjust the MSXML objects XmlListener uses, and you can also opt to use MSXML objects consistently rather than the "raw" method it uses by default to provide the data portions of the output. Using MSXML objects throughout the processing can facilitate some scenarios in which your report output requires specialized encoding of binary data. To adjust the generation process, change the defined values in XmlListener's header file, REPORTLISTENERS.H. The default values are shown below:

#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.

Field	Usage
OBJTYPE	Stores the original FRX table OBJTYPE value for the type of band or layout object the XML element describes, plus an offset of 1100. For example, a Picture layout control in an FRX has the OBJTYPE 17, so a record storing the XML node name for a Picture layout control has the value 1117.
OBJCODE	Has the same value as a record of the same type in the FRX. For example, a record storing the XML node name for a Detail Footer band has the same OBJCODE as a DetailFooter band record in the FRX.
OBJNAME	Not used by XmlListener
OBJVALUE	Stores the node name.
OBJINFO	Stores a descriptive value for the type of FRX record. For example, Detail Footer Band nodename .

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.

applyUserTransform Property

Indicates whether XMLListener should automatically apply a user-defined XSLT transform at the conclusion of a report run.

Default .F.

Remarks: When you set this property to .T., the associated assign method checks to see if you have already filled the xsltProcessorUser property with an appropriate processor object. If not, it runs an internal method, getDefaultUserXslt, to load the xsltProcessorUser property. This internal method provides a hook for subclasses to supply their preferred XSLT document for use without requiring an external load procedure.

applyXslt Method

Provides generic facilities for applying XSLT to XML.

Syntax: applyXslt (vSource, vProcessor [, vParamCollection])

Return Values: cXmlResult

Parameters:

vSource can be the name of a file holding the source XML document, a string holding the XML document, or a DOM document object.

vProcessor can be the name of a file holding the XSLT processor document, a string holding the XSLT document, or an XSLT processor object.

vParamCollection is an optional object of Collection type. If it is available, this method adds the members of the collection to the XSLT processor instance as global parameters before applying the XSLT transformation to the source document. It uses the collection keys as parameter names, and the corresponding collection values as parameter values.

XmlListener provides a property, xsltParameters, you can use to hold the collection you build to hold these parameters between calls.

Remarks: Both the XML source and XSLT processor object types are defined in REPORTLISTENERS.H. You can edit this header file and recompile the class to choose different processing objects.

contAttr Property

Supplies the name of the attribute used to show continuation type for a layout object that can span bands or pages.

Default "c"

currentDocument Property

Holds information about the XML document for which output is currently being generated during a report run.

Default .NULL.

heightAttr Property

Supplies the name of the XML attribute used to show height for a layout object.

Default "h"

idAttribute Property

Supplies the name of the XML attribute used to provide the FRX record number for a layout object or page number of a formatting band (column or page) object.

Default "id"

idrefAttribute Property

Supplies the name of the XML attribute used to provide the current page for a layout object or FRX record number of a formatting band (column or page) object.

Default "idref"

includeBandsWithNoObjects Property

Indicates whether band-level information for bands with no contents should be included in the XML.

Default .F.

includeBreaksInData Property

Determines whether formatting bands (page and columns) should be included in output and, if so, using what structure.

Value	Meaning
0	Provide page band nodes positioned along with other bands in the datastream, wherever they happen to occur
1	No pagebreak info, no page header and footer info
2	Provide collection of pages with page headers and footers data

Default 0

includeDataSourcesInVfpRdl Property

Indicates whether information about the source tables, relations, indexes, etc. should be included in the VFPRDL metadata section of the report XML.

Default .F.

includeFormattingInLayoutObjects Property

Indicates whether formatting information such as positioning attributes should be included in the report XML.

Default .F.

leftAttr Property

Supplies the name of the XML attribute used to show leftmost position for a layout object.

Default "l"

noPageEject Property

Indicates whether the XML Listener should consider the current report run to be continued. Can be used without NOPAGEEJECT on the REPORT FORM command.

Default .F.

resetDocument Method

Resets the XML document after a report run.

Syntax: resetDocument()

Return Values: none

Parameters: none

topAttr Property

Supplies the name of the XML attribute used to show topmost position for a layout object.

Default "t"

verifyNCName Method

Provides generic method to validate strings as XML-standard NCNames.

Syntax: verifyNCName ( cName )

Return Values: lValid

Parameters:

cName is the string you are checking for validity as an NCName value.

Remarks: In XML, an NCName or non-colonized name is a legal value for either the namespace or the non-prefixed (local) name of a node. For example, in the node name xsl:template, both xsl and template are NCNames.

widthAttr Property

Supplies the name of the XML attribute used to show width for a layout object.

Default "w"

xmlMode Property

Determines what parts of the VFP Report XML schema are included in output.

Value	Meaning
0	Data only
1	VFP-RDL only
2	Data and VFP-RDL

Default 2

xsltParameters Property

Holds an optional parameter collection passed to the ApplyXSLT method when XmlListener automatically applies a user XSLT transformation at the conclusion of a report run.

Default .NULL.

Remarks: The code example in ReportListener HTML Foundation Class uses xsltParameters explicitly, to set numberPrecision, one parameter of its default transformation. The class's code sets several other parameters of the default HTML transformation using xsltParameters. If you create xsltParameters as a collection object yourself, as shown in that example, the HtmlListener class will use this object, adding any required keys and values after checking to see if they already exist.

xsltProcessorRdl Property

Holds a Report Definition Language (RDL) -specific processor object.

Default .NULL.

Remarks: Reserved for future use. You can load an XSLT processor object to this property using the same techniques as described for the xslProcessorUser property.

xsltProcessorUser Property

Holds a user-definable processor object which, if filled and available at the end of a run, can be used automatically by XML Listener to transform the raw XML document to requirements.

Default .NULL.

Remarks: To change this document, you have several options:

Store a filename to the property, as shown in the example below.
Store an XSLT document contained in a string variable to the property.
Store an XSLT processor object, with its stylesheet already loaded, to the property. The appropriate object types are defined in XmlListener's header file, REPORTLISTENERS.H.

If you store the document as a string or a filename, XmlListener creates the processor object for you, and loads the stylesheet.

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)

Compartir a través de

ReportListener XML Foundation Class

XmlListener and Report Continuation

XmlListener's XML Generation Process

XmlListener and XSLT

XmlListener and its Configuration Table

Remarks

Example

See Also

Concepts

Reference

Other Resources

Recursos adicionales