You are not restricted to using VBScript to evaluate expressions in calculated fields. You can also specify scripts that are triggered when the report is rendered, and you can use those to change the formatting of the report.

These scripts are contained in event properties. An event property is similar to a Visual Basic event handler, except that the scripts are executed in the scope of the report rather than in the scope of the application that is displaying the report. For example, you could use an event property to set a field's Font and ForeColor properties depending on its value. This behavior would then be a part of the report itself, and would be preserved regardless of the application used to render it.

Of course, traditional events are also available, and you should use them to implement behavior that affects the application rather than the report. For example, you could write a handler for the OnPage event to update a page count in your application, regardless of which particular report is being rendered.

The table below lists the event properties that are available, and typical uses for them:

The following examples illustrate typical uses for these properties.

Format a Field According to its Value

This is probably the most common use for the OnPrint property. For example, imagine you have a report with a field called "ExtendedPriceCtl", which displays the total value of sales of a particular product. The report is sorted by product name, and you would like to add emphasis to products that sell more than a certain amount. The following code does just that:

Dim sEvent$

sEvent = "If ExtendedPriceCtl > 20000 Then " & vbCrLf &_

    "  ExtendedPriceCtl.FontBold = True" & vbCrLf &_

    "  ExtendedPriceCtl.ForeColor = RGB(150,0,0) " & vbCrLf &_

    "Else" & vbCrLf &_

    "  ExtendedPriceCtl.FontBold = False" & vbCrLf &_

    "  ExtendedPriceCtl.ForeColor = 0" & vbCrLf &_

    "End If"

vsr.Sections("ProductGroupHeader").OnPrint = sEvent

The Visual Basic code builds a string containing the VBScript event handler, and then assigns it to the section's OnPrint property. When using the VSReport8 Designer you can type the script code directly into the Event Editor window instead of writing the code above.

The control executes the VBScript code whenever the section is about to be printed. The script gets the value of the field and sets the field's FontBold and ForeColor properties according to the value. If the value exceeds $20,000, the field becomes bold and red.

Here's what the report looks like:

Show or Hide a Field Depending on a Value

Instead of changing the field format to highlight its contents, you could set another field's Visible property to True or False to create special effects. For example, if we created a new field called "BoxCtl" and formatted it to look like a green rectangle, and then we could change the script as follows:

Dim sEvent$

sEvent = "If ExtendedPriceCtl > 20000 Then " & vbCrLf &_

    "  ExtendedPriceCtl.FontBold = True" & vbCrLf &_

    "  ExtendedPriceCtl.ForeColor = RGB(150,0,0) " & vbCrLf &_

    "  BoxCtl.Visible = True " & vbCrLf &_

    "Else" & vbCrLf &_

    "  ExtendedPriceCtl.FontBold = False" & vbCrLf &_

    "  ExtendedPriceCtl.ForeColor = 0" & vbCrLf &_

    "  BoxCtl.Visible = False " & vbCrLf &_

    "End If"

vsr.Sections("ProductGroupHeader").OnPrint = sEvent

Prompt Users for Parameters

Instead of using a fixed value of $20,000 as the threshold for highlighting fields, you could have the report prompt the user for a value.

To get the threshold value from the user, you would change the report's RecordSource property to use a parameter query. (For details on how to build parameter queries, see Advanced Topics.)

vsr.DataSource.RecordSource = _

  "PARAMETERS [Sales Threshold] Currency 20000; " & _

  "[Order Details Extended]"

This setting causes the control to prompt the user for a Sales Threshold value, which gets stored in a global VBScript variable where your events can use it. The default value for the variable is specified as $20,000.

To use the value specified by the user, the script should be changed as follows:

Dim sEvent$

sEvent = "If ExtendedPriceCtl > [Sales Threshold] Then " & vbCrLf &_

    "  ExtendedPriceCtl.FontBold = True" & vbCrLf &_

    "  ExtendedPriceCtl.ForeColor = RGB(150,0,0) " & vbCrLf &_

    "  BoxCtl.Visible = True " & vbCrLf &_

    "Else" & vbCrLf &_

    "  ExtendedPriceCtl.FontBold = False" & vbCrLf &_

    "  ExtendedPriceCtl.ForeColor = 0" & vbCrLf &_

    "  BoxCtl.Visible = False " & vbCrLf &_

    "End If"

vsr.Sections("ProductGroupHeader").OnPrint = sEvent

Reset the Page Counter

The Page variable is created and automatically updated by the control. It is useful for adding page numbers to page headers or footers.

In some cases, you may want to reset the page counter when a group starts. For example, in a report that groups records by country and has a calculated page footer field with the expression:

vsr.Fields("PageFooter").Text = "[Country] & "" "" & [Page]"

It would be good to reset the Page variable for each new country. To do this, assign the following script to the country group header section:

vsr.Sections("CountryGroupHeader").OnPrint = "Page = 1"

Change a Field's Dimensions to Create a Bar Chart

We saved the most sophisticated example for last. Instead of showing a field's value as text, you can change its dimensions to create a chart. (The example described below is included in the NWind.xml sample file that ships with VSReport8; it is called "Sales Chart".)

To create a chart, the first thing you need to do is find out the scale, that is, the measurements that will be used to the maximum and minimum values. The "Sales Chart" report has a field designed to do this. It is a report footer field called SaleAmountMaxFld that has the size of the longest bar we want to appear on the chart, and holds the following expression:

SaleAmountMaxFld.Text = "Max([SaleAmount])"

To draw the actual bars, the report has a detail field called BarFld that is formatted to look like a solid box. The detail section has the following script assigned to its OnPrint event:

vsr.Sections(vsrDetail).OnPrint = & _

  "BarFld.Width = SaleAmountMaxFld.Width * (SaleAmountFld / SaleAmountMaxFld)"

This expression calculates the width of the bar based on the width and value of the reference field and on the value of the SaleAmountFld for the current record.

The result is a report that looks like this:

Copyright (c) GrapeCity, inc. All rights reserved.