Basic Customization
No matter what type of runtime customization you want to perform, there are three basic steps that you need to know. Customizing reports always starts with the same premise: declare and instantiate a ReportDocument object modify its properties, and print or preview it.
Chapter 3 gave a thorough explanation of the different ways to integrate reports into an application (Strongly-Type versus Untyped). If you need a refresher, refer to the sections on binding reports for a discussion of the pros and cons of the different methods of binding reports.
The code that implements runtime customization is the same for both WinForms development and ASP.NET applications. The ReportDocument class is used with both types of applications. ASP.NET will only be mentioned for special circumstances.
Step 1: Declare and instantiate the ReportDocument object variable.
An object variable can either instatiate the report class directly (Strongly-Typed reports) or it can instantiate the ReportDocument class and then load the report into memory (Untyped reports). Since runtime customization requires the use of Strongly-Typed reports, the examples in this chapter will use this binding method.
In the examples throughout this chapter and the rest of the book, the report class being referenced is called CrystalReport1. This is the default report name that is given by the report wizard. When you implement the sample code in your applications, replace the name CrystalReport1 with the class name of the report you want to print. All the code samples are generic and will work with every report.
‘Declare and instantiate an object variable of the report class
Dim MyReport As New CrystalReport1
Step 2: Modify the properties of the report object.
After instantiating the report variable, all the properties and methods of the ReportDocument object are available to you. Set the properties that need to be modified. The different properties of the report object are explained throughout all the chapters in Part II of this book.
In this example, the record selection formula is changed. The report variable MyReport (from Step 1) is used to get a reference to the DataDefinition object and change its RecordSelectionFormula property.
MyReport.DataDefinition.RecordSelectionFormula = "{Orders.Order Date}>#01/01/2004#"
The above line of code is very simplistic for purposes of illustrating how to change a property of the ReportDocument class. Real applications aren’t so simple and you can save yourself effort by using the same code in different projects. A lot of times you will find yourself taking a specific piece of code and rewriting it so that it can be generic enough to be used by multiple applications or put into a reporting library. In many of the examples in this book, I do this by writing a method that gets passed the report object and any necessary parameters. The method modifies the properties of the report object that was passed to it and exits. In these examples, the method’s code will be shown but not the code that calls it. I won’t repeat the code that declares and initializes the report variable and previews it. It is assumed that you know that these methods should be called after the report object is declared and initialized, but before previewing the report. If you need a refresher, you can refer back to this chapter.
Step 3: Print or preview the report.
To preview the report, pass the report variable to the viewer control. To print the report, call the PrintToPrinter() method of the report variable. To be consistent, my examples always preview the report. Thus, the sample code will assign the report variable to the viewer control.
Those three steps are always used for performing runtime customization. The next question you might be asking yourself is where to put the code. You can put this code anywhere in the form. If you want to load the form immediately and customize the report, put it in the Load() event. There are time that you are going to call this code after the user has entered various data that specifies how the report should be customized. If that’s the case, put the code in response to the click event of an OK button that confirms they are finished inputting data. The following code sample shows you a complete code listing and it demonstrates where to put the code for calling a generic method to modify report properties.
Private Sub Form1_Load(ByVal sender As System.Object, _
ByVal e As System.EventArgs) Handles MyBase.Load
Dim MyReport As New CrystalReport1
‘Call all report modification code here.
‘As mentioned in Step 2 above, this can be a method that is passed the report variable.
‘For illustration purposes, I'm calling a generic method that changes
‘the report title. The code for ModifyTitle() isn't shown here.
ModifyTitle(MyReport, "Runtime Demo")
CrystalReportViewer1.ReportSource = MyReport
End Sub
If you are writing an ASP.NET application, this code can be put in the Page_Load() event. See Chapter 3 for a more information about writing ASP.NET applications.
All report customization must be done prior to previewing or printing the report. No changes are allowed once the report is generated. For example, you can’t use .NET to change the way a field is formatted depending upon the current group value. Making dynamic report changes while the report is running requires writing formulas and using conditional formatting (discussed in Chapters 7, 8, and 9).
