Walkthroughs Copyright © 2004 Business Objects Page 178 4. Right-click within the new Details b section that you have created, point to Insert, and then click Subreport. A gray square appears around the mouse cursor. 5. Drag the gray rectangle into the new Details b section, and then click to release. 6. In the Insert Subreport dialog box, on the Subreport tab, select Create a subreport with the Report Wizard. Note The Insert Subreport dialog box includes other options that allow you to choose an existing report and on-demand subreports. 7. In the New report name field, type "CustomerOrders." 8. Click Report Wizard 9. In the Available Data Sources panel of the Standard Report Creation Wizard window, expand the Create New Connection folder. Note In Visual Studio .NET 2002 or 2003 where Crystal Reports has not been upgraded to the full version, the Create New Connection folder does not exist; the contents are shown at the top level. 10. From the subfolder that opens, expand the ODBC (RDO) folder. The folder contains the database server, which has been configured for the report when the report is created. Note If the server is not displayed, follow the instructions in the previous tutorial to connect to the Xtreme Sample Database. 11. Select the Orders table and click the > symbol to move the Orders table into the Select Tables panel, and then click Next. 12. From the Available Fields panel, select Order ID, Order Date, Ship Date, and Ship Via. 13. Click the > symbol to move these fields into the Fields to Display panel, and then click Finish. 14. In the Insert Subreport dialog box, select the Link tab. 15. In the panel Container Report field(s) to link to, in the list Available fields, expand the Customers table, select Customer ID, and then click the > symbol. 16. In the Customers.Customer ID field link panel that appears, leave the default selections unchanged. These parameter and data selections auto-generate a relationship between the main report and the subreport. 17. Click OK. The new subreport, CustomerOrders, is displayed within the Details b section of the Main report. Note When you add a subreport to the Details section, the subreport displays for every row, which adds a performance cost to your report. If you do not need subreport information with that level of granularity, place the subreport in a Group section rather than a Details section. You are now ready to verify the settings in the subreport. Walkthroughs Copyright © 2004 Business Objects Page 179 To verify the settings in the subreport 1. In the report Details section, double-click on the CustomerOrders subreport to view it. At the bottom of the designer view, navigation buttons appear for both the Main Report and the CustomerOrders subreport. 2. If the Field Explorer is not visible, on the Crystal Reports toolbar, click Toggle Field View. Note Another way to display the Field Explorer is to go to the Crystal Reports menu, and then click Field Explorer. 3. In the Field Explorer, expand Parameter Fields. 4. Verify that the parameter field Pm-Customers.Customer ID was auto-generated when the subreport was linked. 5. On the toolbar, click Select Expert. 6. In the Select Expert dialog box, verify that the criteria Orders.Customer ID is equal to {Pm-Customers.Customer ID} is set, and then click OK. 7. From the File menu, select Save All. You have successfully added a CustomerOrders subreport to the CustomersByCity report. In the next section, you add an OrderDateRange parameter to the subreport. To add an OrderDateRange parameter to the subreport 1. In the Field Explorer, right-click Parameter Fields and select New… 2. In the Create Parameter Field dialog box: Set the Name to "OrderDateRange." Set the Prompting text to "Specify a Date Range of Orders to display." Set the Value type to "Date." Set the Options to one selection only, "Range value(s)." 3. Click OK. 4. On the toolbar, click Select Expert. 5. Click the New tab. 6. In the Choose Field dialog box, expand the Orders table, select Order Date, and then click OK. 7. On the new Orders.OrderDate tab, from the drop down criteria list, select formula: 8. Type the following formula: {Orders.Order Date} in {?OrderDateRange} 9. Click OK. 10. From the File menu, select Save All. You have successfully added an OrderDateRange parameter to the subreport and linked it to the Orders.OrderDate column. In the next section, you add code to address the OrderDateRange parameter within the subreport. Adding the Subreport Parameter Code You are now ready to add the parameter code for the subreport to the code-behind class. To begin, you create a private helper method, SetDateRangeForOrders(). Walkthroughs Copyright © 2004 Business Objects Page 180 To create and code the SetDateRangeForOrders() method 1. Open the Web or Windows Form. 2. From the View menu, click Code. 3. At the top of the class, add two new constants below the existing PARAMETER_FIELD_NAME constant added during the previous tutorial. [Visual Basic] Private Const SUBREPORT_PARAMETER_FIELD_NAME As String = "OrderDateRange" Private Const SUBREPORT_NAME As String = "CustomerOrders" [end] [C#] private const string SUBREPORT_PARAMETER_FIELD_NAME = "OrderDateRange"; private const string SUBREPORT_NAME = "CustomerOrders"; [end] 4. At the bottom of the class, create a new private method named SetDateRangeForOrders() with three parameters: ReportDocument, a string startDate, and a string endDate. [Visual Basic] Private Sub SetDateRangeForOrders(ByVal myReportDocument As ReportDocument, ByVal startDate As String, ByVal endDate As String) End Sub [end] [C#] private void SetDateRangeForOrders(ReportDocument reportDocument, string startDate, string endDate) { } [end] 5. Within this method, declare and instantiate the ParameterRangeValue class. [Visual Basic] Dim myParameterRangeValue As ParameterRangeValue = New ParameterRangeValue() [end] [C#] ParameterRangeValue parameterRangeValue = new ParameterRangeValue(); [end] Note For the ParameterRangeValue class to be accessible, you must include an "Imports" [Visual Basic] or "using" [C#] statement at the top of the code-behind class for the CrystalDecisions.Shared namespace. (You added this declaration in Appendix: Project Setup.) Walkthroughs Copyright © 2004 Business Objects Page 181 6. Set the StartValue property of the ParameterRangeValue instance to the startDate method parameter. [Visual Basic] myParameterRangeValue.StartValue = startDate [end] [C#] parameterRangeValue.StartValue = startDate; [end] Note The StartValue and EndValue properties of the ParameterRangeValue class accept values of type Object. This generic type allows the range value that is passed in to be of many types, including: text, number, date, currency, or time. 7. Set the EndValue property of the ParameterRangeValue instance to the endDate method parameter. [Visual Basic] myParameterRangeValue.EndValue = endDate [end] [C#] parameterRangeValue.EndValue = endDate; [end] 8. Set the lower and upper boundaries to be bound-inclusive. [Visual Basic] myParameterRangeValue.LowerBoundType = RangeBoundType.BoundInclusive myParameterRangeValue.UpperBoundType = RangeBoundType.BoundInclusive [end] [C#] parameterRangeValue.LowerBoundType = RangeBoundType.BoundInclusive; parameterRangeValue.UpperBoundType = RangeBoundType.BoundInclusive; [end] Note For BoundInclusive, the upper and lower range values are included in the range. You are now ready to assign the ParameterRangeValue instance to the parameter of the subreport. 9. Retrieve the ParameterFieldDefinitions class, which comes from the DataDefinition property of the ReportDocument instance Note ParameterFieldDefinitions is an indexed class that contains instances of the ParameterFieldDefinition class. [Visual Basic] Dim myParameterFieldDefinitions As ParameterFieldDefinitions = myReportDocument.DataDefinition.ParameterFields [end] [C#] Walkthroughs Copyright © 2004 Business Objects Page 182 ParameterFieldDefinitions parameterFieldDefinitions = reportDocument.DataDefinition.ParameterFields; [end] 10. Retrieve the ParameterFieldDefinition instance from the ParameterFieldDefinitions indexed class, which is based on two indexed values: the subreport parameter field name and the subreport name. Pass in the two constant values that you declared at the top of the class. [Visual Basic] Dim myParameterFieldDefinition As ParameterFieldDefinition = myParameterFieldDefinitions(SUBREPORT_PARAMETER_FIELD_NAME, SUBREPORT_NAME) [end] [C#] ParameterFieldDefinition parameterFieldDefinition = parameterFieldDefinitions[SUBREPORT_PARAMETER_FIELD_NAME, SUBREPORT_NAME]; [end] 11. Call the Clear() method of the CurrentValues property of the ParameterFieldDefinition instance to remove any existing values from the CurrentValues property. [Visual Basic] myParameterFieldDefinition.CurrentValues.Clear() [end] [C#] parameterFieldDefinition.CurrentValues.Clear(); [end] 12. Add the ParameterRangeValue instance, which you created earlier, to the CurrentValues property of the ParameterFieldDefinition instance. [Visual Basic] myParameterFieldDefinition.CurrentValues.Add(myParameterRangeValue) [end] [C#] parameterFieldDefinition.CurrentValues.Add(parameterRangeValue); [end] 13. Call the ApplyCurrentValues() method, passing into it the CurrentValues property of the ParameterFieldDefinition instance. [Visual Basic] myParameterFieldDefinition.ApplyCurrentValues(myParameterFieldDefinitio n.CurrentValues) [end] [C#] Walkthroughs Copyright © 2004 Business Objects Page 183 parameterFieldDefinition.ApplyCurrentValues(parameterFieldDefinition.Cu rrentValues); [end] This step procedure has set start and end date values into a ParameterRangeValue instance and passed those values to the OrderDateRange parameter in the CustomerOrders subreport. Adding TextBox Controls to Hold Range Parameter Values In this section, you add two TextBox controls to provide start and end date values at runtime to the OrderDateRange range parameter in the CustomerOrders subreport. Note If you implement this tutorial in a Web Site, the persistence of date values that users enter into the text boxes are maintained by ViewState. To create and configure a redisplay Button on the form 1. Open the Web or Windows form. 2. From the View menu, click Designer. 3. If you are developing a Web Site, do the following: a) Click between the ListBox control and the Button control. b) Press ENTER three times to create two rows between the ListBox control and the Button control. c) In the first row created below the ListBox control, type "Order Start Date." d) In the second row created below the ListBox control, type "Order End Date." 4. If you are developing a Windows project, do the following: a) From the Toolbox, drag two Label controls to the right of the ListBox control. Place one label above the other, with both of them above the Button control. b) Select the first Label control. From the Properties window, set the Text property to "Order Start Date." c) Select the second Label control. From the Properties window, set the Text property to "Order End Date." The remaining steps apply to both Web and Windows projects. 5. From the Toolbox, drag a TextBox control to the right of "Order Start Date." 6. Click on the TextBox control to select it. 7. From the Properties window, set the ID (or Name) to "orderStartDate." 8. From the Toolbox, drag a TextBox control to the right of "Order End Date." 9. Click on the TextBox control to select it. 10. From the Properties window, set the ID (or Name) to "orderEndDate." 11. From the File menu, select Save All. Modifying Methods to Call the Subreport You must now modify the ConfigureCrystalReports() method and the redisplay_Click() event method to receive information from these TextBox controls Walkthroughs Copyright © 2004 Business Objects Page 184 and apply them to the SetDateRangeForOrders() method, to have the parameter information processed for subreports. In the previous tutorial, Reading and Setting Discrete Parameters, you designed these methods in two different ways, depending on whether you included Session persistence. Note Windows projects do not require Session persistence. Web Sites typically require Session persistence. Choose from one (but not both) of the step procedures below. Either modify the methods that exclude Session persistence, or modify the methods that include Session persistence: Modifying Methods that Exclude Session Persistence. Modifying Methods that Include Session Persistence. Modifying Methods that Exclude Session Persistence If you created the previous tutorial Reading and Setting Discrete Parameters and excluded Session persistence, work through the following procedures. If you want to include Session persistence, see Modifying the Methods that Include Session Persistence. To modify the ConfigureCrystalReports() method that excludes Session persistence 1. In the ConfigureCrystalReports() method, create a couple of line breaks in the code after the lines which assign "Paris" and "Tokyo" as ArrayList variables. 2. Within the line breaks, declare and set hard-coded values for two string variables, startDate and endDate. [Visual Basic] Dim startDate As String = "8/1/1997" Dim endDate As String = "8/31/1997" [end] [C#] string startDate = "8/1/1997"; string endDate = "8/31/1997"; [end] 3. Create a couple of line breaks in the code above the line that binds the report to the CrystalReportViewer control. 4. Within the line breaks, enter a call to the SetDateRangeForOrders() method and pass in the CustomersByCity report and the startDate and endDate variables. [Visual Basic] SetDateRangeForOrders(customersByCityReport, startDate, endDate) [end] [C#] SetDateRangeForOrders(customersByCityReport, startDate, endDate); [end] This is followed by the original code that binds the report to the CrystalReportViewer control. Walkthroughs Copyright © 2004 Business Objects Page 186 [C#] string startDate; string endDate; [end] 3. Within the Not IsPostBack conditional block, enter default values for the startDate and endDate variables. [Visual Basic] startDate = "8/1/1997" endDate = "8/31/1997" [end] [C#] startDate = "8/1/1997"; endDate = "8/31/1997"; [end] 4. Within the Not IsPostBack conditional block, assign the startDate and endDate variables into Session. [Visual Basic] Session("startDate") = startDate Session("endDate") = endDate [end] [C#] Session["startDate"] = startDate; Session["endDate"] = endDate; [end] 5. Within the Else block, after the ArrayList instance is retrieved from Session, retrieve the startDate and endDate variables from Session. [Visual Basic] startDate = Session("startDate").ToString() endDate = Session("endDate").ToString() [end] [C#] startDate = Session["startDate"].ToString(); endDate = Session["endDate"].ToString(); [end] With that approach, you reach the end of the block with the date variables assigned in either case. This follows parallel logic to the assignment of the ArrayList variable that you configured in the previous tutorial. 6. Create a couple of line breaks in the code above the line that binds the report to the CrystalReportViewer control. 7. Within these new line breaks, enter a call to the SetDateRangeForOrders() method and pass in the CustomersByCity report and the startDate and endDate variables. Walkthroughs Copyright © 2004 Business Objects Page 187 [Visual Basic] SetDateRangeForOrders(customersByCityReport, startDate, endDate) [end] [C#] SetDateRangeForOrders(customersByCityReport, startDate, endDate); [end] This is followed by the original code that binds the report to the CrystalReportViewer control. 8. From the File menu, select Save All. Next, you modify the redisplay_Click event method. To modify the redisplay_Click() method that includes Session persistence 1. In the redisplay_Click() event method, create a couple of line breaks in the code after the line that assigns the ArrayList instance to Session. 2. Within the line breaks, assign the Text property of the orderStartDate TextBox and the orderEndDate TextBox to Session variables. [Visual Basic] Session("startDate") = orderStartDate.Text Session("endDate") = orderEndDate.Text [end] [C#] Session["startDate"] = orderStartDate.Text; Session["endDate"] = orderEndDate.Text; [end] 3. From the File menu, select Save All. Those startDate and endDate Session values are now retrieved and applied when the ConfigureCrystalReports() method is called. You are now ready to build and run the project, to verify that the TextBox values are resetting the range parameter in the subreport. Testing the Setting of the Subreport Parameter You are now ready to test the setting of the subreport parameter from the TextBox values. To test the setting of the subreport parameter 1. From the Build menu, select Build Solution. 2. If you have any build errors, go ahead and fix them now. 3. From the Debug menu, click Start. 4. In the ListBox control, CTRL-click to select at least four different cities in the list. 5. In the startDate TextBox control, enter "1/1/1997." 6. In the endDate TextBox control, enter "12/31/1997." 7. Click the Redisplay Report button. Walkthroughs Copyright © 2004 Business Objects Page 188 The page reloads and displays the customer records for customers who live in the list of cities that have just been selected, as well as a subreport that displays orders for the date range specified above. 8. In the CrystalReportViewer control, increase the Zoom level to 125%. The page reloads at 125% zoom. The values that are selected for both cities and order date range are persisted. 9. Return to Visual Studio and click Stop to exit from debug mode. Conclusion You have successfully modified your tutorial project to use a report containing a subreport, and set an order date range to the range parameter that is created in the subreport. To learn about reading and setting parameters in a subreport with enhanced API features, continue to Addendum: Enhancements to the Range Parameters Code for Subreports. Addendum: Enhancements to the Range Parameters Code for Subreports If you have installed Visual Studio 2005 or Crystal Reports Developer you have access to the enhanced API that sets the range parameters in the Crystal report. In the previous procedures, you learned how to create the SetDateRangeForOrders() helper method that uses the ParameterFieldDefinitions and ParameterFieldDefinition classes. In this tutorial, you must remove the lines of code that uses the ParameterFieldDefinitions and ParameterFieldDefinition classes. Then, you learn how to use the ParameterFields and ParameterField classes of the enhanced Crystal Reports Developer API to code the SetDateRangeForOrders() method. Note The enhanced API includes the SetParameterValue(string parameterFieldName, object value, string subreport) method for subreports with discrete parameter fields. Therefore, SetParameterValue() cannot be used in this tutorial because the subreport has a range parameter. Prerequisites: You must create a project based on the instructions in Reading and Setting Parameters with a Subreport. To use the enhanced Crystal Reports API for Subreports with Range Parameters 1. Open the completed project for this tutorial. 2. Open the Web or Windows Form. 3. From the View menu, click Code. 4. Within the SetDateRangeForOrders() method, delete the lines of code that use the ParameterFieldDefinitions or ParameterFieldDefinition classes. Delete the following lines of code: [Visual Basic] Dim myParameterFieldDefinitions As ParameterFieldDefinitions = myReportDocument.DataDefinition.ParameterFields [...]... ExportFormatType.NoFormat Case ExportFormatType.CrystalReport Case ExportFormatType.RichText Case ExportFormatType.WordForWindows Case ExportFormatType.Excel Case ExportFormatType.PortableDocFormat Case ExportFormatType.HTML32 Case ExportFormatType.HTML40 End Select [end] [C#] switch ((ExportFormatType)exportTypesList.SelectedIndex) { case ExportFormatType.NoFormat: break; case ExportFormatType.CrystalReport:... instantiate the HTMLFormatOptions class with the variable name "html40FormatOptions." [Visual Basic] Dim html40FormatOptions As HTMLFormatOptions = New HTMLFormatOptions() [end] [C#] HTMLFormatOptions html40FormatOptions = new HTMLFormatOptions(); [end] 6 Set the HTMLBaseFolderName property of the html40FormatOptions instance to the exportPath string and the name "Html40Folder." [Visual Basic] html40FormatOptions.HTMLBaseFolderName... Walkthroughs Crystal Reports For Visual Studio 2005 ReportDocument Object Model Tutorial: Exporting to Multiple Formats Copyright © 20 04 Business Objects Page 191 Walkthroughs Exporting to Multiple Formats Introduction In this tutorial, you learn how to export the report programmatically Crystal Reports can export reports to the following formats: Adobe Acrobat (.pdf) Crystal Reports (.rpt) Rich Text Format... the html40FormatOptions instance to 1 [Visual Basic] html40FormatOptions.FirstPageNumber = 1 [end] [C#] html40FormatOptions.FirstPageNumber = 1; [end] 11 Set the LastPageNumber property of the html40FormatOptions instance 3 [Visual Basic] html40FormatOptions.LastPageNumber = 3 [end] [C#] html40FormatOptions.LastPageNumber = 3; [end] 12 Finally, assign the html40FormatOptions instance to the FormatOptions... = exportPath & "Html40Folder" [end] [C#] html40FormatOptions.HTMLBaseFolderName = exportPath + "Html40Folder"; [end] Copyright © 20 04 Business Objects Page 209 Walkthroughs 7 Set the HTMLFileName property of the html40FormatOptions instance to the name "html40.html." [Visual Basic] html40FormatOptions.HTMLFileName = "html40.html" [end] [C#] html40FormatOptions.HTMLFileName = "html40.html"; [end] 8 Set... value [Visual Basic] Public Sub ConfigureExportToHtml40() End Sub [end] [C#] private void ConfigureExportToHtml40() { } [end] 4 Within the method, set the ExportFormatType property of the ExportOptions instance to the ExportFormatType enum selection HTML40 [Visual Basic] myExportOptions.ExportFormatType = ExportFormatType.HTML40 [end] [C#] exportOptions.ExportFormatType = ExportFormatType.HTML40; [end]... HTMLEnableSeparatedPage property of the html40FormatOptions instance to "True." [Visual Basic] html40FormatOptions.HTMLEnableSeparatedPages = True [end] [C#] html40FormatOptions.HTMLEnableSeparatedPages = true; [end] 9 Set the HTMLHasPageNavigator property of the html40FormatOptions instance to be "True." [Visual Basic] html40FormatOptions.HTMLHasPageNavigator = True [end] [C#] html40FormatOptions.HTMLHasPageNavigator... [C#] private void ConfigureExportToPdf() { } [end] 4 Within the method, set the ExportFormatType property of the ExportOptions instance to the ExportFormatType enum selection PortableDocFormat [Visual Basic] myExportOptions.ExportFormatType = ExportFormatType.PortableDocFormat [end] [C#] exportOptions.ExportFormatType = ExportFormatType.PortableDocFormat; [end] 5 Set the DiskFileName property of the... ConfigureExportToHtml40() [end] [C#] ConfigureExportToHtml40(); [end] If you are creating a project in Visual Studio 2005 or Crystal Reports Developer you must complete the procedures in Creating Methods for the New Exporting Formats, before you continue to Calling the Methods to Perform the Export Copyright © 20 04 Business Objects Page 212 Walkthroughs 4 Within the "Select Case" [Visual Basic] or "switch"... Public Sub ConfigureExportToDoc() End Sub [end] [C#] private void ConfigureExportToDoc() { } [end] 4 Within the method, set the ExportFormatType property of the ExportOptions instance to the ExportFormatType enum selection WordForWindows [Visual Basic] myExportOptions.ExportFormatType = ExportFormatType.WordForWindows [end] [C#] exportOptions.ExportFormatType = ExportFormatType.WordForWindows; [end] 5 Set . 20 04 Business Objects Page 191 Crystal Reports For Visual Studio 2005 ReportDocument Object Model Tutorial: Exporting to Multiple Formats Walkthroughs Copyright © 20 04. the Range Parameters Code for Subreports. Addendum: Enhancements to the Range Parameters Code for Subreports If you have installed Visual Studio 2005 or Crystal Reports Developer you have. ExportFormatType.NoFormat Case ExportFormatType.CrystalReport Case ExportFormatType.RichText Case ExportFormatType.WordForWindows Case ExportFormatType.Excel Case ExportFormatType.PortableDocFormat