Visual FoxPro 9.0 SP2
This conceptual topic supplies information about a new-in-SP2 FFC VFP Reporting
System extension feature.
The remarks in this docoid are intended to improve, and in some details to correct, the VFP SP2 CHM entries on Document Properties Tab, Report Properties Dialog Box (Report Builder) and How to: Add Document Properties to a Report.
The remarks in this docoid are intended to improve, and in some details to correct, the VFP SP2 CHM entries on Document Properties Tab, Report Properties Dialog Box (Report Builder) and How to: Add Document Properties to a Report.
Back to TMM Index
Overview
Some Document Properties are "generic" in the sense that they can easily be used by different output types. For example, a Microsoft Word document, a PDF document, and an HTML document all have might some use for "keywords" or a "copyright". The properties of this type that are provided in-the-box have the prefix Document. to make this clear, including Document.Keywords.
Other Document Properties have meaning only for one extension output type. For example, only HTML output is likely to make good use of a CSSFile. The set of such properties provided in-the-box for HTML output have the prefix HTML. including of course HTML.CSSFile.
As with all Advanced Properties, you can create your own additions to Document Properties. You are encouraged to follow a similar prefix-naming convention as the in-the-box set, to make your intentions clear. If your property is useful for multiple output types, use the prefix Document.If your property might be used by any renderer capable of creating an RTF file, then perhaps RTF. is a good prefix.
Regardless of output types to which your property applies, if it is only useful for your own company's proprietary extension behavior, you can prefix it with your own company's namespace, using whatever dot-syntax allows you to classify the different types of behavior you offer.
For example, suppose you develop a compression technique that can be used as a final delivery step in all output types that result in a physical file or files being created. The values you assign to this particular property are specific to your fx class, or to your listener class. They provide complex instructions regarding passwording, file-naming, etc. You might call this property Document.YourCompany.Compression.
This theoretical Document.YourCompany.Compression property would probably use an XML type, which is best suited to store complex instructions in one property. (Alternatively, your compression utility might use several individual properties, such as Document.YourCompany.Compression.Password and Document.YourCompany.Compression.FileSkeleton.) As with all Advanced Properties, the ReportBuilder presents different editing capabilities for different "types" of Document Properties, and the FFC ReportListeners understand and respect these types. The following chart is repeated from Appendix C of the article on Data Visualization in Reports:
Document
Properties and the RunCollector in FFC ReportListeners
You may be wondering: since Document Properties are not associated with any specific FRX elements that display in the physical layout, how are these properties "surfaced" in report interfaces, at runtime?
Of course, like all Advanced Properties, you can find your Document Property instructions in FRX MemberData. They are associated with the header record, just as the engine associates other global aspects of the report, such as printer setups and page size, with the header record. But this MemberData is the metadata, the description of what you want to happen. You also need a place for the outcome, the result of these instructions during the report run.
FFC's _ReportListener class offers a new PROTECTED member, called the runCollector, which you can use for storage of Document Properties results, and other non-layout-oriented result of the report run.
For example, suppose you implemented a Document.Index property, providing an index expression and a "frequency of evaluation" indicating whether the expression should be evaluated every page, every detail band, or when. During the run of the report, you could store the results of the expression in the runCollection, adding information every time you evaluated it. The full set of results would be available at the end of the report.
The RunCollector is a very "elastic" concept. It is exposed as an abstract idea in _ReportListener and FXListener, so that everyone can use it, for any type of information you might want to gather up during a report run and use after all data in the run has been evaluated. Document Properties provide one good example of how to use this concept, because they are a particularly easy way of exposing your specifications for whatever data you want to store during the run.
You can read more about this idea, and how it is implemented in the FFC, in the Using _ReportListener's RunCollector TMM docoid. XMLListener provides a fully-worked implementation of the RunCollector idea, and its derived classes, especially HTML Listener, make use of this feature. A separate docoid on Using Document Properties and the Run Collection in XMLReportListener and its Derived Classes describes this implementation.
In-the-box reference usage of Document Properties
See Also
Overview
Reporting MemberData provides a way to associate information and report
instructions with FRX elements that include attributes and ideas never before
associated with an FRX. For example, FRX controls don't have a "rotation"
characteristic, but MemberData gives you a place to store one.
Advanced Properties are a way of exposing MemberData quickly and easily.
Using Advanced Properties, you can create new characteristics on-the-fly at
design-time and have access to them at run-time. Each Advanced Property is
defined as a new attribute on a particular report element: a control or report
band.
Document Properties are a special type of Advanced Property, providing a
way to store information and report instructions that are global to the report,
not associated with any report element. Document Properties store information
that is (a) global to the report and (b) has intrinsic value to one or more
output types, even though it doesn't help render any of the individual
report elements.
While it's possible to use Document Property information during the rendering of
some standard element(s) in the report, the special value of Document
Properties is to hold information that has no relationship to
anything in the physical layout, none of the bands and none of the controls, at
all..
Note
|
|---|
|
If you really want to, you can write code to apply the information contained in
a Document Property to some physical element in the report.
For example, you might decide to create a report control that had an Advanced Property tagging it as your "copyright FRX control". You could evaluate any Document.Copyright expression during the BeforeReport event in your reportListener-derived class once, for efficiency, and store the result. During the Render event, your reportListener-derived class could note the availability of this result when it rendered your "copyright control". It would substitute your copyright expression when rendering the "copyright control". However, there isn't much value to doing this; you could just as easily have attached the same information into the Advanced Property you created for the copyright control itself. The FX or GFX object recognizing and manipulating the copyright control can still evaluate the expression for the copyright just once, in BeforeReport, for the same efficiency. |
Some Document Properties are "generic" in the sense that they can easily be used by different output types. For example, a Microsoft Word document, a PDF document, and an HTML document all have might some use for "keywords" or a "copyright". The properties of this type that are provided in-the-box have the prefix Document. to make this clear, including Document.Keywords.
|
Tip
|
|---|
| The in-the-box set of generic Document Properties were, in fact, derived from Word's Document Property set. |
Other Document Properties have meaning only for one extension output type. For example, only HTML output is likely to make good use of a CSSFile. The set of such properties provided in-the-box for HTML output have the prefix HTML. including of course HTML.CSSFile.
As with all Advanced Properties, you can create your own additions to Document Properties. You are encouraged to follow a similar prefix-naming convention as the in-the-box set, to make your intentions clear. If your property is useful for multiple output types, use the prefix Document.If your property might be used by any renderer capable of creating an RTF file, then perhaps RTF. is a good prefix.
Regardless of output types to which your property applies, if it is only useful for your own company's proprietary extension behavior, you can prefix it with your own company's namespace, using whatever dot-syntax allows you to classify the different types of behavior you offer.
For example, suppose you develop a compression technique that can be used as a final delivery step in all output types that result in a physical file or files being created. The values you assign to this particular property are specific to your fx class, or to your listener class. They provide complex instructions regarding passwording, file-naming, etc. You might call this property Document.YourCompany.Compression.
This theoretical Document.YourCompany.Compression property would probably use an XML type, which is best suited to store complex instructions in one property. (Alternatively, your compression utility might use several individual properties, such as Document.YourCompany.Compression.Password and Document.YourCompany.Compression.FileSkeleton.) As with all Advanced Properties, the ReportBuilder presents different editing capabilities for different "types" of Document Properties, and the FFC ReportListeners understand and respect these types. The following chart is repeated from Appendix C of the article on Data Visualization in Reports:
| Edit Type | Description |
|---|---|
| 1 or 0 | Expression (strings would have quotes) |
| 2 | Text/XML (may contain carriage return/line feed) |
| 3 | String (quotes not required) |
| 4 | File (file name, basically same as string but will use GETFILE() for editing |
| 5 | Boolean (editor forces 0=No, 1=Yes) |
Document
Properties and the RunCollector in FFC ReportListeners
You may be wondering: since Document Properties are not associated with any specific FRX elements that display in the physical layout, how are these properties "surfaced" in report interfaces, at runtime?
Of course, like all Advanced Properties, you can find your Document Property instructions in FRX MemberData. They are associated with the header record, just as the engine associates other global aspects of the report, such as printer setups and page size, with the header record. But this MemberData is the metadata, the description of what you want to happen. You also need a place for the outcome, the result of these instructions during the report run.
FFC's _ReportListener class offers a new PROTECTED member, called the runCollector, which you can use for storage of Document Properties results, and other non-layout-oriented result of the report run.
For example, suppose you implemented a Document.Index property, providing an index expression and a "frequency of evaluation" indicating whether the expression should be evaluated every page, every detail band, or when. During the run of the report, you could store the results of the expression in the runCollection, adding information every time you evaluated it. The full set of results would be available at the end of the report.
The RunCollector is a very "elastic" concept. It is exposed as an abstract idea in _ReportListener and FXListener, so that everyone can use it, for any type of information you might want to gather up during a report run and use after all data in the run has been evaluated. Document Properties provide one good example of how to use this concept, because they are a particularly easy way of exposing your specifications for whatever data you want to store during the run.
You can read more about this idea, and how it is implemented in the FFC, in the Using _ReportListener's RunCollector TMM docoid. XMLListener provides a fully-worked implementation of the RunCollector idea, and its derived classes, especially HTML Listener, make use of this feature. A separate docoid on Using Document Properties and the Run Collection in XMLReportListener and its Derived Classes describes this implementation.
In-the-box reference usage of Document Properties
XMLListener provides access to all Document Properties, regardless of prefix,
and whether they originate as an in-the-box property or one that you have added,
by adding a new-in-SP2 Run XML element,
containing a
property node for each one. HTMLListener
leverages this exposure of the Document Properties by using information in the
Run
node to enrich the resulting HTML content.
Caution |
|---|
| Some information related to usage of
Document
Properties
and
Advanced Properties
in the VFP SP2 CHM is inexplicably misleading. In particular, tables listing
in-the-box Document Properties indicate that their sole purpose is to provide
extensions to HTML content. Only the HTML.-prefix
properties were designed specifically for HTML use. The CHM also states that "If there is no corresponding HTML element for the property, the <meta> tags in the <head> section of the HTML file include the value of the property." This is not really the case. HTMLListener's default XSLT only pays attention to general Document.-prefix properties (along with, of course, the specific HTML.-prefix properties) if they can be applied usefully in HTML. The "useful" set of general properties includes some items, such as Document.Title, that have corresponding HTML elements, and others, such as Document.Author, that the XSLT recognizes as having a common meaning in a <meta> tag. It does not unilaterally introduce <meta> tags based on every document property you might create; it ignores those that it does not recognize. The CHM also states that the Document Property HTML.Metatag.HTTP-EQUIV contains 'The value of a <META HTTP-EQUIV="name" CONTENT="content"> tag'. This is not accurate or even understandable. Please see Using Document Properties and the Run Collection in XMLReportListener and its Derived Classes for more information. |
See Also