Handle Events via Scripts

Reporting includes a scripting feature to handle the events of controls, bands, or reports themselves.

Overview

Scripts can be inserted into a report and executed when the report is previewed, printed or exported. Script commands must be placed within the event handlers of the report objects. When the corresponding event occurs (for example, a mouse click), the script code runs.

Generally scripts are used for data-aware report formatting. Although Reporting can be used to perform many tasks without any scripting, sometimes scripts are required to achieve more specific results. The report layout can be fully customized using scripts.

Scripting 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 control type. For example, the events for a Label control are:

When a script is selected from a drop-down list for any event, the Script Editor displays.

Alternatively, on the Report Designer tab, in the Scripts group, click Scripts to display the Script Editor.

If there is no script defined for the event, the Script Editor 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 into the Script Editor.

Click Validate to validate the script code. Errors are displayed in the Script Errors window. Double click on a script error to navigate to the error in the script code.

If there are errors in the script, an error message displays when the report is previewed.

The scripts are saved along with the report layout to a file.

Scripting Language

Report scripts can 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. The scripting language is specified via the Script Language property of the Report object. C# is the default language.

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 and methods. 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: Assemblies do not usually need including because most standard assemblies that are required in scripts are already referenced by Reporting.

Example: Custom Summary

In the example, the total number of product unit packs in a group is displayed.

The steps are similar to the functionality described in Add Report Totals, except that for the summary field, the Function property must be set to Custom.

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

Handle the events in the following way:

Click the Print Preview tab to display the result.

Refer to Conditionally Modify Control Display, Conditionally Modify Label Text, Conditionally Hide Bands and Add Report Totals for further information.