Scripts allow you to specify code to execute for specific events during a report run. This can be used to display something different than the actual value of a field, to perform custom summarization, and other tasks. Report Writer uses scripts for report linking to tell the Preview window when a subreport should be displayed and what to do when the user clicks a hyperlinked field. Writing scripts requires knowledge of the C#, Visual Basic .NET, or JScript .NET languages so it's intended for programmers only.

All the scripts for a report must be written in the same language; this language is specified in the Script Language report property. If the scripts need to reference external assemblies, set the Script References property to the full paths of the assemblies or only the file names for assemblies in the GAC.

To edit the scripts for a report, click the Scripts button in the Report Designer ribbon.

There are four sections to the scripts area:

• The drop-down list at the upper left lists the objects in the report.

• The drop-down list beside the objects displays the events for the selected object. Choosing one from the list either creates a script to handle that event or moves the editor to that script if it already exists.

• The Validate button at the upper right examines the script code and displays any errors it finds in the Script Errors tab at the bottom of the Report Designer Layout window.

• The editor area shows the script code. This is a typical text editor but uses color coding to help with syntax.

The scripts for a report are organized like a typical .NET class but without the "class" definition. There may be using statements, fields, properties, and methods. Event handler methods are usually named ObjectName_Event, where ObjectName is the name of the object and Event is the event being handled for that object.

If you created a script by selecting an event name from the list at the top, the script is automatically associated with that event for the object. However, you can also do that manually by expanding the Scripts property for an object and choosing the desired handler from the drop-down list for a specific event.

Here's an example where a script is useful: custom summarization. Suppose you want to show the total number of boxes of product units on order, where there are 15 items per box. Add a label to a group footer band of the report and set its data binding to the field containing the units on order. In the Property Grid, set the Function sub-property of its Summary property to "Custom," the Format String sub-property to "Total boxes: {0}," and the Running sub-property to "Group." Expand the label's Script property and choose "New" for the Summary Reset, Summary Row Changed, and Summary Get Result events. This creates three scripts. Use code like the following for these scripts:

// Declare a summary and a box.
double totalUnits = 0;
double box = 15;

private void xrLabel1_SummaryReset(object sender,
    EventArgs e) {
    // Reset the result each time a group is printed.
    totalUnits = 0;
}

private void xrLabel1_SummaryRowChanged(object sender,
    EventArgs e) {
    // Calculate a summary.
    totalUnits += Convert.ToDouble(
        GetCurrentColumnValue("UnitsOnOrder"));
}

private void xrLabel1_SummaryGetResult(object sender,
    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 / box);
    e.Handled = true;
}

The SummaryReset method resets the total number of units to 0 when a group breaks. SummaryRowChanged fires on every record, so it adds the current value of the UnitsOnOrder field to the total. SummaryGetResult is called when the summary value is needed (that is, when the label is about to be printed); it calculates the number of boxes by dividing the total number of units by the units per box.