You are here: TextDynamic Reporting
Move back to: Products
Common:
Reporting is available for the products TextDynamic and RTF2PDF/TextDynamic Server. It makes it possible to generate a document from a report template with embedded fields, conditional bands and groups. Due to the new "Token to Template Conversion" it is possible to convert an existing report (RTF file) to a template.
Please check out our TextDynamic Manual, Chapter "Reporting".
If you use the token to template conversion you can edit the reporting template with an editor such as MS Word.
The template is loaded into TextDynamic. In this control the template can be further edited with the additional convenience of syntax highlighting and on demand converted into a "true" reporting template. (The latter uses nested paragraphs to represent groups and special paragraph types for bands. Fields are not text based but use objects instead.).
Editing is not possible in the non visual RTF2PDF TextDynamic Server - we include an external application which offers the syntax highlighting.
If you used the mail merge feature before and have documents with embedded merge fields those can be easily used a reporting templates as well! It is also possible to convert an existing report into a template.
The token to template conversion uses special character combinations to separate the commands from the text. Fields have to be embedded into the characters << and >>.
Example for fields:
<<name>>
The name of a field may contain space characters.
Optionally the closing '/' character can be printed:
<<name/>>
Using such fields mail merge documents can be created. Such merge documents only require fields to be filled with data. Using mail merge does not require the reporting extension so we decided to make the syntax highlighting and token to template conversion available in the basis edition.
Bands are identified by a colon (':') after the opening << characters.
Example for header bands:
<<:HEADER>>
This starts a group header or, if used outside of any group a document header text. In the latter case the following variations are possible:
HEADERF = header on first page only
HEADERO = header on odd pages
HEADERE = header on even pages
HEADER_OFF = this header is disabled.
Please note that bands are not implemented using opening and closing tokens ("i.e. <<..>>...<</...>>") so optionally the closing '/' character can be typed: <<:HEADER/>>
Example for footer bands:
<<:FOOTER>>
This starts a group footer or, if used outside of any group a document footer text. In the latter case the following variations are possible:
FOOTERF = footer on first page only
FOOTERO = footer on odd pages
FOOTERE = footer on even pages
FOOTER_OFF = this footer is disabled.
Inside header and footer bands fields, images and text is possible. A header and footer band ends where either a different header or footer band starts or a data band:
<<:DATA/>>
Bands must be the first non white space (white space= space or tab characters) in a paragraph. All text after the band token will be ignored and can be used to write comments.
Groups are identified by a double cross ('#') after the opening << characters. While bands <<:.../>> are not nested, groups can be nested and so are embedded into a tag pairs <<#...>> <<#/....>.
Unlike header and footer bands the name of the group tags are not fixed. Practically any name can be used if it does not contain spaces. However the opening token must match the closing token. For practical reasons the names should match the database which is referenced inside of the group.
Example:
<<#CUSTOMERS>> comment: we list all customers in this group
<<Customers.Name/>>
<<Customers.Address/>>
Ordered Items:
<<#ORDERS>> comment: we list all items ordered by the current customer
<<Orders.Name/>>
<<#/ORDERS>>
<<#/CUSTOMERS>>
Note: The name of a group will be passed to the event OnReportState while creating a report. This event has to decide if a group should be processed (again) or not. It can create a sql query and calculate sub totals.
<<:HEADERF "my header"/>> -- any text after the group will be ignored as comment
This is the header on the first page
<<:HEADER "my header"/>> -- HEADERF, HEADERO, HEADERE, HEADER
This is the header on all pages
<<:TEXT>> -- start the regular text
Dear Developer,
This letter documents and demonstrates the reporting feature which is based on a template written in regular formatted text with additional tags:
The "<<#" signs are expected as first non-space signs in a paragraph. Any text after the closing >> signs is ignored and can be used as comment. Fields are inserted between the signs << and >>. It is important that after the '<<' no white space or punctuation is written.
Headers in groups are written using single, not open/closing tags. They cannot be nested anyway. The / before the closing >> signs should be added but is not required.
Only groups are nestable. Groups are started using the code <<#. The name after the # sign will be the group name, so a database name can be used. An optional alias can be specified. It is possible to set up a list of possible group names.
Now our list starts:
<<#GROUP1 ?name#null "Invoice">> -- the table will be given the display name "invoice", the logical names remains "GROUP1". After the optional name a condition is expected.
<<:HEADER/>> -- this header will be displayed at the start of the group
Group Header. Fields are possible: <<fieldname +spc/>>
<<:DATA ?"has orders"=null/>> -- this is the data row.
Some data here - under condition that there are no orders. (Note that a field name may used spaces. In this case use " in the field name part as well.)
<<:DATA ?hasorders#null/>> -- this is the data row.
Some data here - under condition there are orders.
<<:FOOTER/>> -- this footer will be displayed at the end of the group
Group Footer. Fields are possible: <<fieldname/>>
<<#/GROUP1>> -- close the group.
This text comes after the group.
To completely control the report creation use the events of TextDynamic and RTF2PDF / TextDynamic Server use two events.
The process is initiated by calling Report.CreateReport. Then the events are triggered to evaluate the fields and the bands. In the end the integrated second editing engine (Memo2) will hold the result text, the created document. It can be saved, printed or exported to PDF.
OnReportState:
This event is triggered before and after a group is started. You use it to move to the next data record or initalize a query. Here we simply use the Count property to abort after 10 rows.
private void wpdllInt1_OnReportState(
object Sender, string Name,
int State, WPDynamic.IWPReportBand Band,
ref bool Abort)
{
if (State==WPDynamic.commands.REP_BeforeProcessGroup)
Abort = Band.Count>10;
else Abort = false;
}
OnFieldGetText:
This event is triggered to fill in field data. It is the same as the one for the regular mail merge. Here we simply print an incremented number.
static int a;
private void wpdllInt1_OnFieldGetText(object Sender, int Editor,
string FieldName, WPDynamic.IWPFieldContents Contents)
{
Contents.StringValue = Convert.ToString(a++);
}