Handle Events via Scripts

Reporting User Guide

Create Reports : Miscellaneous : Handle Events via Scripts

Reporting includes a scripting feature to handle the events of report controls, report bands, or reports themselves. The basic principles of scripting are described in this topic.

Overview

Scripting enables the user to insert scripts into a report, and execute them when the report is previewed, printed or exported. Script commands should be placed within the event handlers of 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 Reporting enables users to perform such tasks without any scripting (see Conditionally Change a Control's Appearance, Conditionally Change a Label's Text and Conditionally Hide Bands), sometimes it may be required to use scripts, for example to achieve more specific results. The report's layout can be fully customised using of scripting.

Scripting also is the only way to calculate custom summaries.

Every report object has a set of events that can result in a script being run. The set of events depends on a particular element type. For example, the Label control's events are shown in the following image:

When the ellipsis is clicked for any event, the Script Editor window is displayed:

If there is no script defined for this event, the window contains a script template in the language specified by the Script Language property of the report (C#, Visual Basic or J#).

Insert the script code with the help of this simple editor. Since there are no syntax checks or a debugger, the user must ensure that the entered script is correct. If there are errors in the script, an error message will display on previewing the report.

To restore the default script, in the Script Editor window, click Default Script which will eliminate all the changes made to scripts.

The scripts are saved along with the report layout to a file (refer to Back up the Current Layout before Modification for further information).

Specifics

Scripting Language

The report scripts may be written in 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 has been installed before writing code in it. The scripting language is specified via the Script Language property of the Report object. 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 Name properties of the controls and objects they represent. When the script is pre-processed, its namespace directives are taken from the script code and added to the namespace where the temporary class is defined.

•

After pre-processing, all scripts are placed in the code of the temporary class. The resulting class is then compiled in memory, and its methods are called when events occur.

•

Scripting offers many advantages: to 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 References property of the Report object 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:

Assembles do not usually need including, because most standard assemblies that may be required in scripts are already referenced by Reporting.

Example: Custom Summary

In this example, the total number of product unit packs in a group will be displayed.

Execute steps similar to those described in Add Totals to a Report, except that for the summary field, the Function property should be set to Custom.

The additional events must then be added to the label's Scripts property.

Handle these events in the following way:

Finally, switch to the Preview tab to view the result.