The Report Designer offers you a scripting feature to handle the events of report controls, report bands, or a reportitself. This document describes the basic principles of scripting.
Overview
Scripting allows you to insert scriptsinto a report, and execute them when the report is previewed, printed or exported. Script commands should be placed within the event handlersof the report objects. When the corresponding event occurs (e.g. a mouse click), the script code runs.
Generally scripts are used for data-aware report formatting. Though Report Designer allows you to perform such tasks without any scripting ( Conditionally Change a Control's Appearance, Conditionally Change a Label's Textand Conditionally Hide Bands), sometimes it may be required to involve scripts, e.g. to achieve more specific results. The report's layout can be fully customized with advanced use of scripting.
Also, scripting is the only way to calculate custom summaries.
Every report object has a set of events that can be handled by modifying the corresponding scripts. This set depends on a particular elements type. For example, the Labelcontrol's events are shown in the following image.
When you click the ellipsis button for any event (the Before Printis the most popular), the Script Editorappears.
If there is no script defined for this event, the window contains a script template in the language specified via the Script Languageproperty of the report ( C#, Visual Basicor J#).
Insert the script code with the help of this simple editor. Since there are no syntax checks or a debugger, you have to be accurate. Use already tested examples to simplify the task. When the code has mistakes, you'll get an error message on previewing the report (for more information, refer to Warnings and Error Messages in Print Preview).
To restore the default script, in the Script Editordialog, click the Default Scriptbutton. This will eliminate all the changes you made to scripts.
The scripts are saved along with the report layout to a file (for details on this, refer to Back Up the Current Layout Before Modifying It).
Specifics
-
Scripting language
The report scripts may be written in one of the following languages that the .NET framework supports - C#, Visual Basic and J#. Since J# is not installed with the framework installation by default, make sure it is present before writing code in it. The scripting language is specified via the Script Languageproperty of the Reportobject. It is set to the C#language by default.
-
Scripting scope
Script execution is performed in the following way:
The report engine generates a temporary class in memory. The names of the variables are defined by the Nameproperties of the controls and objects they represent. When the script is preprocessed, its namespace directives are cut from the script code and added to the namespace where the temporary class is defined.
After preprocessing, all scripts are placed in the code of the temporary class. Then, the resulting class is compiled in memory, and its methods are called when events occur.
Scripting offers many advantages: you can declare classes (they will become inner classes), variables, methods, etc. A variable declared in one script is accessible in another script, because it is, in fact, a variable of the temporary class.
-
Reference External Assemblies
The Script Referencesproperty of the Reportobject specifies the full paths (including the file names) to the assemblies that are referenced in the scripts used in a report. These paths should be specified for all the assemblies that are included in scripts via using(C#), Imports(Visual Basic) or import(J#) directives.
Note Usually, you don't need include any assembles, because most standard assemblies that you may require in scripts are already referenced by the Report Designer.
Example: Custom Summary
In this example, we will display the total number of product unit packs in a group.
To perform this, execute steps similar to the ones described in Add Totals to a Report, except that for the summary field, you should set the Functionproperty to Custom.
Then, the additional events are added to the label's Scriptsproperty.
Handle these events in the following way:
C# | Copy Code |
---|---|
// Declare a summary and a pack. double totalUnits = 0; double pack = 15; private void OnSummaryReset( object sender, System.EventArgs e) { // Reset the result each time a group is printed. totalUnits = 0; } private void OnSummaryRowChanged( object sender, System.EventArgs e) { // Calculate a summary. totalUnits += Convert.ToDouble(GetCurrentColumnValue( "UnitsOnOrder")); } private void OnSummaryGetResult( object sender, DevExpress.XtraReports.UI.SummaryGetResultEventArgs e) { // Round the result, so that a pack will be taken into account // even if it contains only one unit. e.Result = Math.Ceiling(totalUnits / pack); e.Handled = true; } |
Visual Basic | Copy Code |
---|---|
' Declare a summary and a pack. Private totalUnits As Double = 0 Private pack As Double = 15 Private Sub OnSummaryReset( ByVal sender As Object, ByVal e As System.EventArgs) ' Reset the result each time a group is printed. totalUnits = 0 End Sub Private Sub OnSummaryRowChanged( ByVal sender As Object, ByVal e As System.EventArgs) ' Calculate a summary. totalUnits += Convert.ToDouble(GetCurrentColumnValue( "UnitsOnOrder")) End Sub Private Sub OnSummaryGetResult( ByVal sender As Object, _ ByVal e As DevExpress.XtraReports.UI.SummaryGetResultEventArgs) ' Round the result, so that a pack will be taken into account ' even if it contains only one unit. e.Result = Math.Ceiling(totalUnits / pack) e.Handled = True End Sub |
Finally, switch to the Preview Tab, and view the result.