ComponentOne

ReportViewer for ASP.NET AJAX

Copyright 2011 ComponentOne LLC. All rights reserved.

Corporate Headquarters ComponentOne LLC 201 South Highland Avenue 3rd Floor Pittsburgh, PA 15206 USA Internet: Web site: Sales info@ComponentOne.com http://www.componentone.com

E-mail: sales@componentone.com Telephone: 1.800.858.2739 or 1.412.681.4343 (Pittsburgh, PA USA Office)

Trademarks The ComponentOne product name is a trademark and ComponentOne is a registered trademark of ComponentOne LLC. All other trademarks used herein are the properties of their respective owners. Warranty ComponentOne warrants that the original CD (or diskettes) are free from defects in material and workmanship, assuming normal use, for a period of 90 days from the date of purchase. If a defect occurs during this time, you may return the defective CD (or disk) to ComponentOne, along with a dated proof of purchase, and ComponentOne will replace it at no charge. After 90 days, you can obtain a replacement for a defective CD (or disk) by sending it and a check for $25 (to cover postage and handling) to ComponentOne. Except for the express warranty of the original CD (or disks) set forth here, ComponentOne makes no other warranties, express or implied. Every attempt has been made to ensure that the information contained in this manual is correct as of the time it was written. We are not responsible for any errors or omissions. ComponentOnes liability is limited to the amount you paid for the product. ComponentOne is not liable for any special, consequential, or other damages for any reason. Copying and Distribution While you are welcome to make backup copies of the software for your own use and protection, you are not permitted to make copies for the use of anyone else. We put a lot of time and effort into creating this product, and we appreciate your support in seeing that it is used by licensed users only.

This manual was produced using ComponentOne Doc-To-Help.

Table of Contents
ComponentOne ReportViewer for ASP.NET AJAX Overview ........................................................................1 What's New in ReportViewer for ASP.NET AJAX ...................................................................................... 1 Revision History............................................................................................................................................. 1 What's New in 2011 v1..................................................................................................................... 1 What's New in 2010 v3..................................................................................................................... 2 Installing ComponentOne ReportViewer for ASP.NET AJAX .................................................................... 2 ReportViewer for ASP.NET AJAX Setup Files ............................................................................... 2 System Requirements ....................................................................................................................... 3 Installing Demonstration Versions ................................................................................................... 4 Uninstalling ReportViewer for ASP.NET AJAX............................................................................. 4 Deploying your Application in a Medium Trust Environment ....................................................... 4 End-User License Agreement ........................................................................................................................ 7 Licensing FAQs ............................................................................................................................................. 7 What is Licensing?............................................................................................................................ 7 How does Licensing Work?.............................................................................................................. 8 Common Scenarios .......................................................................................................................... 8 Troubleshooting.............................................................................................................................. 10 Technical Support ........................................................................................................................................ 12 Redistributable Files..................................................................................................................................... 12 About This Documentation ......................................................................................................................... 13 Namespaces.................................................................................................................................................. 13 Creating an AJAX-Enabled ASP.NET Project............................................................................................ 14 Adding the ReportViewer for ASP.NET AJAX Component to a Project ................................................... 16 Key Features .............................................................................................................................................. 17 ReportViewer for ASP.NET AJAX Quick Start ............................................................................................ 21 Step 1 of 3: Adding C1ReportViewer to the Page ........................................................................................ 21 Step 2 of 3: Adding Reports to the Control .................................................................................................. 22 Step 3 of 3: Running the Application ........................................................................................................... 22 The C1ReportViewer Control...................................................................................................................... 27 Displaying Reports and Documents ............................................................................................................ 27

iii

Note on C1Report/C1PrintDocument Licensing........................................................................................ 28 C1ReportViewer Elements .......................................................................................................................... 29 C1ReportViewer Toolbar ............................................................................................................................. 30 C1ReportViewer Outline and Search Panes ................................................................................................ 30 C1ReportViewer Preview Pane.................................................................................................................... 32 Design-Time Support .................................................................................................................................. 32 C1ReportViewer Smart Tag ......................................................................................................................... 32 C1ReportViewer Context Menu .................................................................................................................. 34 Run-Time Interaction ................................................................................................................................. 34 Printing a Report .......................................................................................................................................... 35 Saving a Report ............................................................................................................................................ 36 Changing Report Flow ................................................................................................................................. 37 Zooming a Report ........................................................................................................................................ 37 Navigating a Report ..................................................................................................................................... 38 Searching a Report ....................................................................................................................................... 39 ReportViewer for ASP.NET AJAX Appearance ........................................................................................... 41 Visual Styles ................................................................................................................................................. 41 Custom Visual Styles.................................................................................................................................... 43 Client-Side Functionality ............................................................................................................................ 44 Client-Side Properties................................................................................................................................... 44 Working with C1RdlReport ........................................................................................................................ 47 Report Definition Language (RDL)............................................................................................................. 47 C1RdlReport Advantages ............................................................................................................................ 47 C1RdlReport Limitations............................................................................................................................. 47 Loading an RDL file .................................................................................................................................... 48 Working with C1ReportDesigner ................................................................................................................ 49 About C1ReportDesigner............................................................................................................................. 49 Application Button ......................................................................................................................... 50 Design Tab ..................................................................................................................................... 51 Arrange Tab.................................................................................................................................... 56 Page Setup Tab ............................................................................................................................... 59 Preview Tab .................................................................................................................................... 60 Style Gallery ................................................................................................................................... 63 Setting C1ReportDesigner Options .............................................................................................................. 66 Creating a Basic Report Definition .............................................................................................................. 67

iv

Modifying the Report Layout ...................................................................................................................... 74 Enhancing the Report with Fields................................................................................................................ 76 Adding Chart Fields ....................................................................................................................... 76 Adding Gradient Fields .................................................................................................................. 80 Selecting, Moving, and Copying Fields.......................................................................................... 81 Changing Field, Section, and Report Properties ............................................................................ 83 Changing the Data Source.............................................................................................................. 83 Creating a Master-Detail Report Using Subreports ..................................................................................... 83 Previewing and Printing a Report ................................................................................................................ 87 Exporting and Publishing a Report .............................................................................................................. 89 Managing Report Definition Files ............................................................................................................... 89 Importing Microsoft Access Reports............................................................................................................ 90 Importing Crystal Reports............................................................................................................................ 94 Charting in ReportViewer for ASP.NET AJAX .......................................................................................... 95 Charts in Flat Reports .................................................................................................................... 95 Other Useful Chart Properties ........................................................................................................ 96 Charts with Multiple Series ............................................................................................................ 98 Series with Calculated Values ........................................................................................................ 98 Charts in Grouped Reports ............................................................................................................ 98 Aggregate Charts .......................................................................................................................... 100 Working with C1ReportsScheduler ............................................................................................................ 103 About C1ReportsScheduler........................................................................................................................ 103 Installation and Setup ................................................................................................................................ 103 User Interface ............................................................................................................................................. 104 Caption and Status Bar ................................................................................................................. 105 Task List ....................................................................................................................................... 105 Action List .................................................................................................................................... 107 Schedule ....................................................................................................................................... 109 Menu System ................................................................................................................................ 110 ReportViewer for ASP.NET AJAX Samples .............................................................................................. 115 ReportViewer for ASP.NET AJAX Task-Based Help.................................................................................. 115 Creating a C1ReportViewer in Code ......................................................................................................... 116 Setting the Visual Style............................................................................................................................... 116 Resizing the Control................................................................................................................................... 117 Sharing Documents Between Client Sessions ............................................................................................ 118 Switching Documents at Run Time ........................................................................................................... 118

vi

ComponentOne ReportViewer for ASP.NET AJAX Overview

Welcome to ComponentOne ReportViewer for ASP.NET AJAX. The C1ReportViewer control allows you to add reports to Web pages. The control is based on the C1Report component, and uses the same report definition files that you create with the C1ReportDesigner. ReportViewer for ASP.NET AJAX is an ASP.NET Web Forms control running within Microsoft Internet Information Server (IIS). The control's main function is to host the C1Report control and stream HTML and PDF reports to the client machine. The C1ReportViewer control shows documents and reports using an innovative technology that ComponentOne calls WebPaper. WebPaper technology allows the reports to be displayed with very high fidelity while preserving the ability to select, copy and search text. For information about using C1Report and C1PrintDocument, see the Reports for WinForms documentation.
Getting Started

Get started with the following topics: - Key Features (page 17) - Quick Start (page 21) - Control Elements (page 29) - Samples (page 115)

What's New in ReportViewer for ASP.NET AJAX

This documentation was last revised for 2011 v2. No new features were added to ReportViewer for ASP.NET AJAX in this release. Tip: A version history containing a list of new features, improvements, fixes, and changes for each product is available on HelpCentral at http://helpcentral.componentone.com/VersionHistory.aspx.

Revision History
The revision history details recent enhancements to ReportViewer for ASP.NET AJAX.

What's New in 2011 v1

The following feature was added to ReportViewer for ASP.NET AJAX in this release. Parameter Support C1ReportViewer now supports parameters for C1Report and C1RdlReport reports. The user interface has been enhanced with a Parameters pane which will be shown above the control when a report requires parameters. The Parameters pane can be collapsed or expanded during report viewing. Parameters must be filled in by the user before report generation starts. IMPORTANT NOTE for .NET 2.0 version users: C1.C1Report.2 assembly uses the following dll that is only included in .NET Framework 3.5 and later:

System.Windows.Forms.DataVisualization.dll

This assembly will be installed on your system with other ComponentOne reporting assemblies when you install ComponentOne Studio for ASP.NET AJAX (CLR 2.0). It MUST BE INCLUDED with other ComponentOne reporting assemblies when you deploy an application that uses ComponentOne reporting to other systems. (This does not apply to .NET 4.0 users as DataVisualization is already included in the Framework.)

What's New in 2010 v3

The following features were added to ReportViewer for ASP.NET AJAX: Hyperlinks Hyperlinks are now supported in ReportViewer for ASP.NET AJAX. Designer Enhancements The FileName and ReportName properties were added to the C1ReportViewer Tasks menu. To access the C1ReportViewer Tasks menu, click the control's smart tag in Design view. Additional Export Options The following file types are now included as options in the export options drop-down box: .c1d and .c1dx. RDL Support The C1RdlReport class was added to ReportViewer for ASP.NET AJAX. This provides support for SQL Server Reporting Services and includes many previously unsupported RDL features. C1RdlReport exposes the full RDL object model so you can modify existing reports or create new reports without external dependencies such as Microsoft Reporting Services. Import your existing SSRS report definitions (RDL) into C1RdlReport to programmatically generate your reports and integrate them with the full ComponentOne Reporting suite.

Installing ComponentOne ReportViewer for ASP.NET AJAX

The following sections provide helpful information on installing ComponentOne ReportViewer for ASP.NET AJAX.

ReportViewer for ASP.NET AJAX Setup Files

The ComponentOne Studio for ASP.NET AJAX installation program will create the following directory: C:\Program Files\ComponentOne\Studio for ASP.NET. This directory contains the following subdirectories: Bin C1WebUi C1WebUi\VisualStyles Contains copies of all binaries (DLLs, Exes) in the ComponentOne Visual Studio ASP.NET package. Contains files (at least a readme.txt) related to the product. Contains all external file themes.

The ComponentOne Studio for ASP.NET AJAX Help Setup program installs integrated Microsoft Help 2.0 and Microsoft Help Viewer help to the C:\Program Files\ComponentOne\Studio for ASP.NET directory in the following folders: H2Help Contains Microsoft Help 2.0 integrated documentation for all Studio components.

HelpViewer Samples

Contains Microsoft Help Viewer Visual Studio 2010 integrated documentation for all Studio components.

Samples for the product are installed in the ComponentOne Samples folder by default. The path of the ComponentOne Samples directory is slightly different on Windows XP and Windows 7/Vista machines: Windows XP path: C:\Documents and Settings\<username>\My Documents\ComponentOne Samples Windows 7/Vista path: C:\Users\<username>\Documents\ComponentOne Samples The ComponentOne Samples folder contains the following subdirectories: Common Studio for ASP.NET\C1WebUi Contains support and data files that are used by many of the demo programs. Contains samples and tutorials for ReportViewer for ASP.NET AJAX.

Samples can be accessed from the ComponentOne Sample Explorer. To view samples, on your desktop, click the Start button and then click All Programs | ComponentOne | Studio for ASP.NET | Samples | Palomino Samples.

System Requirements
System requirements for ComponentOne ReportViewer for ASP.NET AJAX include the following: Operating Systems: Windows 2000 Windows Server 2003 Windows Server 2008 Windows XP SP2 Windows Vista Windows 7 Web Server: Environments: Microsoft Internet Information Services (IIS) 5.0 or later .NET Framework 2.0 or later Visual Studio 2005 or later Internet Explorer 6.0 or later Firefox 2.0 or later Safari 2.0 or later Disc Drive: CD or DVD-ROM drive if installing from CD

Note: ReportViewer for ASP.NET AJAX requires Microsoft ASP.NET AJAX Extensions installed and a ScriptManager on the page before the C1ReportViewer control is placed on the page. You must create an ASP.NET AJAX-Enabled Project so that the ScriptManager and Microsoft AJAX Extensions are included on the page. For more information, see Creating an AJAX-Enabled ASP.NET Project (page 14). For more information

about Microsoft ASP.NET AJAX Extensions, see http://ajax.asp.net/. For information about the ScriptManager, see MSDN.

Installing Demonstration Versions

If you wish to try ComponentOne ReportViewer for ASP.NET AJAX and do not have a serial number, follow the steps through the installation wizard and use the default serial number. The only difference between unregistered (demonstration) and registered (purchased) versions of our products is that the registered version will stamp every application you compile so a ComponentOne banner will not appear when your users run the applications.

Uninstalling ReportViewer for ASP.NET AJAX

To uninstall ComponentOne ReportViewer for ASP.NET AJAX: 1. 2. 3. 1. 2. 3. Open the Control Panel and select the Add or Remove Programs or Programs and Features (Windows 7/Vista). Select ComponentOne Studio for ASP.NET AJAX and click the Remove button. Click Yes to remove the program. Open the Control Panel and select Add or Remove Programs (Programs and Features in Windows 7/Vista). Select ComponentOne Studio for ASP.NET AJAX Help and click the Remove button. Click Yes to remove the integrated help.

To uninstall Studio for ASP.NET AJAX integrated help:

Deploying your Application in a Medium Trust Environment

Depending on your hosting choice, you may need to deploy your Web site or application in a medium trust environment. Often in a shared hosting environment, medium trust is required. In a medium trust environment several permissions are unavailable or limited, including OleDbPermission, ReflectionPermission,and FileIOPermission. You can configure your Web.config file to enable these permissions.
Note: ComponentOne controls will not work in an environment where reflection is not allowed.

ComponentOne ASP.NET AJAX controls include the AllowPartiallyTrustedCallers() assembly attribute and will work under the medium trust level with some changes to the Web.config file. Since this requires some control over the Web.config file, please check with your particular host to determine if they can provide the rights to override these security settings.

Modifying or Editing the Config File

In order to add permissions, you can edit the exiting web_mediumtrust.config file or create a custom policy file based on the medium trust policy. If you modify the existing web_mediumtrust.config file, all Web applications will have the same permissions with the permissions you have added. If you want applications to have different permissions, you can instead create a custom policy based on medium trust. Edit the Config File In order to add permissions, you can edit the exiting web_mediumtrust.config file. To edit the exiting web_mediumtrust.config file, complete the following steps: 1. 2. Locate the medium trust policy file web_mediumtrust.config located by default in the %windir%\Microsoft.NET\Framework\{Version}\CONFIG directory. Open the web_mediumtrust.config file.

3.

Add the permissions that you want to grant. For examples, see Adding Permissions (page 5).

Create a Custom Policy Based on Medium Trust In order to add permissions, you can create a custom policy file based on the medium trust policy. To create a custom policy file, complete the following steps: 1. 2. Locate the medium trust policy file web_mediumtrust.config located by default in the %windir%\Microsoft.NET\Framework\{Version}\CONFIG directory. Copy the web_mediumtrust.config file and create a new policy file in the same directory. Give the new a name that indicates that it is your variation of medium trust; for example, AllowReflection_Web_MediumTrust.config. 3. 4. Add the permissions that you want to grant. For examples, see Adding Permissions (page 5). Enable the custom policy file on your application by modifying the following lines in your web.config file under the <system.web> node: <system.web> <trust level="CustomMedium" originUrl=""/> <securityPolicy> <trustLevel name="CustomMedium" policyFile="AllowReflection_Web_MediumTrust.config"/> </securityPolicy> ... </system.web>
Note: Your host may not allow trust level overrides. Please check with your host to see if you have these rights.

Allowing Deserialization
To allow the deserialization of the license added to App_Licenses.dll by the Microsoft IDE, you should add the SerializationFormatter flag to security permission to the Web.config file. Complete the steps in the Modifying or Editing the Config File (page 4) topic to create or modify a policy file before completing the following. Add the SerializationFormatter flag to the <IPermission class="SecurityPermission"> tag so that it appears similar to the following: <NamedPermissionSets> <PermissionSet class="NamedPermissionSet" version="1" Name="ASP.Net"> <IPermission class="SecurityPermission" version="1" Flags="Assertion, Execution, ControlThread, ControlPrincipal, RemotingConfiguration, SerializationFormatter"/> ... </PermissionSet> </NamedPermissionSets>

Adding Permissions
You can add permission, including ReflectionPermission, OleDbPermission, and FileIOPermission to the web.config file. Note that ComponentOne controls will not work in an environment where reflection is not allowed. Complete the steps in the Modifying or Editing the Config File (page 4) topic to create or modify a policy file before completing the following.

ReflectionPermission By default ReflectionPermission is not available in a medium trust environment. ComponentOne ASP.NET controls require reflection permission because LicenseManager.Validate() causes a link demand for full trust. To add reflection permission, complete the following: 1. 2. Open the web_mediumtrust.config file or a file created based on the web_mediumtrust.config file. Add the following <SecurityClass> tag after the <SecurityClasses> tag so that it appears similar to the following: <SecurityClasses> <SecurityClass Name="ReflectionPermission" Description="System.Security.Permissions.ReflectionPermission, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/> ... </SecurityClasses> Add the following <IPermission> tag after the <NamedPermissionSets> tag so it appears similar to the following: <NamedPermissionSets> <PermissionSet class="NamedPermissionSet" version="1" Name="ASP.Net"> <IPermission class="ReflectionPermission" version="1" Flags="ReflectionEmit,MemberAccess" /> ... </PermissionSet> </NamedPermissionSets> Save and close the web_mediumtrust.config file.

3.

4.

OleDbPermission By default OleDbPermission is not available in a medium trust environment. This means you cannot use the ADO.NET managed OLE DB data provider to access databases. If you wish to use the ADO.NET managed OLE DB data provider to access databases, you must modify the web_mediumtrust.config file. To add OleDbPermission, complete the following steps: 1. 2. Open the web_mediumtrust.config file or a file created based on the web_mediumtrust.config file. Add the following <SecurityClass> tag after the <SecurityClasses> tag so that it appears similar to the following: <SecurityClasses> <SecurityClass Name="OleDbPermission" Description="System.Data.OleDb.OleDbPermission, System.Data, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/> ... </SecurityClasses> Add the following <IPermission> tag after the <NamedPermissionSets> tag so it appears similar to the following: <NamedPermissionSets> <PermissionSet class="NamedPermissionSet" version="1" Name="ASP.Net"> <IPermission class="OleDbPermission" version="1" Unrestricted="true"/> ... </PermissionSet>

3.

</NamedPermissionSets> 4. Save and close the web_mediumtrust.config file.

FileIOPermission By default, FileIOPermission is not available in a medium trust environment. This means no file access is permitted outside of the application's virtual directory hierarchy. If you wish to allow additional file permissions, you must modify the web_mediumtrust.config file. To modify FileIOPermission to allow read access to a specific directory outside of the application's virtual directory hierarchy, complete the following steps: 1. 2. Open the web_mediumtrust.config file or a file created based on the web_mediumtrust.config file. Add the following <SecurityClass> tag after the <SecurityClasses> tag so that it appears similar to the following: <SecurityClasses> <SecurityClass Name="FileIOPermission" Description="System.Security.Permissions.FileIOPermission, mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/> ... </SecurityClasses> Add the following <IPermission> tag after the <NamedPermissionSets> tag so it appears similar to the following: <NamedPermissionSets> <PermissionSet class="NamedPermissionSet" version="1" Name="ASP.Net"> ... <IPermission class="FileIOPermission" version="1" Read="C:\SomeDir;$AppDir$" Write="$AppDir$" Append="$AppDir$" PathDiscovery="$AppDir$" /> ... </PermissionSet> </NamedPermissionSets> Save and close the web_mediumtrust.config file.

3.

4.

End-User License Agreement

All of the ComponentOne licensing information, including the ComponentOne end-user license agreements, frequently asked licensing questions, and the ComponentOne licensing model, is available online at http://www.componentone.com/SuperPages/Licensing/.

Licensing FAQs
This section describes the main technical aspects of licensing. It may help the user to understand and resolve licensing problems he may experience when using ComponentOne .NET and ASP.NET products.

What is Licensing?
Licensing is a mechanism used to protect intellectual property by ensuring that users are authorized to use software products. Licensing is not only used to prevent illegal distribution of software products. Many software vendors, including ComponentOne, use licensing to allow potential users to test products before they decide to purchase them. Without licensing, this type of distribution would not be practical for the vendor or convenient for the user. Vendors would either have to distribute evaluation software with limited functionality, or shift the burden of

managing software licenses to customers, who could easily forget that the software being used is an evaluation version and has not been purchased.

How does Licensing Work?

ComponentOne uses a licensing model based on the standard set by Microsoft, which works with all types of components.
Note: The Compact Framework components use a slightly different mechanism for run-time licensing than the other ComponentOne components due to platform differences.

When a user decides to purchase a product, he receives an installation program and a Serial Number. During the installation process, the user is prompted for the serial number that is saved on the system. (Users can also enter the serial number by clicking the License button on the About Box of any ComponentOne product, if available, or by rerunning the installation and entering the serial number in the licensing dialog box.) When a licensed component is added to a form or Web page, Visual Studio obtains version and licensing information from the newly created component. When queried by Visual Studio, the component looks for licensing information stored in the system and generates a run-time license and version information, which Visual Studio saves in the following two files: An assembly resource file which contains the actual run-time license A "licenses.licx" file that contains the licensed component strong name and version information

These files are automatically added to the project. In WinForms and ASP.NET 1.x applications, the run-time license is stored as an embedded resource in the assembly hosting the component or control by Visual Studio. In ASP.NET 2.x applications, the run-time license may also be stored as an embedded resource in the App_Licenses.dll assembly, which is used to store all run-time licenses for all components directly hosted by WebForms in the application. Thus, the App_licenses.dll must always be deployed with the application. The licenses.licx file is a simple text file that contains strong names and version information for each of the licensed components used in the application. Whenever Visual Studio is called upon to rebuild the application resources, this file is read and used as a list of components to query for run-time licenses to be embedded in the appropriate assembly resource. Note that editing or adding an appropriate line to this file can force Visual Studio to add run-time licenses of other controls as well. Note that the licenses.licx file is usually not shown in the Solution Explorer; it appears if you press the Show All Files button in the Solution Explorer's Toolbox, or from Visual Studio's main menu, select Show All Files on the Project menu. Later, when the component is created at run time, it obtains the run-time license from the appropriate assembly resource that was created at design time and can decide whether to simply accept the run-time license, to throw an exception and fail altogether, or to display some information reminding the user that the software has not been licensed. All ComponentOne products are designed to display licensing information if the product is not licensed. None will throw licensing exceptions and prevent applications from running.

Common Scenarios
The following topics describe some of the licensing scenarios you may encounter.

Creating components at design time

This is the most common scenario and also the simplest: the user adds one or more controls to the form, the licensing information is stored in the licenses.licx file, and the component works. Note that the mechanism is exactly the same for Windows Forms and Web Forms (ASP.NET) projects.

Creating components at run time

This is also a fairly common scenario. You do not need an instance of the component on the form, but would like to create one or more instances at run time. In this case, the project will not contain a licenses.licx file (or the file will not contain an appropriate run-time license for the component) and therefore licensing will fail. To fix this problem, add an instance of the component to a form in the project. This will create the licenses.licx file and things will then work as expected. (The component can be removed from the form after the licenses.licx file has been created). Adding an instance of the component to a form, then removing that component, is just a simple way of adding a line with the component strong name to the licenses.licx file. If desired, you can do this manually using notepad or Visual Studio itself by opening the file and adding the text. When Visual Studio recreates the application resources, the component will be queried and its run-time license added to the appropriate assembly resource.

Inheriting from licensed components

If a component that inherits from a licensed component is created, the licensing information to be stored in the form is still needed. This can be done in two ways: Add a LicenseProvider attribute to the component. This will mark the derived component class as licensed. When the component is added to a form, Visual Studio will create and manage the licenses.licx file, and the base class will handle the licensing process as usual. No additional work is needed. For example: [LicenseProvider(typeof(LicenseProvider))] class MyGrid: C1.Win.C1FlexGrid.C1FlexGrid { // ... } Add an instance of the base component to the form. This will embed the licensing information into the licenses.licx file as in the previous scenario, and the base component will find it and use it. As before, the extra instance can be deleted after the licenses.licx file has been created. Please note, that C1 licensing will not accept a run-time license for a derived control if the run-time license is embedded in the same assembly as the derived class definition, and the assembly is a DLL. This restriction is necessary to prevent a derived control class assembly from being used in other applications without a design-time license. If you create such an assembly, you will need to take one of the actions previously described create a component at run time.

Using licensed components in console applications

When building console applications, there are no forms to add components to, and therefore Visual Studio won't create a licenses.licx file. In these cases, create a temporary Windows Forms application and add all the desired licensed components to a form. Then close the Windows Forms application and copy the licenses.licx file into the console application project. Make sure the licenses.licx file is configured as an embedded resource. To do this, right-click the licenses.licx file in the Solution Explorer window and select Properties. In the Properties window, set the Build Action property to Embedded Resource.

Using licensed components in Visual C++ applications

There is an issue in VC++ 2003 where the licenses.licx is ignored during the build process; therefore, the licensing information is not included in VC++ applications.

To fix this problem, extra steps must be taken to compile the licensing resources and link them to the project. Note the following: 1. 2. 3. 4. 5. Build the C++ project as usual. This should create an EXE file and also a licenses.licx file with licensing information in it. Copy the licenses.licx file from the application directory to the target folder (Debug or Release). Copy the C1Lc.exe utility and the licensed DLLs to the target folder. (Don't use the standard lc.exe, it has bugs.) Use C1Lc.exe to compile the licenses.licx file. The command line should look like this: c1lc /target:MyApp.exe /complist:licenses.licx /i:C1.Win.C1FlexGrid.dll Link the licenses into the project. To do this, go back to Visual Studio, right-click the project, select Properties, and go to the Linker/Command Line option. Enter the following: /ASSEMBLYRESOURCE:Debug\MyApp.exe.licenses Rebuild the executable to include the licensing information in the application.

6.

Using licensed components with automated testing products

Automated testing products that load assemblies dynamically may cause them to display license dialog boxes. This is the expected behavior since the test application typically does not contain the necessary licensing information, and there is no easy way to add it. This can be avoided by adding the string "C1CheckForDesignLicenseAtRuntime" to the AssemblyConfiguration attribute of the assembly that contains or derives from ComponentOne controls. This attribute value directs the ComponentOne controls to use design-time licenses at run time. For example: #if AUTOMATED_TESTING [AssemblyConfiguration("C1CheckForDesignLicenseAtRuntime")] #endif public class MyDerivedControl : C1LicensedControl { // ... } Note that the AssemblyConfiguration string may contain additional text before or after the given string, so the AssemblyConfiguration attribute can be used for other purposes as well. For example: [AssemblyConfiguration("C1CheckForDesignLicenseAtRuntime,BetaVersion ")] THIS METHOD SHOULD ONLY BE USED UNDER THE SCENARIO DESCRIBED. It requires a designtime license to be installed on the testing machine. Distributing or installing the license on other computers is a violation of the EULA.

Troubleshooting
We try very hard to make the licensing mechanism as unobtrusive as possible, but problems may occur for a number of reasons. Below is a description of the most common problems and their solutions.

I have a licensed version of a ComponentOne product but I still get the splash screen when I run my project.
If this happens, there may be a problem with the licenses.licx file in the project. It either doesn't exist, contains wrong information, or is not configured correctly.

10

First, try a full rebuild (Rebuild All from the Visual Studio Build menu). This will usually rebuild the correct licensing resources. If that fails follow these steps: 1. 2. 3. 4. Open the project and go to the Solution Explorer window. Click the Show All Files button on the top of the window. Find the licenses.licx file and open it. If prompted, continue to open the file. Change the version number of each component to the appropriate value. If the component does not appear in the file, obtain the appropriate data from another licenses.licx file or follow the alternate procedure following. Save the file, then close the licenses.licx tab. Rebuild the project using the Rebuild All option (not just Rebuild). Open the project and go to the Solution Explorer window. Click the Show All Files button on the top of the window. Find the licenses.licx file and delete it. Close the project and reopen it. Open the main form and add an instance of each licensed control. Check the Solution Explorer window, there should be a licenses.licx file there. Rebuild the project using the Rebuild All option (not just Rebuild). Open the project and go to the Solution Explorer window. Find the licenses.licx file and right-click it. Select the Rebuild Licenses option (this will rebuild the App_Licenses.licx file). Rebuild the project using the Rebuild All option (not just Rebuild).

5. 6. 1. 2. 3. 4. 5. 6. 7. 1. 2. 3. 4.

Alternatively, follow these steps:

For ASP.NET 2.x applications, follow these steps:

I have a licensed version of a ComponentOne product on my Web server but the components still behave as unlicensed.
There is no need to install any licenses on machines used as servers and not used for development. The components must be licensed on the development machine, therefore the licensing information will be saved into the executable (EXE or DLL) when the project is built. After that, the application can be deployed on any machine, including Web servers. For ASP.NET 2.x applications, be sure that the App_Licenses.dll assembly created during development of the application is deployed to the bin application bin directory on the Web server. If your ASP.NET application uses WinForms user controls with constituent licensed controls, the run-time license is embedded in the WinForms user control assembly. In this case, you must be sure to rebuild and update the user control whenever the licensed embedded controls are updated.

I downloaded a new build of a component that I have purchased, and now I'm getting the splash screen when I build my projects.
Make sure that the serial number is still valid. If you licensed the component over a year ago, your subscription may have expired. In this case, you have two options: Option 1 Renew your subscription to get a new serial number.

11

If you choose this option, you will receive a new serial number that you can use to license the new components (from the installation utility or directly from the About Box). The new subscription will entitle you to a full year of upgrades and to download the latest maintenance builds directly from http://prerelease.componentone.com/. Option 2 Continue to use the components you have. Subscriptions expire, products do not. You can continue to use the components you received or downloaded while your subscription was valid.

Technical Support
ComponentOne offers various support options. For a complete list and a description of each, visit the ComponentOne Web site at http://www.componentone.com/SuperProducts/SupportServices/. Some methods for obtaining technical support include: Online Resources ComponentOne provides customers with a comprehensive set of technical resources in the form of FAQs, samples and videos, Version Release History, searchable Knowledge base, searchable Online Help and more. We recommend this as the first place to look for answers to your technical questions. Online Support via our Incident Submission Form This online support service provides you with direct access to our Technical Support staff via an online incident submission form. When you submit an incident, you'll immediately receive a response via e-mail confirming that you've successfully created an incident. This email will provide you with an Issue Reference ID and will provide you with a set of possible answers to your question from our Knowledgebase. You will receive a response from one of the ComponentOne staff members via e-mail in 2 business days or less. Product Forums ComponentOne's product forums are available for users to share information, tips, and techniques regarding ComponentOne products. ComponentOne developers will be available on the forums to share insider tips and technique and answer users' questions. Please note that a ComponentOne User Account is required to participate in the ComponentOne Product Forums. Installation Issues Registered users can obtain help with problems installing ComponentOne products. Contact technical support by using the online incident submission form or by phone (412.681.4738). Please note that this does not include issues related to distributing a product to end-users in an application. Documentation Microsoft integrated ComponentOne documentation can be installed with each of our products, and documentation is also available online. If you have suggestions on how we can improve our documentation, please email the Documentation team. Please note that e-mail sent to the Documentation team is for documentation feedback only. Technical Support and Sales issues should be sent directly to their respective departments.

Note: You must create a ComponentOne Account and register your product with a valid serial number to obtain support using some of the above methods.

Redistributable Files
ComponentOne ReportViewer for ASP.NET AJAX is developed and published by ComponentOne LLC. You may use it to develop applications in conjunction with Microsoft Visual Studio or any other programming environment that enables the user to use and integrate the control(s). You may also distribute, free of royalties, the following Redistributable Files with any such application you develop to the extent that they are used separately on a single CPU on the client/workstation side of the network:

12

C1.C1Report.2.dll C1.C1Report.4.dll C1.Web.UI.Controls.C1Report.2.dll C1.Web.UI.Controls.C1Report.3.dll C1.Web.UI.Controls.C1Report.4.dll

Site licenses are available for groups of multiple developers. Please contact Sales@ComponentOne.com for details. IMPORTANT NOTE for .NET 2.0 version users: The C1.C1Report.2 assembly uses the following DLL that is only included in .NET Framework 3.5 and later: System.Windows.Forms.DataVisualization.dll This assembly will be installed on your system with other Reports assemblies when you install ComponentOne Studio for ASP.NET AJAX (CLR 2.0). It MUST BE INCLUDED with other ComponentOne Reporting assemblies when you deploy an application that uses ComponentOne reporting assemblies to other systems.

About This Documentation

Acknowledgements Microsoft, Windows, Windows Vista, and Visual Studio, are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Firefox is a registered trademark of the Mozilla Foundation. Safari is a trademark of Apple Inc., registered in the U.S. and other countries. ComponentOne If you have any suggestions or ideas for new features or controls, please call us or write: Corporate Headquarters ComponentOne LLC 201 South Highland Avenue 3rd Floor Pittsburgh, PA 15206 USA 412.681.4343 412.681.4384 (Fax) http://www.componentone.com ComponentOne Doc-To-Help This documentation was produced using ComponentOne Doc-To-Help Enterprise.

Namespaces
Namespaces organize the objects defined in an assembly. Assemblies can contain multiple namespaces, which can in turn contain other namespaces. Namespaces prevent ambiguity and simplify references when using large groups of objects such as class libraries. The general namespace for ComponentOne Web products is C1.Web. The following code fragment shows how to declare a C1ReportViewer using the fully qualified name for this class: Visual Basic Dim ReportViewer As C1.Web.UI.Controls.C1ReportViewer C# C1.Web.UI.Controls.C1ReportViewer ReportViewer;

13

Namespaces address a problem sometimes known as namespace pollution, in which the developer of a class library is hampered by the use of similar names in another library. These conflicts with existing components are sometimes called name collisions. Fully qualified names are object references that are prefixed with the name of the namespace where the object is defined. You can use objects defined in other projects if you create a reference to the class (by choosing Add Reference from the Project menu) and then use the fully qualified name for the object in your code. Fully qualified names prevent naming conflicts because the compiler can always determine which object is being used. However, the names themselves can get long and cumbersome. To get around this, you can use the Imports statement (using in C#) to define an alias an abbreviated name you can use in place of a fully qualified name. For example, the following code snippet creates aliases for two fully qualified names, and uses these aliases to define two objects: Visual Basic Imports C1ReportViewer = C1.Web.UI.Controls.C1ReportViewer Imports MyReportViewer = MyProject.Objects.C1ReportViewer Dim rv1 As C1ReportViewer Dim rv2 As MyReportViewer C# using C1ReportViewer = C1.Web.UI.Controls.C1ReportViewer; using MyReportViewer = MyProject.Objects.C1ReportViewer; C1ReportViewer rv1; MyReportViewer rv2; If you use the Imports statement without an alias, you can use all the names in that namespace without qualification provided they are unique to the project.

Creating an AJAX-Enabled ASP.NET Project

ComponentOne ReportViewer for ASP.NET AJAX requires you to create an ASP.NET AJAX-Enabled project so that Microsoft ASP.NET AJAX Extensions and a ScriptManager control are included in your project before the C1ReportViewer control is placed on the page. This allows you to take advantage of ASP.NET AJAX and certain features such as partial-page rendering and client-script functionality of the Microsoft AJAX Library. When creating AJAX-Enabled ASP.NET projects, Visual Studios 2008 and 2005 both give you the option of creating a Web site project or a Web application project. MSDN provides detailed information on why you would choose one option over the other. If you are using Visual Studio 2008 with .NET Framework 2.0 or .NET Framework 3.0 or if you are using Visual Studio 2005, you must install the ASP.NET AJAX Extensions 1.0, which can be found at http://ajax.asp.net/. Additionally for Visual Studio 2005 users, creating a Web application project requires installation of a Visual Studio 2005 update and add-in, which can be found at http://msdn.microsoft.com/; however, if you have Visual Studio 2005 SP1, Web application project support is included and a separate download is not required. If you are using Visual Studio 2008 and .NET Framework 3.5, you can easily create an AJAX-enabled ASP.NET project without installing separate add-ins because the framework has a built-in AJAX library and controls.
Note: If you are using Visual Studio 2010, see http://www.asp.net/ajax/ for more information on creating an AJAXEnabled ASP.NET Project.

The following table summarizes the installations needed:

14

Visual Studio Version Visual Studio 2008, .NET Framework 3.5 Visual Studio 2008 and .NET Framework 2.0 or 3.0 Visual Studio 2005 Service Pack 1 Visual Studio 2005

Additional Installation Requirements None

ASP.NET AJAX Extensions 1.0

ASP.NET AJAX Extensions 1.0 Visual Studio update and add-in (2 installs for Web
application project support)

The following topics explain how to create both types of projects in Visual Studio 2008 and 2005. Creating an AJAX-Enabled Web Site Project in Visual Studio 2008 To create a Web site project in Visual Studio 2008, complete the following steps: a. b. c. From the File menu, select New | Web Site. The New Web Site dialog box opens. Select .NET Framework 3.5 or the desired framework in the upper right corner. Note that if you choose .NET Framework 2.0 or 3.0, you must install the extensions first. In the list of templates, select AJAX 1.0-Enabled ASP.NET 2.0 Web Site.

d. Click Browse to specify a location and then click OK.

Note: The Web server must have IIS version 6 or later and the .NET Framework installed on it. If you have IIS on your computer, you can specify http://localhost for the server.

A new AJAX-Enabled Web Site is created at the root of the Web server you specified. In addition, a new Web Forms page called Default.aspx is displayed and a ScriptManager control is placed on the form. The ScriptManger is needed to enable certain features of ASP.NET AJAX such as partial-page rendering, client-script functionality of the Microsoft AJAX Library, and Web-service calls.

Creating an AJAX-Enabled Web Application Project in Visual Studio 2008 To create a new Web application project in Visual Studio 2008, complete the following steps. a. b. c. From the File menu, select New | Project. The New Project dialog box opens. Select .NET Framework 3.5 or the desired framework in the upper right corner. Note that if you choose .NET Framework 2.0 or 3.0, you must install the extensions first. Under Project Types, choose either Visual Basic or Visual C# and then select Web. Note that one of these options may be located under Other Languages.

d. Select AJAX 1.0-Enabled ASP.NET 2.0 Web Application from the list of Templates in the right pane. e. Enter a URL for your application in the Location field and click OK.
Note: The Web server must have IIS version 6 or later and the .NET Framework installed on it. If you have IIS on your computer, you can specify http://localhost for the server.

A new Web Forms project is created at the root of the Web server you specified. In addition, a new Web Forms page called Default.aspx is displayed and a ScriptManager control is placed on the form.

15

The ScriptManger is needed to enable certain features of ASP.NET AJAX such as partial-page rendering, client-script functionality of the Microsoft AJAX Library, and Web-service calls.

Creating an AJAX-Enabled Web Site Project in Visual Studio 2005 To create a Web site project in Visual Studio 2005, complete the following steps: a. b. c. From the File menu in Microsoft Visual Studio .NET, select New Web Site. The New Web Site dialog box opens. Select ASP.NET AJAX-Enabled Web Site from the list of Templates. Enter a URL for your site in the Location field and click OK.
Note: The Web server must have IIS version 6 or later and the .NET Framework installed on it. If you have IIS on your computer, you can specify http://localhost for the server.

A new Web Forms project is created at the root of the Web server you specified. In addition, a new Web Forms page called Default.aspx is displayed and a ScriptManager control is placed on the form. The ScriptManger is needed to enable certain features of ASP.NET AJAX such as partial-page rendering, client-script functionality of the Microsoft AJAX Library, and Web-service calls. Creating an AJAX-Enabled Web Application Project in Visual Studio 2005 To create a new Web application project in Visual Studio 2005, complete the following steps. a. b. c. From the File menu in Microsoft Visual Studio 2005, select New Project. The New Project dialog box opens. Under Project Types, choose either Visual Basic Projects or Visual C# Projects. Note that one of these options may be located under Other Languages. Select ASP.NET AJAX-Enabled Web Application from the list of Templates in the right pane.

d. Enter a URL for your application in the Location field and click OK.
Note: The Web server must have IIS version 6 or later and the .NET Framework installed on it. If you have IIS on your computer, you can specify http://localhost for the server.

A new Web Forms project is created at the root of the Web server you specified. In addition, a new Web Forms page called Default.aspx is displayed and a ScriptManager control is placed on the form. The ScriptManger is needed to enable certain features of ASP.NET AJAX such as partial-page rendering, client-script functionality of the Microsoft AJAX Library, and Web-service calls.

Adding the ReportViewer for ASP.NET AJAX Component to a Project

When you install ComponentOne Studio for ASP.NET AJAX, the Create a ComponentOne Visual Studio Toolbox Tab check box is checked, by default, in the installation wizard. When you open Visual Studio, you will notice a ComponentOne Studio for ASP.NET AJAX Projects tab containing the ComponentOne controls that have automatically been added to the Toolbox. If you decide to uncheck the Create a ComponentOne Visual Studio Toolbox Tab check box during installation, you can manually add ComponentOne controls to the Toolbox at a later time. Manually Adding the Studio for ASP.NET AJAX controls to the Toolbox

16

When you install ComponentOne ReportViewer for ASP.NET AJAX, the following ComponentOne ReportViewer for ASP.NET AJAX component will appear in the Visual Studio Toolbox customization dialog box: 1. 2. 3. 4. C1ReportViewer Open the Visual Studio IDE (Microsoft Development Environment). Make sure the Toolbox is visible (select Toolbox in the View menu if necessary) and right-click it to open the context menu. To make the Studio for ASP.NET AJAX components appear on their own tab in the Toolbox, select Add Tab from the context menu and type in the tab name, Studio for ASP.NET AJAX, for example. Right-click the tab where the component is to appear and select Choose Items from the context menu. The Choose Toolbox Items dialog box opens. In the dialog box, select the .NET Framework Components tab. Sort the list by Namespace (click the Namespace column header) and check the check boxes for all components belonging to namespace C1.Web.UI.Controls.C1Report.2.dll. Note that there may be more than one component for each namespace. Click OK to close the dialog box. The controls are added to the Visual Studio Toolbox. Adding Studio for ASP.NET AJAX Controls to the Form To add Studio for ASP.NET controls to a form: 1. 2. Add them to the Visual Studio Toolbox. Double-click each control or drag it onto your form. To manually add the Studio for ASP.NET AJAX controls to the Visual Studio Toolbox:

5.

Note: ReportViewer for ASP.NET AJAX requires Microsoft ASP.NET AJAX Extensions installed and a ScriptManager on the page before the C1ReportViewer control is placed on the page. You must create an ASP.NET AJAX-Enabled Project so that the ScriptManager and Microsoft AJAX Extensions are included on the page. For more information, see Creating an AJAX-Enabled ASP.NET Project (page 14). For more information about Microsoft ASP.NET AJAX Extensions, see http://ajax.asp.net/. For information about the ScriptManager, see MSDN.

Adding a Reference to the Assembly To add a reference to the C1.Web.UI.Controls.C1Report.2 assembly: 1. 2. 3. Select the Add Reference option from the Website menu of your Web Site project or from the Project menu of your Web Application project. Select the most recent version of the ComponentOne Studio for ASP.NET AJAX assembly from the list on the NET tab or browse to find the C1.Web.UI.Controls.C1Report.2.dll file and click OK. Select the Form1.vb tab or go to View|Code to open the Code Editor. At the top of the file, add the following Imports directive (using in C#): Imports C1.Web.UI.Controls.C1Report
Note: This makes the objects defined in the C1.Web.UI.Controls.C1Report.2 assembly visible to the project. See Namespaces (page 13) for more information.

Key Features
ComponentOne ReportViewer for ASP.NET AJAX includes several unique features, including the following:
17

Pixel-perfect Reports in Any Browser C1ReportViewer uses WebPaper to create pixel perfect reports that are truly in a league of their own. ComponentOne WebPaper technology allows you to render reports in a high fidelity graphical form.

Crystal Reports C1ReportViewer supports features found in Microsoft Access and Crystal Reports. With the click of a button, import Access report files (MDB) and Crystal report files (RPT) using the C1ReportDesigner.

Microsoft Access and SQL Reporting Services Reports C1ReportViewer has extensive support of Microsoft reporting technologies. Both Access and SQL Server Reporting Services Reports are supported in the viewer. The support for RDL allows you to use existing enterprise reports embedded in your Web app with WebPaper technology.

Zooming By default, the report pages are zoomed to fit the whole page. You can change the zoom to show the pages in actual size, to fit the page width in the preview window, to fit the content width in the preview window, or to a custom zoom mode which is determined by the value of the Zoom property.

Exporting Export your reports directly to various portable formats: Excel, PDF, HTML, text, and images. This allows you to conveniently send your reports via e-mail or share them across your enterprise.

Auto-generate Outlines The outline tree is created automatically based on the report groups and can be used to navigate through the report in the Adobe Acrobat viewer. Each node in the tree corresponds to a group header section in the report. Invisible group header sections do not generate outline entries in the PDF document.

Paged or Flowing Navigation The viewing pane of C1ReportViewer supports both paged navigation and scrolling navigation. Both views can be used easily with the click of a button. It gives your end-users the option to choose which they prefer.

Built-in Search The C1ReportViewer control comes with a built-in search pane that queries an auto-generated index of your report. This feature gives your end-users a powerful search tool in reports without writing a single line of code. It also highlights and builds a menu of the search results to help your end-users find what they are looking for.

Efficient Report Cache Experience extremely fast response times with C1ReportViewer's efficient report cache. Each time the C1ReportViewer control renders a report it is compressed and stored in the server, eliminating the need to re-query the database and regenerate the report when it is needed again. This reduces server loads and results in extremely fast response times at low memory cost.

Powerful Printing Capabilities The C1ReportViewer control has built-in print features including a print button that launches a custom print dialog box. The print dialog box allows your end-users to change how their report gets printed and even shows them a live preview of the document.

C1ReportDesigner Application Quickly create, edit, preview, load, and save report definition files without writing a single line of code. The familiar Microsoft Access-like user interface of the C1ReportDesigner application yields fast adaptation. The designer's new Microsoft Office 2007 Ribbon-style UI organizes related commands into groups enabling you to design reports faster than ever before.

18

Banded Report Model Reports uses a banded report model based on groups, sections, and fields. The banded report model allows for a highly organized report layout.

30+ Built-in Report Templates The enhanced report designer application now includes 34 report templates. Simply select a report from all of the C1ReportViewer samples and you get a professionally styled report in minutes. No coding required - your colorful report is just a click away!

Flexible Data Binding Specify a connection string and an SQL statement in your report definition and C1ReportViewer will load the data automatically for you. Optionally, use XML files, custom collections, and other data sources.

Nested Reports C1ReportViewer may contain nested reports to arbitrary levels (subreports). You can use the main report to show detailed information and use subreports to show summary data at the beginning of each group.

19

ReportViewer for ASP.NET AJAX Quick Start

The following quick start is designed to quickly familiarize you with the features for the C1ReportViewer control. In this quick start you'll create a simple Web site that uses the C1ReportViewer control to view a report. Note that in this example you'll use the CommonTasks.xml example file which should be installed in the ComponentOne Samples folder.

Step 1 of 3: Adding C1ReportViewer to the Page

The C1ReportViewer control is easy to create and setup. In this step you'll create a new application and add a C1ReportViewer control to the page so you can see just how easy it is. Complete the following steps: 1. 2. Create a new ASP.NET AJAX-Enabled Website project. For details on how to create a new project, see Creating an AJAX-Enabled ASP.NET Project (page 14). Click the Design tab located below the Document window to switch to Design view. Note that as you've created an AJAX-Enabled Web site, a ScriptManager control initially appears on the page. If you created a Web site project that does not include the ScriptManager control, navigate to the Visual Studio Toolbox and add the ScriptManager control to the page. 3. Navigate to the Visual Studio Toolbox and double-click the C1ReportViewer control to add it to the page. The C1ReportViewer control is a fully-functioning report viewer. The page will now look similar to the following image:

21

Note that the C1ReportViewer control is a fully functioning report viewer. For detailed information about the parts of the control, see C1ReportViewer Elements (page 29). Now that you've created your Web site and added the C1ReportViewer control to the page, the next step is to add a report to display in the control.

Step 2 of 3: Adding Reports to the Control

In the last step you created a new application and added the C1ReportViewer to the project. In this step you'll add a data source to your application and load a report into the C1ReportViewer control without using any code at all. Note that in this step you'll use the CommonTasks.xml example file which should be installed in the ComponentOne Samples folder. Complete the following steps: 1. 2. 3. 4. Navigate to the Solution Explorer window, right-click the project name, and choose New Folder. Name the new folder "~/tempReports". This is the default value of the ReportsFolderPath property. In the Solution Explorer, right-click the App_Data folder and select Add Existing Item. The Add Existing Item dialog box will appear. In the Add Existing Item dialog box locate the C1Nwind.mdb file and click the Add button to close the dialog box and add the file to the project. By default, the C1NWind.mdb file will be located in the Documents or My Documents folder at ComponentOne Samples\Common. 5. 6. In the Solution Explorer, right-click the project name and select Add Existing Item. The Add Existing Item dialog box will appear. In the Add Existing Item dialog box locate the CommonTasks.xml report definition file and click the Add button to close the dialog box and add the file to the project. By default, the CommonTasks.xml file will be located in the Documents or My Documents folder at ComponentOne Samples\C1Report\C1Report\XML\CommonTasks.
Note: Report definition files are created with a separate utility, the C1ReportDesigner. The C1ReportDesigner works like the Access report generator, and is the same designer that ships with the C1Report component. The designer lets you create new reports from scratch or import existing ones from Microsoft Access and Crystal Reports. For more information on the C1ReportDesigner, see Working with the C1ReportDesigner in the Reports for WinForms documentation.

7. 8. 9.

Click once on the C1ReportViewer control so that it is selected and navigate to the Properties window. In the Properties window, set the FileName property to "~/CommonTasks.xml". In the Properties window, set the ReportName property to "01: Alternating Background (Greenbar report)". The C1ReportViewer will now display this report at run time.

In this step you added data source to your application and loaded a report into the C1ReportViewer control without using any code. In the next (and last) step you'll run your application and see the C1ReportViewer control in action.

Step 3 of 3: Running the Application

In the previous steps you created and added a report to view in the C1ReportViewer control. In this last step you'll run your application and view the C1ReportViewer control at run time. Complete the following steps:

22

1.

Run your application. The page will look similar to the following:

The C1ReportViewer control displays the 01: Alternating Background (Greenbar report) report in the CommonTasks.XML file. 2. Click the Next arrow button:

Observe that the displayed report moves to the next page. 3. Click an item in the contents, for example Confections:

23

Observe that the C1ReportViewer control now displays that section of the report. 4. Click the Zoom Out button a few times:

Observe that the displayed report appears smaller. 5. Click the Continuous View button:

Now if you scroll through the report, the report scrolls continuously. 6. Click the Save button's drop-down arrow and choose Adobe PDF:

24

A page will open allowing you to save the report as a PDF file. Congratulations, you've completed the ReportViewer for ASP.NET AJAX quick start! You've learned how to add a report definition file to view a report in the C1ReportViewer control. You also explored some of the runtime interactions possible with the control.

25

The C1ReportViewer Control

ReportViewer for ASP.NET AJAX includes the C1ReportViewer control which is a control that allows users to view and browse reports or documents generated by ComponentOne reporting products in a Web application. The viewer's server side code uses C1Report assembly (C1.C1Report.2.dll, the same DLL that is used by ComponentOne Reports for WinForms) to generate documents and reports, and to serve pages to the viewer. The report viewer's class is C1.Web.UI.Controls.C1Report.C1ReportViewer. The viewer shows document and reports using an innovative technology that ComponentOne calls Web Paper. Web Paper technology allows the reports to be displayed with very high fidelity while preserving the ability to select, copy, and search text.
Note: For information about using C1Report and C1PrintDocument, see the Reports for WinForms documentation.

Displaying Reports and Documents

The C1ReportViewer control can show any report or document that can be generated by C1Report. This is specified via the following three public properties on the viewer: FileName: Gets or sets the report or document file name. ReportName: Gets or sets the name of the report. Document: Gets or sets the report or document to view.

The FileName and ReportName properties can be set at design time. The Document property is a run time only property. Note that if it is assigned to a non-null value, the Document property overrides any FileName and ReportName values. The types allowed for the Document property are from C1.C1Report.2.dll and can be: C1.C1Report.C1Report C1.C1Preview.C1PrintDocument A C1Report loaded from an XML file (such as the reports in the CommonTasks.xml sample shipped with C1Report). To specify this type of document, the FileName and ReportName properties should be assigned, while leaving the Document property empty. For example: Visual Basic C1ReportViewer1.FileName = "~/CommonTasks.xml" C1ReportViewer1.ReportName = "Greenbar Report" C# C1ReportViewer1.FileName = "~/CommonTasks.xml"; C1ReportViewer1.ReportName = "Greenbar Report";

The following kinds of documents can be shown by the C1ReportViewer control:

A C1Report generated in memory by user code (such as in the Page_Load event). For example: Visual Basic Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load Dim rep As C1.C1Report.C1Report = Me.C1ReportViewer1.CreateC1Report() rep.Load(MapPath("~/CommonTasks.xml"), "Greenbar Report") Me.C1ReportViewer1.Document = rep End Sub C# protected void Page_Load(object sender, EventArgs e)

27

{ C1.C1Report.C1Report rep = this.C1ReportViewer1.CreateC1Report(); rep.Load(MapPath("~/CommonTasks.xml"), "Greenbar Report"); this.C1ReportViewer1.Document = rep; } A C1PrintDocument loaded from a C1D or C1DX file. To specify this, the FileName property should be set to the name of the .c1d/.c1dx file, for example: Visual Basic C1ReportViewer1.FileName = "~/MyDocument.c1dx" C# C1ReportViewer1.FileName = "~/MyDocument.c1dx";

A C1PrintDocument generated in memory by user code, for example: Visual Basic Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load Dim doc As C1PrintDocument = Me.C1ReportViewer1.CreateC1PrintDocument() doc.Body.Children.Add(New RenderText("Hello World!")) Me.C1ReportViewer1.Document = doc End Sub C# protected void Page_Load(object sender, EventArgs e) { C1PrintDocument doc = this.C1ReportViewer1.CreateC1PrintDocument(); doc.Body.Children.Add(new RenderText("Hello World!")); this.C1ReportViewer1.Document = doc; }

An RDL report loaded from an RDL report definition file. For example: Visual Basic C1ReportViewer1.FileName = "~/MyRdlReport.rdl" C# C1ReportViewer1.FileName = "~/MyRdlReport.rdl";

Note on C1Report/C1PrintDocument Licensing

Note how in the Displaying Reports and Documents (page 27) section, in-memory C1Report and C1PrintDocument objects were created with calls to method on the C1ReportViewer rather than using regular constructors: Visual Basic Dim doc As C1PrintDocument = Me.C1ReportViewer1.CreateC1PrintDocument() Dim rep As C1.C1Report.C1Report = Me.C1ReportViewer1.CreateC1Report() C# C1PrintDocument doc = this.C1ReportViewer1.CreateC1PrintDocument(); C1.C1Report.C1Report rep = this.C1ReportViewer1.CreateC1Report();

Using the CreateC1Report and CreateC1PrintDocument methods ensures that, as long as your C1ReportViewer control is licensed, the instances of C1.C1Report.C1Report and C1.C1Preview.C1PrintDocument classes that you

28

create in this way are also licensed, and you or your users will not see the nag screen about using an unlicensed copy of C1Report. If you simply wrote: Visual Basic Dim doc As New C1PrintDocument() Dim rep As New C1.C1Report.C1Report() C# C1PrintDocument doc = new C1PrintDocument(); C1.C1Report.C1Report rep = new C1.C1Report.C1Report();

chances are that at run time, those calls would have generated nag screens because run-time licenses for C1.C1Report.C1Report and C1.C1Preview.C1PrintDocument were not embedded into the application. So, whenever you need to create an instance of a C1.C1Report.C1Report or a C1.C1Preview.C1PrintDocument in code that you want to assign to the C1DocumentViewer.Document, use the appropriate CreateC1Report or CreateC1PrintDocument method to make sure the created instance is licensed properly.

C1ReportViewer Elements
This section provides a visual and descriptive overview of the elements that comprise the C1ReportViewer control. The C1ReportViewer control consists of several distinct elements. The C1ReportViewer control includes a toolbar, outline and search panes, and a report preview area. At run time the control appears similar to the following image:

This format should be familiar to end-users as it resembles how PDFs appear in viewers such as Adobe Acrobat Reader. The following sections describe each of these sections.

29

C1ReportViewer Toolbar
By default, a toolbar appears at the top of the C1ReportViewer control at run time. The toolbar allows users to print, save, navigate through, and change the display of the report at run time. If you do not want the toolbar to appear you can set the ToolBarVisible property to False. The toolbar appears similar to the following image:

The toolbar includes the following options: Print document: The Print document button opens the Print dialog box where users can print a report. For more information, see Printing a Report (page 35). Save: The Save button allows users to save the report as an Adobe PDF, Open XML Excel, Open XML Word, Microsoft Excel, or Rich Text Format document. See Saving a Report (page 36) for more information. First page: Navigates to the first page of the report. See Navigating a Report (page 38) for more information. Previous page: Navigates to the previous page of the report. See Navigating a Report (page 38) for more information. Page: Indicates the currently selected page and allows users to select a page to view. See Navigating a Report (page 38) for more information. Next page: Navigates to the next page of the report. See Navigating a Report (page 38) for more information. Last page: Navigates to the last page of the report. See Navigating a Report (page 38) for more information. Zoom Out: The Zoom Out button decreases the size of the viewed report. See Zooming a Report (page 37) for more information. Zoom In: The Zoom In button increases the size of the viewed report. See Zooming a Report (page 37) for more information. Current Zoom: Indicates the current zoom level and allows the user to choose from predefined zoom options. See Zooming a Report (page 37) for more information. Continuous View: Lets the user view a report as a continuous series of pages. For more information, see Changing Report Flow (page 37).

For more information about using the toolbar at run time, see Run-Time Interaction (page 34).

C1ReportViewer Outline and Search Panes

By default, two tools panes appear on the left side of the C1ReportViewer control: an Outline pane and a Search pane. The Outline pane functions as a table of contents and lists sections of the displayed report so users can skip to a particular place in the report. The Search pane allows users to search the displayed report for particular works or phrases. The Outline pane of a report appears similar to the following image:

30

By clicking one of these options, users can skip to that section of the report. See Navigating a Report (page 38) for more information. The Search pane appears similar to the following image:

Users can search for a word or phrase at run time and then jump to instances of that word or phrase in the report. For more information, see Searching a Report (page 39).

31

C1ReportViewer Preview Pane

By default, a preview pane appears in the right side of the C1ReportViwer control. The preview pane allows users to view the report that that is currently displayed in the control. For example, the preview pane appears similar to the following image with a report zoomed out and displayed:

Design-Time Support
The following sections describe how to use C1ReportViewer's design-time environment to configure the C1ReportViewer control.

C1ReportViewer Smart Tag

In Visual Studio, the C1ReportViewer control includes a smart tag. A smart tag represents a short-cut tasks menu that provides the most commonly used properties in C1ReportViewer. The C1ReportViewer control provides quick and easy access to common properties through its smart tag. To access the C1ReportViewer Tasks menu, click on the smart tag in the upper-right corner of the C1ReportViewer control. This will open the C1ReportViewer Tasks menu, which appears like the following image:

32

The C1ReportViewer Tasks menu operates as follows: FileName Click the FileName ellipses button to open the Open dialog box to choose a compatiple file to load into the C1ReportViewer control. You can choose an XML, RDL, C1DX, or C1D file. The FileName property will be set to the file you choose. ReportName Once you've chosen a file to open in the FileName box you can select a specific report to view. Click the ReportName drop-down box to set the ReportName property and select a report from the list of available reports to load into the C1ReportViewer control. Zoom The Zoom text box changes the initial zoom value of the report shown in the C1ReportViewer control at run time. Tthe default value is 100%. You can choose a percentage value from the drop-down box, or choose Actual Size, Fit Page, or Fit Width. ToolBarVisible When the ToolBarVisible check box is checked (default) the ToolBarVisible property is set to True and the ReportViewer's toolbar is visible on the C1ReportViewer control at run time. Uncheck the ToolBarVisible check box if you do not want the toolbar displayed. ToolsPaneVisible When the ToolsPaneVisible check box is checked (default) the ToolsPaneVisible property is set to True and the tools pane, which includes the outline and search panes, is visible on the C1ReportViewer control. Uncheck the ToolBarVisible check box if you do not want the tools pane displayed. AvailableTools Check the AvailableTools drop-down box sets the AvailableTools property which determines what tool panes are visible in the C1ReportViewer control at run time. Options include None, Outline, Search, and All (default). VisualStylePath

33

The VisualStylePath property specifies the location of the visual styles used for the control. By default, embedded visual styles are located in ~/C1WebControls/VisualStyles. If you create a custom style, add it to this location ~/VisualStyles/StyleName/C1ReportViewer/styles.css, set the VisualStylePath property to ~/VisualStyles, and set the VisualStyle property to StyleName (assuming that StyleName is the name used to define the style in the style.css file). Uncheck the UseEmbeddedVisualStyles property. UseEmbeddedVisualStyles This check box is checked by default so that the internal visual styles, such as ArcticFox and Vista can be used. If you want to use your own custom styles, uncheck this check box and specify the location of your visual styles using the VisualStylePath property. Visual Style Clicking the Visual Style drop-down box allows you to select from various built-in visual schemes. For more information about available visual styles, see Visual Styles (page 41). About Clicking on the About item displays the About dialog box, which is helpful in finding the version number of ReportViewer for ASP.NET AJAX and online resources.

C1ReportViewer Context Menu

Right-click anywhere on the list to display the C1ReportViewer context menu, which is a context menu that Visual Studio provides for all .NET controls. It will appear similar to the following image:

The context menu commands operate as follows: Show Smart Tag Clicking this item shows the C1ReportViewer Tasks menu. For more information on how to use the smart tag and available features in the Tasks menu, see C1ReportViewer Smart Tag (page 32).

Run-Time Interaction
The following topics detail how to interact with the C1ReportViewer control at run time. You'll learn how users can navigate and interact with displayed reports.
34

Printing a Report
At run time, users can easily print a report by clicking the Print report button in the toolbar:

The Print dialog box will then appear:

The Print dialog box includes the following options: Print Range: Choose whether you want All pages displayed, only Visible pages (default), or only certain Pages. The Subset drop-down box lets you choose to print All pages in range (default), Odd pages only, or Even pages only. The Reverse pages check box lets you choose to reverse the order pages are displayed if selected. Options: Set the Width and Height of the report to print, you can also set the Print DPI to set the quality the report prints at (by default 300). Print Tips: The Print Tips button displays tips for printing reports to help users print documents at run time. Preview: The Preview pane displays the report as it would be printed; if you change settings, the preview will also change. Print: The Print button prints the report to the default printer. Cancel: The Cancel button closes the Print dialog box without printing the report.

35

Printing Tips The following tips will help users when printing documents: Make sure that you have configured the default printer correctly. Print information will be sent to the default system printer immediately when you click Print button. Make sure that preview area contains the correct content; if needed wait until preview area has updated successfully. Setting the Print DPI (dots per inch) to a higher value increases printing quality, but preview download size increases proportionally too; in most cases you will not need DPI value higher than 300. Be aware that content inside the preview area of C1ReportViewer will be printed 'as is'.

Note on printing: while the Print button provides a convenient and quick way to print all or part of a document, it should be understood that it has significant limitations. First, the resolution of the printout is currently fixed at 300 dpi and cannot be changed. But more importantly, anything printed from within a Web browser is subject to the browsers formatting, page headers and footers and so on. So normally, to print the final copy of a document you would probably want to use the Save button (see below) to save it as PDF and print that instead. PDF documents created by C1ReportViewer should be identical in appearance to the documents in the viewer but should print much better as they may be printed avoiding limitations imposed by the Web browser.

Saving a Report
At run time, users can easily save a report by clicking the Save button or the Save button's drop-down arrow in the toolbar:

If you click the Save button's drop-down arrow, a drop-down menu will appear:

The Save drop-down menu includes the following options:

36

Adobe PDF: Saves the report as an Adobe PDF file with the .pdf file extension. This is the default option; if the user click the Save button without selecting an option from the drop-down menu. Open XML Excel: Saves the report as an Open XML Excel file with the .xlsx file extension. Open XML Word: Saves the report as an Open XML Word file with the .docx file extension. Microsoft Excel: Saves the report as a Microsoft Excel file with the .xls file extension. Rich Text Format: Saves the report as a rich text file with the .rtf file extension.

If the user clicks the Save button and not the drop-down arrow, the file is saved as a PDF. Once the user selects a file option, the "Exported document download" page appears allowing users to download the selected file type.

Changing Report Flow

At run time, users can easily change the flow of a report by clicking the Continuous view button on the toolbar:

The Continuous view button changes the way a report is displayed. When selected, the PagedView property is set to False and users can scroll from page to page. When the PagedView property is set to True (default) users must page through the document instead.

Zooming a Report
At run time, users can easily zoom in and out of a report by clicking the Zoom In, Zoom Out, and Current Zoom options on the toolbar:

The Zoom drop-down options on the toolbar include the following: Zoom In: Zooms the document in by 20%. If the document appears at 100% zoom, clicking this button will display the document at 120% zoom. Zoom Out: Zooms the document out by 20%. If the document appears at 100% zoom, clicking this button will display the document at 80% zoom. Current Zoom: Users can enter a value in the Current Zoom combo box, or they can click the drop-down arrow and choose from one of the predefined zoom options:

37

Navigating a Report
At run time, users can navigate through the report document using several navigation options in the C1ReportViewer control. Navigation options include an Outline pane and page navigation buttons on the toolbar. The navigation buttons in the toolbar allow users to move from page to page in the report document and to skip to any specific page in the document:

The Navigation options on the toolbar include the following: First page: Navigates to the first page in the report document. The option is available when any page other than the first page is displayed. Previous page: Navigates to the previous page in the report document. The option is available when any page other than the first page is displayed. Page: Displays the current page and the number of total pages. Users can enter a page number in the text box to navigate to that page. Next page: Navigates to the next page in the report document. The option is available when any page other than the last page is displayed. Last page: Navigates to the last page in the report document. The option is available when any page other than the last page is displayed.

At run time, users can also easily navigate sections of a report by clicking the Outline button in the tools pane:

38

The Outline pane will appear:

The Outline pane lists the sections of a report a user can easily navigate to. Users can click an item in the Outline pane to navigate to the part of the report document.

Searching a Report
At run time, users can easily search a report by clicking the Search button in the tools pane:

39

This will open the Search panel. The Search panel includes the following: Text box: Users can enter a word or phrase in the Search text box to search the report document for that word or phrase. Case sensitive: The Case sensitive check box determines if the text entered should be searched as case sensitive. For example, if this box is checked, searching for "Product" and "product" will product different results. Search: Users can click the Search button to search for the text they entered in the text box. Results: If a search term is found in the document, it will be displayed in the Results window. The results window will list the number of matches found and the pages (with links to those pages) where the term was found.

For example, if the report was searched for the word "chai" the Search pane might appear as in the following image:

40

ReportViewer for ASP.NET AJAX Appearance

There are several options for customizing the appearance and layout of the C1ReportViewer control. The following sections describe how to change the appearance of the control through built-in Visual Styles as well as how to customize other elements of the C1ReportViewer control.

Visual Styles
C1ReportViewer includes Visual Styles allowing you to easily change the control's appearance. The control includes several built-in visual styles, including Vista and Office 2007 styles, to quickly style your application. You can easily change Visual Styles from the C1ReportViewer Tasks menu, the Properties window, in Source view, and in code using the VisualStyle property. For more information on changing Visual Styles see the Setting the Visual Style (page 116) topic. C1ReportViewer includes the following built-in styles: ArcticFox (default) Office2007Black Office2007Blue Office2007Silver Vista

You can view previews of each of these styles below. ArcticFox The ArcticFox visual style is the default visual style and appears similar to the following image:

Office2007Black

41

The Office2007Black visual style appears similar to the following image:

Office2007Blue The Office2007Blue visual style appears similar to the following image:

Office2007Silver The Office2007Silver visual style appears similar to the following image:

42

Vista The Vista visual style appears similar to the following image:

Custom Visual Styles

If you choose to completely customize the appearance of the C1ReportViewer you may not wish to use any of the available built-in Visual Styles. In that case, you can create your own visual style using CSS. To create your own visual style, you will need to do three things: add a custom style sheet to your project, set the UseEmbeddedVisualStyles property to False, and set the VisualStylePath and VisualStyle properties. Step 1: Add a Custom Style Sheet

43

In order to create your own custom style, you must add a style sheet to your project. The VisualStylePath property determines the location of your visual style. The default directory and file name that the VisualStylePath property looks in for custom visual styles is: ~/VisualStyles/StyleName/C1ReportViewer/styles.css (replacing "StyleName" with the name of each style). Step 2: Set the UseEmbeddedVisualStyles Property The UseEmbeddedVisualStyles property allows you to override built-in visual styles with your own custom appearance. By default C1ReportViewer.UseEmbeddedVisualStyles property is True and Visual Styles are used. Any customizations you make while using Visual Styles will simply set specific elements in the control's appearance on top of the current Visual Style. To start customizing the control's appearance from scratch set C1ReportViewer.UseEmbeddedVisualStyles to False and set your own styles. Step 3: Set the VisualStylePath and VisualStyle Properties Once you have created a custom visual style and set the UseEmbeddedVisualStyles to False you must assign the C1ReportViewer control's the VisualStylePath and VisualStyle properties to the visual style directory and the visual style name that you are using. For example, if you add your style sheet to the following location ~/VisualStyles/StyleName/C1ReportViewer/styles.css the VisualStylePath should be set to ~/VisualStyles and the VisualStyle property should be set to StyleName (assuming that StyleName is the name used to define the style in the styles.css file.

Client-Side Functionality
C1ReportViewer includes a robust client-side object model, where a majority of server-side properties can be set on the client-side and client-side events are described in the properties window. When a C1ReportViewer control is rendered, an instance of the client side C1ReportViewer will be created automatically. This means that you can enjoy the convenience of accessing properties and methods of the C1ReportViewer control without having to postback to the server. For example, suppose a C1ReportViewer control with name C1ReportViewer1 is hosted on Web page; when the page is rendered, a corresponding client C1ReportViewer object will be created. Use the following syntax to get the client object: $get("C1ReportViewer1").control OR $find("C1ReportViewer1") By using C1ReportViewer's client-side functionality, you can implement many features in your Web page without the need to take up time by sending information to the Web server. Thus, using client-side methods and events can increase the efficiency of your Web site. The following topics will describe the available client-side methods and events.

Client-Side Properties
The following conventions are used when accessing the client object properties: Server properties on the client are implemented as a pair of Get- and Set- methods. Method names must start with "get_" (Get-method) and "set_" (Set-method) followed with the server property name. The first letter of the server property name must be lowercase (camel case). Visual Basic Dim s As String = C1ReportViewer1.ToolTip C1ReportViewer1.ToolTip = s

For example in the code below the C#, Visual Basic, and JavaScript examples are equivalent:

44

C# string s = C1ReportViewer1.ToolTip; C1ReportViewer1.ToolTip = s; JavaScript var dialog = $get("C1ReportViewer1").control; var s = ReportViewer.get_toolTip(); ReportViewer.set_toolTip(s);

45

Working with C1RdlReport

The C1RdlReport class, a class that represents an RDL (Report Definition Language) report defined using the 2008 version of the RDL specification. The C1RdlReport class is similar to the C1Report class with the addition of RDL support. RDL import in C1PrintDocument (provided by ImportRdl and FromRdl methods) is now obsolete. C1RdlReport should be used instead. Important Notes for .NET 2.0/3.0 version users: The C1.C1Report.2 assembly uses the System.Windows.Forms.DataVisualization.dll assembly that is only included in .NET Framework 3.5 and later. The assembly is installed on your system with when you install ReportViewer for ASP.NET AJAX. It MUST BE INCLUDED with other ComponentOne Reports assemblies when you deploy your application that using ReportViewer for ASP.NET AJAX to other systems. Also, if you update the ReportViewer for ASP.NET AJAX DLLs manually, you MUST put DataVisualization where those assemblies are, and make sure that your project references it. This does not apply to .NET 4.0 users as DataVisualization is already included in the Framework.

Report Definition Language (RDL)

Report Definition Language (RDL) is a Microsoft-standard XML schema for representing reports. The goal of RDL is to promote the interoperability of reporting products by defining a common schema that allows interchange of report definitions. RDL is designed to be output format neutral. This means that reports defined using RDL should be able to be outputted to a variety of formats including Web and print-ready formats or datafocused formats like XML. The C1RdlReport class was added to ReportViewer for ASP.NET AJAX in the 2010 v3 release to leverage the flexibility of RDL files. Using C1RdlReport, you can easily import RDL files into your reporting applications adding flexibility and functionality through the use of the familiar format.

C1RdlReport Advantages
The C1RdlReport control has several advantages over using the standard Microsoft Reporting Services. The major advantages provided by C1RdlReport include: Support for the current RDL 2008 specification. Programmatic access to the RDL object model (which follows the 2008 RDL specification) - this allows you to modify existing or create new RDL reports completely in code. Generation of RDL reports that can consume any data source (such as .mdb files). A self-contained RDL reporting solution without external dependencies such as the need to access a Microsoft Reporting Services server. Seamless integration with other ComponentOne reporting engines including C1Report and C1PrintDocument.

C1RdlReport Limitations
The C1RdlReport control supports most of the features of RDL. However, the initial release of C1RdlReport includes some limitations. The following objects are not supported: Gauge objects are not supported.

47

The following RDL properties are not currently supported: Document.AutoRefresh Document.Width Document.Language Document.DataTransform Document.DataSchema Document.DataElementName Document.DataElementStyle DataSet.CaseSensitivity DataSet.Collation DataSet.AccentSensitivity DataSet.KanatypeSensitivity DataSet.WidthSensitivity DataSet.InterpretSubtotalsAsDetails TextBox.UserSort TextBox.ListStyle TextBox.ListLevel TextRun.ToolTip TextRun.MarkupType

Important Note for .NET 2.0/3.0 version users: The C1.C1Report.2 assembly uses the System.Windows.Forms.DataVisualization.dll assembly that is only included in .NET Framework 3.5 and later. The assembly is installed on your system with when you install ReportViewer for ASP.NET AJAX. It MUST BE INCLUDED with other ComponentOne Reports assemblies when you deploy your application that using ReportViewer for ASP.NET AJAX to other systems. Also, if you update the ReportViewer for ASP.NET AJAX DLLs manually, you MUST put DataVisualization where those assemblies are, and make sure that your project references it. This does not apply to .NET 4.0 users as DataVisualization is already included in the Framework.

Loading an RDL file

To load an RDL file into the C1RdlReport class you can use the Load method. To remove an RDL file, you would use the Clear method. This method clears any RDL file previously loaded into the C1RdlReport control. To load an RDL file in code: To load an RDL file into the C1RdlReport component you can use the Load method: Visual Basic C1RdlReport1.Load("C:/Report.rdl") C1RdlReport1.Render() C# c1RdlReport1.Load(@"C:/Report.rdl"); c1RdlReport1.Render();

48

Working with C1ReportDesigner

The following topics contain important information about C1ReportDesigner, a stand-alone application similar to the report designer in Microsoft Access, including how to create a basic report definition file, modify, print, and export the report definition. This section also demonstrates how to import reports created with Microsoft Access.

About C1ReportDesigner
The C1ReportDesigner application is a tool used for creating and editing C1Report report definition files. The Designer allows you to create, edit, load, and save files (XML) that can be read by the C1Report component. It also allows you to import report definitions from Microsoft Access files (MDB) and VSReport 1.0 (VSR). To run the Designer, double-click the C1ReportDesigner.exe file located by default in the following path: C:\Program Files\ComponentOne\Studio for WPF\C1WPFReport in the Designer or Designer.4 folder. Note that this directory reflects the default installation path and its path may be different if you made changes to the installation path. Here's what the Designer looks like with the CommonTasks.xml file opened:

The main Designer window has the following components:

49

Application button: Click the application button to open a menu to load and save report definition files and to import and export report definitions. See Application Button (page 50) for more information. Design tab: Provides shortcuts to the Edit, Font, Data, Fields, and Tools menu functions. See Design Tab (page 51) for more information. Arrange tab: Provides shortcuts to the Edit, AutoFormat, Grid, Control Alignment, Position, and Size menu functions. See Arrange Tab (page 56) for more information. Page Setup tab: Provides shortcuts to the Edit and Page Layout menu functions. See Page Setup Tab (page 59) for more information. Preview tab: Appears only when the report is being viewed in a print preview. See Preview Tab (page 60) for more information. Help button: Provides options to open the online help file and view the About screen, which displays information about the application. Reports tab: Lists all reports contained in the current report definition file. You can double-click a report name to preview or edit the report. You can also use the list to rename, copy, and delete reports. Fields tab: Lists all the fields contained in the current report. Properties tab: Allows you to edit properties for the objects that are selected in the Designer. Pages tab: Only available when in preview mode, this tab includes thumbnails of all the pages in the document. Properties tab: Only available when in preview mode, this tab displays a text outline of the document. Find tab: Only available when in preview mode, this tab displays fine pane allowing you to search for text in the document. Preview/Design pane: This is the main working area of the Designer. In preview mode, it displays the current report. In design mode, it shows the report's sections and fields and allows you to change the report definition. Status bar: The status bar displays information about what the Designer is working on (for example, loading, saving, printing, rendering, importing, and so on). You can zoom in and out of a selected report by dragging the zoom slider at the right of the status bar.

The topics that follow explain how you can use the C1ReportDesigner application to create, edit, use, and save report definition files.

Application Button
The Application button provides a shortcut menu to load and save report definition files and to import and export report definitions. You can also access the C1ReportDesigner application's options through the Application menu. Click the Application button to open the menu. It will appear similar to the following:

50

The menu includes the following options: New: Creates a new report definition file. Open: Brings up the Open Report Definition File dialog box, enabling you to select an existing file to open. Close: Closes the current report definition file. Save: Saves the report definition file, to the location previously saved. Save As: Opens the Save Report Definition dialog box allowing you to save your report definition as an XML file. Import: Opens the Import Report Definition dialog box enabling you to import Microsoft Access (.mdb and .adp) files and Crystal Reports (.rpt) files. See Importing Microsoft Access Reports (page 90) and Importing Crystal Reports (page 94) for more information. Export: Exports the current report file as an HTML, PDF, RTF, XLS, XLSX, TIF, TXT, or ZIP file. Recent files: Lists recently opened report definition files. To reopen a file, select it from the list. Options: Opens the C1ReportDesigner Options dialog box which allows you to customize the default appearance and behavior of the C1ReportDesigner application. See Setting C1ReportDesigner Options (page 66) for more information. Exit: Closes the C1ReportDesigner application.

Design Tab
The Design tab is located in the C1ReportDesigner's Ribbon menu and provides shortcuts to the Edit, Font, Data, Fields, and Tools menu functions. For more information, see the following topics.

51

Edit Group
The Edit group on the Design tab appears similar to the following:

It consists of the following options: Preview: The Preview button opens a print preview view of the report. To exit the preview, click the Close Print Preview button. See Preview Tab (page 60) and Previewing and Printing a Report (page 87) for more information. Paste: Pastes the last copied item. Cut: Cuts the selected item, removing it from the report and allowing it to be pasted elsewhere. Copy: Copies the selected item so that it can be pasted elsewhere. Undo: Undoes the last change that was made to the report definition. Redo: Redoes the last change that was made to the report definition.

Font Group
The Font group on the Design tab appears similar to the following:

And consists of the following options: Font Name: Displays the current font of the selected text and allows you to choose another font for the selected item (to do so, click the drop-down arrow next to the font name). Font Size: Displays the current font size of the selected text and allows you to choose another font size. Type a number in the font size box or click the drop-down arrow to choose a font size. Increase Font Size: Increases the font size by one point. Decrease Font Size: Decreases the font size by one point. Bold: Bold the selected text (you can also press CTRL+B). Italic: Italicizes the selected text (you can also press CTRL+I). Underline: Underlines the selected text (you can also press CTRL+U). Left: Aligns text to the left. Center: Aligns text to the center.

52

Right: Aligns text to the right. Justify: Justifies the selected text. Text Color: Allows you to select the color of the selected text. Fill Color: Allows you to select the background color of the selected text.

Data Group
The Data group appears similar to the following image:

And consists of the following items: Sorting and grouping: Clicking this button opens the Sorting and Grouping dialog box where you can add and delete sorting and grouping criteria. Data Source: Clicking this button opens the Select a Data Source dialog box. The Select a Data Source dialog box allows you to choose a new data source, change the connection string, and edit the SQL statement. Clicking the Data sources radio button displays the tables and views in the current data source. Clicking the Sql statement radio button allows you to view the current SQL statement:

53

To select change the connection string, click the ellipses button. This will open the Data Link Properties dialog box. To open an XML Schema Definition file (XDS) click the Open button. To edit or change the SQL statement, click the Build SQL Statement button which will open the Sql Builder dialog box. Report Info: Opens the Report Information dialog box. This dialog box allows you to set the report's Title, Author, Subject, Creator, and Keywords. You can also choose to apply report information to all reports.

Fields Group
The Fields group of the Design tab in the C1ReportDesigner application provides tools for creating report fields. This toolbar is enabled only in design mode. The Fields group on the Design tab appears similar to the following:

Each field button creates a field and initializes its properties. The Fields group consists of the following options: Arrow: Returns the mouse cursor to an arrow cursor. Data Field: Creates a field that is bound to the source recordset. When you click this button, a menu appears and you can select the recordset field. Bound fields are not limited to displaying raw data from the database. You can edit their Text property and use any VBScript expression. Label: Creates a field that displays static text.

54

Add CheckBox ( ): Creates a bound field that displays a Boolean value as a check box. By default, the check box displays a regular check mark. You can change it into a radio button or cross mark by changing the value of the field's Checkbox property after it has been created. Add BarCode ( ): Creates a field that displays a barcode. When you click this button, a menu appears where you can select other fields that are contained in the same report definition file to be displayed as a barcode. Add Rtf Field ( ): Creates an RTF field. When you click this button, a menu appears where you can select other fields that are contained in the same report definition file to be displayed in RTF format. Add Calculated Field ( ): Creates a calculated field. When you click this button, the code editor dialog box appears so you can enter the VBScript expression whose value you want to display. Add Common Calculated Field ( ): Creates a field with a commonly used expression. When you click this button, a menu appears and you can select expressions that render the date or time when the report was created or printed, the page number, page count, or "page n of m", or the report name. Add Unbound Picture ( ): Creates a field that displays a static picture, such as a logo. When you click this button, a dialog box appears to prompt you for a picture file to insert in the report. A copy is made of the picture you select and placed in the same directory as the report file. You must distribute this file with the application unless you embed the report file in the application. When you embed a report file in your application, any unbound picture files are embedded too. Add Bound Picture ( ): Creates a field that displays a picture (or object) stored in the recordset. When you click this button, a menu appears so you can select a picture field in the source recordset (if there is one; not all recordsets contain this type of field). Add Line ( ): Creates a line. Lines are often used as separators. Add Rectangle ( ): Creates a rectangle. Rectangles are often used to highlight groups of fields or to create tables and grids. Add SubReport ( ): Creates a field that displays another report. When you click this button, a menu appears and you can select other reports that are contained in the same report definition file. See Creating a Master-Detail Report Using Subreports (page 83) for more information. Add Page Break ( ): Creates a field that inserts a page break.

Add Chart Field ( ):Creates a field that displays a chart. Unlike most bound fields, Chart fields display multiple values. To select the data you want to display, set the Chart field's Chart.DataX and Chart.DataY properties. To format the values along the X and Y axis, set the Chart.FormatX and Chart.FormatY properties. Add Gradient Field ( ): Creates a gradient field. Gradients are often used as a background feature to make other fields stand out. See Adding Gradient Fields (page 80) for more information.

See Enhancing the Report with Fields (page 76) for more information.

Tools Group
The Tools group on the Design tab appears similar to the following:

55

It consists of the following options: Property Grid: Selecting this item brings the Properties tab into view on the left pane. Note that you can also use F4 to view the Properties tab. Field List: Selecting this item brings the Fields tab into view on the left pane. Zoom: Allows you to select a value to set the zoom level of the report.

Arrange Tab
The Arrange tab is located in the C1ReportDesigner's Ribbon menu and provides shortcuts to the Edit, AutoFormat, Grid, Control Alignment, Position, and Size menu functions. See Edit Group (page 52) for information about that group, and the following topics for the other groups.

AutoFormat Group
The AutoFormat Group on the Arrange tab of the Ribbon appears similar to the following image:

The AutoFormat group consists of the following options: Styles: Opens the Report Style Editor dialog box, where you can choose a built-in style or create and edit your own custom style. Apply Style: Applies style to the current selection. As Table Row: Formats the current selection as a table row.

Report Style Editor You can access the Report Style Editor dialog box by clicking the Styles button of the AutoFormat group. The Report Style Editor dialog box appears similar to the following image:

56

It includes several elements including: Style Gallery List: The Style Gallery list displays all the currently available built-in and custom styles. See Style Gallery (page 63) for information about the available built-in styles. Add Button: The Add button adds a custom style to the Style Gallery list. The style that is added will be based on the style that was selected in the Style Gallery list when the Add button was clicked. Remove Button: The Remove button removes a selected custom style. The button is only available when a custom style is selected in the Style Gallery list. Property Grid: The Property grid lets you change the properties and edit a custom style. The Property grid is only available and editable when a custom style is selected in the Style Gallery list. Preview Window: The Preview window displays a preview of the style selected in the Style Gallery list. Apply Button: Clicking the Apply button applies the style to your selection without closing the dialog box. OK Button: Clicking the OK button closes the dialog box, applies your changes, and sets the style you choose as the current selected style. Cancel Button: Clicking the Cancel button allows you to cancel any changes you've made to styles.

Grid Group
The Grid group on the Arrange tab of the Ribbon appears similar to the following image:

57

The Grid group consists of the following buttons: Grid Properties: Opens the C1ReportDesigner Options dialog box. For details see Setting C1ReportDesigner Options (page 66). Snap to Grid: Snaps elements to the grid. When this item is selected elements cannot be placed in between lines of the grid. Show Grid: Shows a grid in the background of the report in the preview. The grid can help you place and align elements. By default, this option is selected. Lock Fields: After you've placed the fields in the desired positions, you can lock them to prevent inadvertently moving them with the mouse or keyboard. Use the Lock Fields button to lock and unlock the fields.

Control Alignment Group

The Control Alignment group on the Arrange tab of the Ribbon appears similar to the following image:

The Control Alignment group consists of the following options: Left: Horizontally aligns the selected item to the left. Right: Horizontally aligns the selected item to the right. Center: Horizontally aligns the selected item to the center. Top: Vertically aligns the selected item to the top. Bottom: Vertically aligns the selected item to the bottom. Middle: Vertically aligns the selected item to the middle.

Items can be both horizontally and vertically aligned so, for example, an item can be both aligned to the left and the top.

Position Group
The Position group on the Arrange tab of the Ribbon controls spacing between elements and how elements are layered. It appears similar to the following image:

58

The Position group consists of the following options: Bring to Front: Brings the selected item to the front, in front of all layered items. Send to Back: Sends the selected item to the back, behind all layered objects. Equal Horizontal: Provides equal horizontal spacing between elements. Increase Horizontal: Increases the horizontal spacing between elements. Decrease Horizontal: Decreases the horizontal spacing between elements. Equal Vertical: Provides equal vertical spacing between elements. Increase Vertical: Increases the vertical spacing between elements. Decrease Vertical: Decreases the vertical spacing between elements.

Size Group
The Size group on the Arrange tab of the Ribbon controls how elements are aligned and sized. It appears similar to the following image:

The Size group consists of the following options: To Grid: Aligns the selected items to the grid. To Tallest: Sets the height of all selected elements to the tallest selected item. To Shortest: Sets the height of all selected items to the shortest selected item. Size To Grid: Sizes the selected items to the grid. To Widest: Sets the width of all selected items to the width of the widest selected item. To Narrowest: Sets the width of all selected items to the width of the narrowest selected item.

Page Setup Tab

The Page Setup tab is located in the C1ReportDesigner's Ribbon menu and provides shortcuts to the Edit and Page Layout menu functions. See Edit Group (page 52) and Page Layout Group (page 59) for more information.

Page Layout Group

The Page Layout group on the Page Setup tab of the Ribbon appears similar to the following image:

59

The Page Layout group consists of the following options: Portrait: Changes the layout of your report to Portrait view (where the height is longer than the width). Landscape: Changes the layout of your report to Landscape view (where the height is shorter than the width). Page Setup: Opens the printers Page Setup dialog box.

Preview Tab
The Preview tab is located in the C1ReportDesigner's Ribbon menu and provides shortcuts to the Print, Page Layout, Zoom, Navigation, Tools, Export, and Close Preview menu functions. To access the Preview tab and a print preview of your report, click the Preview option located in the Edit group of the Ribbon. See Edit Group (page 52) for more information. See Page Layout Group (page 59) for information about that group, and the following topics for the other groups in the Preview tab.

Print Group
The Print group on the Preview tab of the Ribbon appears similar to the following image:

The Print group consists of the Print option. Clicking the Print option opens your printer options for printing the report.

Zoom Group
The Zoom group on the Preview tab of the Ribbon controls how the print preview is zoomed and appears similar to the following image:

60

The Zoom group consists of the following options: One page: Allows you to preview one page at a time. Two pages: Allows you to preview two pages at a time. More pages: Clicking the drop-down arrow allows you to preview multiple pages at a time and includes the following options: Four pages, Eight pages, Twelve pages. Zoom: Zooms the page in to a specific percent or to fit in the window.

Navigation Group
The Navigation group on the Preview tab of the Ribbon controls how the print preview is navigated and appears similar to the following image:

The Navigation group consists of the following options: First page: Navigates to the first page of the preview. Previous page: Navigates to the previous page of the preview. Page: Entering a number in this textbox navigates the preview to that page. Next page: Navigates to the next page of the preview. Last page: Navigates to the last page of the preview. History Back: Returns to the last page viewed. History Next: Moves to the next page viewed. This is only visible after the History Back button is clicked.

Tools Group
The Tools group on the Preview tab of the Ribbon contains tools for selecting and locating items in the preview and appears similar to the following image:

The Tools group consists of the following buttons: Hand Tool: The hand tool allows you to move the preview through a drag-and-drop operation. Text Select Tool: The text select tool allows you to select text through a drag-and-drop operation. You can then copy and paste this text to another application.

61

Find: Clicking the Find option opens the Find pane where you can search for text in the document. To find text enter the text to find, choose search options (if any), and click Search:

You can click a search result to locate it in the document.

Export Group
The Export group on the Preview tab of the Ribbon contains options for exporting the report to various formats and appears similar to the following image:

Each item in the Export group opens the Export Report to File dialog box where you can choose a location for your exported file. The Export group consists of the following options: Pdf: Exports the document to a PDF file. The drop-down arrow includes options for PDF (system fonts) and PDF (embedded fonts) to choose if you want to use system fronts or embed your chosen fonts in the PDF file. Html: Exports the document to an HTML file. You can then copy and paste this text to another application. The drop-down arrow includes options for Plain HTML, Paged HTML, and Drilldown HTML allowing you to choose if you want to export to a plain HTML file, multiple HTML files that can be paged using included arrow links, or an HTML file that displays content that can be drilled down to. Excel: Exports the document to a Microsoft Excel file. The drop-down arrow includes options for Microsoft Excel 97 and Microsoft Excel 2007 OpenXML allowing you to choose if you want to save the document as an XLS or XLSX file.

62

Rtf: Exports the document to a Rich Text File (RTF). Text: Exports the document to a Text file (TXT). More: Clicking the More drop-down arrow includes additional options to export the report including: Tagged Image File Format (export as TIFF), RTF (fixed positioning), Single Page Text, Compressed Metafile (export as ZIP).

Close Preview Group

The Close Preview group on the Preview tab of the Ribbon appears similar to the following image:

It includes just one button, Close Print Preview, enabling you to close the preview view and return to the design view. To return to the Review view again, click the Preview button in the Edit group.

Style Gallery
The Style Gallery dialog box details all the available built-in and custom styles that you can use to format your report. Built-in styles include standard Microsoft AutoFormat themes, including Vista and Office 2007 themes. You can access the Style Gallery from the C1ReportDesigner application by selecting the Arrange tab and clicking Styles. The following built-in styles are included:
Style Name Access 2007 Preview Style Name Oriel Preview

Access 2003

Origin

Apex

Paper

63

Aspect

Solstice

Civic

Technic

Concourse

Trek

ComponentOne

Urban

Equity

Verve

Flow

Windows Vista

Foundry

Bold

64

Median

Casual

Metro

Compact

Module

Corporate

None

Formal

Northwind

Soft Gray

Office

Verdana

Opulent

WebReport

65

Setting C1ReportDesigner Options

To access the C1ReportDesigner Options dialog box, click the Application button and then Options. For more information about the Application button, see Application Button (page 50). The C1ReportDesigner Options dialog box appears similar to the following image:

The C1ReportDesigner Options dialog box includes options to control the appearance and behavior of the application. Options include: Categorize property grid: Categorizes the Properties grid by property type. The Properties grid can be accessed by clicking the Properties tab located in the bottom of the left pane in Design view. Filter field properties: Filters the Properties grid by properties that have been set. The Properties grid can be accessed by clicking the Properties tab located in the bottom of the left pane in Design view. Enable undo/redo: Enables undo and redo in the application. Sort report list: Sorts the list of reports listed on the Reports tab. Reports can be accessed by clicking the Reports tab located in the bottom of the left pane in Design view. Show Grid: Shows the grid in the report preview window. Snap to Grid: Snaps all objects the grid in the report. If this option is selected, you will not be able to place objects between grid lines. Grid Units: Indicates how the grid is spaced. Options include Automatic, English (in), Metric (cm), and Custom. Grid Spacing: Sets the spacing of grid lines. This option is only available when the Grid Units option is set to Custom. Grid major color: Set the color of major grid lines.

66

Grid minor color: Sets the color of minor grid lines. Field edges color: Sets the color of field edges in the report. Show Subreport Content: Shows sub-report content in the report. Reload last file on Startup: If this option is checked, the last opened file will appear whenever the C1ReportDesigner application is opened. Embed images into Xml when saving: When the report is saved, images will be embedded into XML if this option is checked. Save changes before rendering: Checking this option saves the report before rendering. Default Export Format: Sets the default export format. For more information about exporting see Export Group (page 62). Auto Syntax Checking: Determines if syntax is automatically checked in the VBScript Editor dialog box. Syntax Coloring: Determines if syntax text is automatically colored in the VBScript Editor dialog box. Font: Defines the appearance of the text used in the VBScript Editor dialog box. OK: Click OK to save your changes. Cancel: Click Cancel to cancel any changes that you have made.

Creating a Basic Report Definition

You can design your report to display your data in a variety of ways on the printed page. Using the C1ReportDesigner application, you can design comprehensive lists, summaries, or special subsets of data, like an invoice. The easiest way to start a new report is to use the C1Report Wizard. In the C1Report Wizard click the Application button and select New from the menu to create a new report. To access the C1Report Wizard, click the New Report button from the Reports tab:

The C1Report Wizard appears, and will guide you through five easy steps: 1. Select the data source for the new report. Use this page to select the ConnectionString and RecordSource that will be used to retrieve the data for the report.

67

You can specify the ConnectionString in three ways: Type the string directly into the editor. Use the drop-down list to select a recently used connection string (the Designer keeps a record of the last eight connection strings). Click the button with the ellipsis button () to bring up the standard connection string builder. Click the Table option and select a table from the list. Click the SQL option and type (or paste) an SQL statement into the editor.

You can specify the RecordSource string in two ways:

2. Select the fields you want to include in the report. This page contains a list of the fields available from the recordset you selected in Step 1, and two lists that define the group and detail fields for the report. Group fields define how the data will be sorted and summarized, and detail fields define what information you want to appear in the report. You can move fields from one list to another by dragging them with your mouse pointer. Drag fields into the Detail list to include them in the report, or drag within the list to change their order. Drag fields back into the Available list to remove them from the report.

68

3. Select the layout for the new report. This page offers you several options to define how the data will be organized on the page. When you select a layout, a thumbnail preview appears on the left to give you an idea of what the layout will look like on the page. There are two groups of layouts, one for reports that have no groups and one for reports with groups. Select the layout that best approximates what you want the final report to look like. This page also allows you to select the page orientation and whether fields should be adjusted to fit the page width. The Labels layout option is used to print Avery-style labels. If you select this option, you will see a page that prompts you for the type of label you want to print.

69

4. Select the style for the new report. Style Layouts This page allows you to select the style that will be used in the new report. Like the previous page, it shows a preview to give you an idea of what each style looks like. Select the one that you like best (and remember, you can refine it and adjust the details later).

70

Label Layout Only This page allows you to select the type of label you want to create. The Designer has over 170 predefined label types for you to choose from. The labels are divided into four groups, depending on whether they use metric or English measurements, and on the type of paper they use (sheets or continuous forms).

71

5. Select a title for the new report. This last page allows you to select a title for the new report and to decide whether you would like to preview the new report right away or whether you would like to go into edit mode and start improving the design before previewing it.

72

If you choose to preview the report and click finish, you will immediately see the report in the preview pane of the Designer. It should look like this:

73

Modifying the Report Layout

The report generated for you by the wizard is a good starting point, but you will usually need to adjust and enhance it to get exactly what you want. You can do this with the C1ReportDesigner application. To start using the Designer, click the Close Print Preview button in the Close Preview group of the Preview tab:

The right pane of the main window switches from Review mode into Design mode, and it shows the controls and fields that make up the report:

74

The picture shows how the report is divided into sections (Header, Page Header, Detail, and so on). The sections contain fields that hold the labels, variables, and expressions that you want in the printed report. In this example, the Header section contains a label with the report title. The Page Header section contains labels that identify the fields in the Detail section, and the Page Footer section contains fields that show the current time, the page number and the total page count for the report. The sections of the report determine what each page, group, and the beginning and end of the report look like. The following table describes where each section appears in the report and what it is typically used for:
Section Report Header Appears Once per report Typically Contains The report title and summary information for the whole report. Labels that describe detail fields, and/or page numbers. Fields that identify the current group, and possibly aggregate values for the group (for example, total, percentage of the grand total). Fields containing data from the source recordset. Aggregate values for the group. Page number, page count, date printed, report name. Summary information for the whole report.

Page Header Group Header

Once per page Once per group

Detail Group Footer Page Footer Report Footer

Once per record Once per group Once per page Once per report

75

Note that you cannot add and delete sections directly. The number of groups determines the number of sections in a report. Every report has exactly five fixed sections (Report Header/Footer, Page Header/Footer, and Detail) plus two sections per group (a Header and Footer). You can hide sections that you don't want to display by setting their Visible property to False. You can modify sections by changing their properties with the Properties window, or move and resize them with the mouse. Resizing a Section To resize a section, select its border and with your mouse pointer drag to the position where you want it. The rulers on the left and on top of the design window show the size of each section (excluding the page margins). Note that you cannot make the section smaller than the height and width required to contain the fields in it. To reduce the size of a section beyond that, move or resize the fields in it first, then resize the Section. To see how this works, move the mouse to the area between the bottom of the Page Header section and the gray bar on top of the Detail Section. The mouse cursor changes to show that you are over the resizing area. Click the mouse and drag the line down until the section is about twice its original height.

Release the mouse button and the section is resized.

Enhancing the Report with Fields

To enhance your report, you can add fields (for example, lines, rectangles, labels, pictures, charts, and so on) to any Section. You can also modify the existing fields by changing their properties with the Properties window, or move and resize the fields with the mouse. Report Fields The Fields group of the Design tab in the C1ReportDesigner application provides tools for creating report fields. This toolbar is enabled only in design mode. Each button creates a field and initializes its properties. For more information about the Fields group, see Fields Group (page 54).

Adding Chart Fields

Chart fields are implemented using the C1Chart control.
Note: You must deploy the C1Chart assembly with your application if you use charts.

To add a Chart field to your report, complete the following steps: 1. 2. Open the report in the C1ReportDesigner application. Click the Add Chart Field button should be displayed. in the toolbar, and mark the area in the report where the Chart

76

3.

Then set the field properties as usual.

The only unusual aspect of Chart fields is that unlike most bound fields, they display multiple values. To select the data you want to display, set the Chart field's Chart.DataX and Chart.DataY properties. To format the values along the X and Y axis, set the Chart.FormatX and Chart.FormatY properties. You can also customize the chart appearance by setting other properties such as Chart.ChartType, Chart.Palette, and so on. To create a new report with an embedded chart, use the C1Report Wizard. Complete the following steps: 1. Select the data source for the new report. a. Click the Build a connection string ellipses button (). The Data Link Properties dialog box appears.

Select the Provider tab and then select Microsoft Jet 4.0 OLE DB Provider from the list. Click Next. In the Connection page, click the ellipsis button to browse for the Nwind.mdb database. This is the standard Visual Studio Northwind database. By default, the database is installed in the ComponentOne Samples\Common directory. Select the Tables radio button, and then select the Sales by Category view. The following image shows this step:

2. Select the fields you want to display.

77

This example groups the data by Category and show ProductName and ProductSales in the Detail section of the report: To add groups and detail fields, with your mouse pointer drag them from the Available list on the left to the Groups or Detail lists on the right:

Continue clicking Next until the wizard is done. The wizard creates the initial version of the report. 3. Add the Chart to the Group Header section of the report. Charts usually make sense in the Group Header sections of a report, to summarize the information for the group. To add the chart to the Group Header section: a. Click the Close Print Preview button in the Close Preview group to switch to Design mode to begin editing the report.

Expand the Group Header Section by performing a drag-and-drop operation with the section's borders. Then click the Add Chart Field button Group Header Section. in the Fields group of the Design tab and place the field in the report in the

Resize the chart by clicking and dragging the chart field. From the Properties window, set the Chart.DataY property to the name of the field that contains the values to be charted, in this case, ProductSales.

78

Note that the Chart.DataY property may specify more than one chart series. Just add as many fields or calculated expressions as you want, separating them with semicolons. Also set the Chart.DataX property to the name of the field that contains the labels for each data point, in this case, ProductName. From the Properties window, set the Chart.FormatY property to "#,###" to set the values along the axis to thousandseparated values. The Chart control will now display some sample data so you can see the effect of the properties that are currently set (the actual data is not available at design time). You may want to experiment changing the values of some properties such as Chart.ChartType, Chart.DataColor, and Chart.GridLines. You can also use the regular field properties such as Font and ForeColor. Your report should look similar to the following report:

Click the Preview button to see the report and click the Next page button to scroll through the report to view the Chart field for each group. The sample report should look like the following image:

79

Note that the Report field is sensitive to its position in the report. Because it is in a Group Header section, it only includes the data within that group. If you place the Chart field in a Detail section, it will include all the data for the entire report. This is not useful because there will be one chart in each Detail section and they will all look the same. If you need more control over what data should be displayed in the chart, you can use the DataSource property in the chart field itself. You can now save the report and use it in your reporting applications.

Adding Gradient Fields

Gradient fields are much simpler than charts. They are mainly useful as a background feature to make other fields stand out. The following image shows a report that uses gradient fields over the labels in the Group Header section:

80

To create a similar gradient field, complete the following steps: 1. 2. 3. 4. In Design mode of the Designer, select the Add Gradient Field button Design tab. from the Fields group in the

Move your mouse cursor (which has changed to a cross-hair) over the labels in the Group Header section and drag the field to the desired size. To ensure that the field is behind the labels, right-click the gradient field and select Send To Back. Then set the Gradient.ColorFrom and Gradient.ColorTo properties to SteelBlue and White, respectively.

Note that you may change the angle of the gradient field by setting the Gradient.Angle property another value (default value is 0).

Selecting, Moving, and Copying Fields

You can use the mouse to select fields in the C1ReportDesigner application as usual: Click a field to select it. Shift-click a field to toggle its selected state. Control-drag creates a copy of the selected fields. Click the empty area and drag your mouse pointer to select multiple fields. With your mouse pointer, drag field corners to resize fields. Double-click right or bottom field corners to auto size the field.

81

To select fields that intersect vertical or horizontal regions of the report, click and drag the mouse on the rulers along the edges of the Designer. If fields are small or close together, it may be easier to select them by name. You can select fields and sections by picking them from the drop-down list above the Properties window. Show a grid The Snap to grid and Show grid buttons located in the Grid group in the Appearance tab provide a grid that helps position controls at discrete positions. While the grid is on, the top left corner of the fields will snap to the grid when you create or move fields. You can change the grid units (English or metric) by clicking the Application button and selecting Options from the menu.

Lock fields After you have placed fields in the desired positions, you can lock them to prevent inadvertently moving them with the mouse or keyboard. Use the Lock Fields button to lock and unlock the fields. Format fields

When multiple fields are selected, you can use the buttons on the Control Alignment, Position, and Size groups of the Appearance tab to align, resize, and space them. When you click any of these buttons, the last field in the selection is used as a reference and the settings are applied to the remaining fields in the selection. Apply styles

The Apply Style to Selection button applies the style of the reference field to the entire selection. The style of a field includes all font, color, line, alignment, and margin properties. You can use the Properties window to set the value of individual properties to the entire selection. Determine order for overlapping fields

82

If some fields overlap, you can control their z-order using the Bring to Front/Send to Back buttons in the Position group. This determines which fields are rendered before (behind) the others. Move fields using the keyboard The C1ReportDesigner application also allows you to select and move fields using the keyboard: Use the TAB key to select the next field. Use SHIFT-TAB to select the previous field. Use the arrow keys to move the selection one pixel at a time (or shift arrow to by 5 pixels). Use the DELETE key to delete the selected fields. When a single field is selected, you can type into it to set the Text property.

Changing Field, Section, and Report Properties

Once an object is selected, you can use the Properties window to edit its properties. When one or more fields are selected, the Properties window shows property values that all fields have in common, and leaves the other properties blank. If no fields are selected and you click on a section (or on the bar above a section), the Section properties are displayed. If you click the gray area in the background, the Report properties are displayed. To see how this works, click the label in the Header section and change its Font and ForeColor properties. You can also change a field's position and dimensions by typing new values for the Left, Top, Width, and Height properties. The Properties window expresses all measurements in twips (the native unit used by C1Report), but you can type in values in other units (in, cm, mm, pix, pt) and they will be automatically converted into twips. For example, if you set the field's Height property to 0.5in, the Properties window will convert it into 720 twips.

Changing the Data Source

The data source is defined by the ConnectionString, RecordSource, and Filter properties. These are regular Report properties and may be set one of the following ways: From the Properties window, select the ellipsis button next to the DataSource property (if you click the gray area in the background, the Report properties are displayed). OR Click the DataSource button in the Data group of the Design tab to open the Select a Data Source dialog box that allows you to set the ConnectionString and RecordSource properties directly.

Creating a Master-Detail Report Using Subreports

Subreports are regular reports contained in a field in another report (the main report). Subreports are usually designed to display detail information based on a current value in the main report, in a master-detail scenario. In the following example, the main report contains categories and the subreport in the Detail section contains product details for the current category:

83

To create a master-detail report based on the Categories and Products tables, you need to create a Categories report (master view) and a Products report (details view). Step 1: Create the master report 1. Create a basic report definition (page 67) using the C1Report Wizard. a. Select the Categories table from the Northwind database (Nwind.mdb located in the ComponentOne Samples\Common folder).

Include the CategoryName and Description fields in the report. 2. 3. 4. 5. In the C1ReportDesigner application, click the Close Print Preview button to begin editing the report. Set the Page Header and Header section's Visible property to False. In the Detail section, select the DescriptionCtl and move it directly below the CategoryNameCtl. Use the Properties window to change the Appearance settings (Font and ForeColor). Note that for this example, a Gradient field was added to the Detail Section. For information on Gradient fields, see Adding Gradient Fields (page 80). Select the Preview button, the Categories report should now look similar to the following image:

6.

84

Step 2: Create the detail report 1. In the C1ReportDesigner application, click the New Report button to create a basic report definition (page 67) using the C1Report Wizard. a. Select the Products table from the Northwind database.

Include the following fields in the report: ProductName, QuantityPerUnit, UnitPrice, UnitsInStock, and UnitsOnOrder. 2. In the Report Designer, click the Close Print Preview button to begin editing the report. a. Set the Page Header and Header section's Visible property to False.

In the Detail section, arrange the controls so that they are aligned with the heading labels. Use the Properties window to change the Appearance settings. Step 3: Create the subreport field The C1ReportDesigner application now has two separate reports, Categories Report and Products Report. The next step is to create a subreport: 1. 2. From the Reports list in the Designer, select Categories Report (master report). In design mode, from the click the Add Subreport button in the Fields group of the Design tab and select Products Report from the drop-down menu.

85

3.

In the Detail section of your report, click and drag the mouse pointer to make the field for the subreport:

Step 4: Link the subreport to the master report The master-detail relationship is controlled by the Text property of the subreport field. This property should contain an expression that evaluates into a filter condition that can be applied to the subreport data source. The Report Designer can build this expression automatically for you. Complete the following steps: 1. Right-click the subreport field and select Link Subreport from the menu.

2.

A dialog box appears that allows you to select which fields should be linked.

86

3.

Once you make a selection and click OK, the Report Designer builds the link expression and assigns it to the Text property of the subreport field. In this case, the expression is: "[CategoryID] = '" & [CategoryID] & "'" From the Properties window, click the Text property of the subreport field and select Script Editor from the drop-down list.

Alternatively, you can also link the subreport to the master report by completing the following steps: 1.

2. 3.

Enter the following expression in the VBScript Editor: "[CategoryID] = '" & [CategoryID] & "'" Click OK to close the VBScript Editor and build the expression.

Previewing and Printing a Report

To preview a report, select the report to view from the Reports list on the left pane of the Designer window and click the Preview button, which appears on each Ribbon tab:

87

Alternatively, you can select View | Preview from the menu. The report is displayed on the right pane, as shown in the following screen shot:

The main window has a preview navigation toolbar, with buttons that let you page through the document and select the zoom mode. At this point, you can print the report by clicking the Print button:

88

Exporting and Publishing a Report

Instead of printing the report, you may want to export it into a file and distribute it electronically to your clients or co-workers. The Designer supports the following export formats:
Format Paged HMTL (*.htm) Description Creates one HTML file for each page in the report. The HTML pages contain links that let the user navigate the report. Creates a single HTML file with sections that can be collapsed and expanded by the user by clicking on them. Creates a single HTML file with no drill-down functionality. Creates a PDF file that can be viewed on any computer equipped with Adobe's Acrobat viewer or browser plug-ins. Creates a PDF file with embedded font information for extra portability. This option significantly increases the size of the PDF file. Creates an RTF file that can be opened by most popular word processors (for example, Microsoft Word, WordPad). Creates an RTF file with fixed positioning that can be opened by most popular word processors (for example, Microsoft Word, WordPad). Creates an XLS file that can be opened by Microsoft Excel. Creates an XLS file that can be opened by Microsoft Excel 2007 and later.

Drill-Down HTML (*.htm)

Plain HMTL (*.htm) PDF with system fonts (*.pdf) PDF with embedded fonts (*.pdf) RTF (*.rtf)

RTF with fixed positioning (*.rtf) Microsoft Excel 97 (*.xls) Microsoft Excel 2007/2010 Open XML (*.xlsx) TIFF (*.tif) Text (*.txt) Single Page Text (*.txt) Compressed Metafile (*.txt)

Creates a multi-page TIFF (Tag Image File Format) file. Creates a plain text file. Creates a single-page plain text file. Creates a compressed metafile text file.

To create an export file, select File | Export from the menu and use the File Save dialog box to select the type of file you want to create, specifying its name and location.
Note: When a document is exported to the RTF or the DOCX formats with the "preserve pagination" option selected, text is placed in text boxes and the ability to reflow text in the resulting document may be limited.

Managing Report Definition Files

A report definition file may contain several reports. Occasionally, you may want to copy or move a report from one file to another. To move a report from one file to another, open two instances of the C1ReportDesigner application and drag the report from one instance to the other. If you hold down the CTRL key while doing this, the report will be copied. Otherwise, it will be moved. You can also copy a report within a single file. This creates a new copy of the report, which is a good way to start designing a new report that is similar to an existing one.

89

Note that the report definition files are saved in XML, so you can also edit and maintain them using any text editor.

Importing Microsoft Access Reports

One of the most powerful features of the C1ReportDesigner application is the ability to import reports created with Microsoft Access. This feature requires Access to be installed on the computer. Once the report is imported into the Designer, Access is no longer required.

To import reports from an Access file, click the Application button and select Import from the menu. A dialog box prompts you for the name of the file you want to import. Select a Microsoft Access file (MDB or ADP) and the Designer scans the file and shows a dialog box where you can select which reports you would like to import:

90

The dialog box also allows you to specify if the Designer should clear all currently defined reports before starting the import process. The import process handles most elements of the source reports, with a few exceptions: Event handler code Access reports can use VBA, macros and forms to format the report dynamically. C1Report can do the same things, but it only uses VBScript. Because of this, all report code needs to be translated manually. Form-oriented field types Access reports may include certain fields that are not handled by the Designer's import procedure. The following field types are not supported: Chart, CommandButton, ToggleButton, OptionButton, OptionGroup, ComboBox, ListBox, TabCtl, and CustomControl. Reports that use VBScript reserved words Because Access does not use VBScript, you may have designed reports that use VBScript reserved words as identifiers for report objects or dataset field names. This causes problems when the VBScript engine tries to evaluate the expression, and prevents the report from rendering correctly. Reserved words you shouldn't use as identifiers include Date, Day, Hour, Length, Minute, Month, Second, Time, TimeValue, Value, Weekday, and Year. For a complete list, please refer to a VBScript reference. Reports that sort dates by quarter (or weekday, month of the year, and so on) C1Report uses the ADO.NET dataset Sort property to sort groups. This property sorts datasets according to field values only and does not take expressions. (Note that you can group according to an arbitrary expression, but you can't sort.) An Access report that sorts groups by quarter will sort them by date after it is imported. To fix this, you have two options: create a field that contains the value for the expression you want to sort on or change the SQL statement that creates the dataset and perform the sorting that way. These limitations affect a relatively small number of reports, but you should preview all reports after importing them, to make sure they still work correctly. Importing the Nwind.mdb File

91

To illustrate how the Designer fares in a real-life example, try importing the Nwind.mdb file. It contains the following 13 reports. (The Nwind.xml file that ships with C1Report already contains all the following modifications.) 1. Alphabetical List of Products No action required. 2. Catalog No action required. 3. Customer Labels No action required. 4. Employee Sales by Country This report contains code which needs to be translated manually. The following code should be assigned to the Group 1 Header OnPrint property: Visual Basic If SalespersonTotal > 5000 Then ExceededGoalLabel.Visible = True SalespersonLine.Visible = True Else ExceededGoalLabel.Visible = False SalespersonLine.Visible = False End If C# if (SalespersonTotal > 5000) { ExceededGoalLabel.Visible = true; SalespersonLine.Visible = true; } else { ExceededGoalLabel.Visible = false; SalespersonLine.Visible = false; }

5. Invoice No action required. 6. Products by Category No action required. 7. Sales by Category This report contains a Chart control that is not imported. To add a chart to your report, you could use an unbound picture field, then write a VB event handler that would create the chart and assign it to the field as a picture. 8. Sales by Category Subreport No action required. 9. Sales by Year This report contains code and references to a Form object which need to be translated manually. To replace the Form object, edit the RecordSource property to add a [Show Details] parameter: Visual Basic PARAMETERS (Beginning Date) DateTime 1/1/1994, (Ending Date) DateTime 1/1/2001,

92

(Show Details) Boolean False; ... C# PARAMETERS [Beginning Date] DateTime 1/1/1994, [Ending Date] DateTime 1/1/2001, [Show Details] Boolean False; ... Visual Basic Dim script As String = _ "bDetails = [Show Details]" & vbCrLf & _ "Detail.Visible = bDetails" & vbCrLf & _ "[Group 0 Footer].Visible = bDetails" & vbCrLf & _ "DetailsLabel.Visible = bDetails" & vbCrLf & _ "LineNumberLabel2.Visible = bDetails" & vbCrLf & _ "Line15.Visible = bDetails" & vbCrLf & _ "SalesLabel2.Visible = bDetails" & vbCrLf & _ "OrdersShippedLabel2.Visible = bDetails" & vbCrLf & _ "ShippedDateLabel2.Visible = bDetails" & vbCrLf & _ "Line10.Visible = bDetails" c1r.Sections.Detail.OnPrint = script C# string script = "bDetails = [Show Details]" + "Detail.Visible = bDetails\r\n" + "[Group 0 Footer].Visible = bDetails\r\n" + "DetailsLabel.Visible = bDetails\r\n" + "LineNumberLabel2.Visible = bDetails\r\n" + "Line15.Visible = bDetails\r\n" + "SalesLabel2.Visible = bDetails\r\n" + "OrdersShippedLabel2.Visible = bDetails\r\n" + "ShippedDateLabel2.Visible = bDetails\r\n" + "Line10.Visible = bDetails"; c1r.Sections.Detail.OnPrint = script; Visual Basic Sections ("Detail").OnPrint = _ "PageHeader.Visible = True" Sections("Group 0 Footer).OnPrint = _ "PageHeader.Visible = False" C# Sections ("Detail").OnPrint = "PageHeader.Visible = true"; Sections("Group 0 Footer).OnPrint = "PageHeader.Visible = false";

Use the new parameter in the report's OnOpen event:

Finally, two more lines of code need to be translated:

10. Sales by Year Subreport No action required. 11. Sales Totals by Amount This report contains code that needs to be translated manually. The following code should be assigned to the Page Header OnPrint property: Visual Basic PageTotal = 0

93

C# PageTotal = 0; Visual Basic PageTotal = PageTotal + SaleAmount HiddenPageBreak.Visible = (Counter = 10) C# PageTotal = PageTotal + SaleAmount; HiddenPageBreak.Visible = (Counter = 10);

The following code should be assigned to the Detail OnPrint property:

12. Summary of Sales by Quarter This report has a group that is sorted by quarter (see item 4 above). To fix this, add a field to the source dataset that contains the value of the ShippedDate quarter, by changing the RecordSource property as follows: SELECT DISTINCTROW Orders.ShippedDate, Orders.OrderID, [Order Subtotals].Subtotal, DatePart("q",Orders.ShippedDate) As ShippedQuarter FROM Orders INNER JOIN [Order Subtotals] ON Orders.OrderID = [Order Subtotals].OrderID WHERE (((Orders.ShippedDate) Is Not Null)); Change the group's GroupBy property to use the new field, ShippedQuarter. 13. Summary of Sales by Year No action required. Summing up the information on the table, out of the 13 reports imported from the NorthWind database: eight did not require any editing, three required some code translation, one required changes to the SQL statement, and one had a chart control that was not replaced.

Importing Crystal Reports

The C1ReportDesigner application can also import Crystal report definition files (.rpt files).

94

To import reports from a Crystal report definition file: 1. 2. Click the Application button and select Import from the menu. A dialog box prompts you for the name of the file you want to import. Select a Crystal report definition file (RPT) and the Designer will convert the report into the C1Report format.

The import process handles most elements of the source reports, with a few exceptions for elements that are not exposed by the Crystal object model or not supported by C1Report. The exceptions include image fields, charts, and cross-tab fields.

Charting in ReportViewer for ASP.NET AJAX

Aggregate charting is a powerful, yet simple and easy-to-use feature.ComponentOne Reporting products have always supported chart fields using their extensible custom field architecture. The Chart field is implemented as a custom field in the C1.Win.C1Report.CustomFields.2.dll assembly, which is installed with the report designer application and is also included as a sample with full source code (CustomFields). In the following topics, you'll see how you can customize chart fields in reports using the C1ReportDesigner application.

Charts in Flat Reports

Creating simple charts is very easy. The following steps required to create a simple chart: 1. 2. 3. Open the C1ReportDesigner application and create or open a report definition file. Add a Chart field to the report, then select it to show its properties in the designer's property window. Set the chart's DataX property to the name of the field whose values should be displayed in the X axis (chart categories).

95

4. 5.

Set the chart's DataY property to the name of the field whose values should be displayed in the Y axis (chart values). Optionally set additional properties such as ChartType and DataColor.

For example, the chart below was created based on the NorthWind Products table. In this case, the following properties were set: DataX = "ProductName" DataY = "UnitPrice"

Note that for this chart type (Bar), the value axis (where the DataY field is displayed) is the horizontal one, and the category axis is the vertical one. In this case, a filter was applied to the data in order to limit the number of values shown. Without the filter, the chart would contain too many values and the vertical axis would not be readable.

Other Useful Chart Properties

In addition to the DataX and DataY properties mentioned above, the Chart object provides a few other properties that are commonly used: ChartType: This property allows you to select the type of chart to display. There are six options: Bar (horizontal bars), Column (vertical columns), Scatter (X-Y values), Line, Area, and Pie. DataColor: This property selects the color used to draw the bars, columns, areas, scatter symbols, and pie slices. If the chart contains multiple series, then the Chart field automatically generates different shades of the selected color for each series. If you want to select specific colors for each series, use the Palette property instead, and set its value to a semi-colon separated list containing the colors to use (for example "Red;Green;Blue"). FormatY, FormatX: These properties determine the format used to display the values along each axis. For example, setting FormatY to "c" causes the Chart field to format the values along the Y axis as currency values. This is analogous to the Format property in regular report fields. XMin, XMax, YMin, YMax: These properties allow you to specify ranges for each axis. Setting any of them to -1 cause the Chart to calculate the range automatically. For example, if you set the YMax property to 100, then any values higher than 100 will be truncated and won't appear on the chart. ShowPercentages: Each pie slice has a legend that shows the X value for the slice. If the ShowPercentages property is set to true, the legend will also include a percentage value that indicates the

These properties apply to all chart types. There are a few additional properties that only apply to Pie charts:

96

size of the slice with respect to the pie. The percentage is formatted using the value specified by the FormatY property. For example, if you set FormatY to "p2", then the legends will include the X value and the percentage with two decimal points (for example "North Region (15.23%)"). RadialLabels: This property specifies that instead of showing a legend on the right side of the chart, labels with connecting lines should be attached to each slice. This works well for pies with few slices (up to about ten).

The Chart field is actually a wrapper for a C1Chart control, which provides all the charting services and has an extremely rich object model of its own. If you want to customize the Chart field even further, you can use the ChartControl property to access the inner C1Chart object using scripts. For example, the Chart field does not have a property to control the position of the legend. But the C1Chart control does, and you can access this property through the ChartControl property. For example, the script below causes the chart legend to be positioned below the chart instead of on the right: ' place legend below the chart chartField.ChartControl.Legend.Compass = "South" If you assign this script to the report's OnLoad property, the chart will look like the image below:

The other properties used to create these chart are as follows: ChartType = Pie FormatY = "p1" ShowPercentage = true Palette = "Red;Gold;Orange;Beige;DarkGoldenrod;Goldenrod;"

97

Charts with Multiple Series

To create charts with multiple series, simply set the DataY property to a string that contains the names of each data field you want to chart, separated by semi-colons. For example, to create a chart showing product prices and discounts you would set the DataY property as shown below: DataY = "UnitPrice;Discount" If you want to specify the color used to display each series, set the Palette property to a list of colors separated by semi-colons. For example, the value displayed below would cause the chart to show the UnitPrice" series in red and the "Discount" series in blue: Palette = "Red;Blue"

Series with Calculated Values

The DataY property is not restricted to field names. The strings that specify the series are actually treated as full expressions, and are calculated like any regular field in the report. For example, to create a chart showing the actual price of each field you could set the DataY property to the value shown below: DataY = "UnitPrice * (1 - Discount)"

Charts in Grouped Reports

ReportViewer for ASP.NET AJAX allows you to create reports with multiple groups. For example, instead of listing all products in a single flat report, you could group products by category. Each group has a header and a footer section that allow you to display information about the group, including titles and subtotals, for example. If you add a chart to a group header, the chart will display only the data for the current group. By contrast, adding a chart to the report header or footer would include all the data in the report. To illustrate this, here is a diagram depicting a report definition as shown in the report designer and showing the effect of adding a Chart field to the report header and to a group header:

Report Header section A chart field here would generate only one chart for the entire report. The chart would show all the data in the report's data source. Page Header section Group Header section (CategoryName) A chart field here would generate one chart for each CategoryName value. Each chart would show all the data for the current CategoryName. Detail section Group Footer section (CategoryName) Page Footer section

98

Report Footer section

Continuing with the example mentioned above, if you added a chart to the group header and set the DataX property to "ProductName" and the DataY property to "UnitPrice", the final report would contain one chart for each category, and each chart would display the unit prices for the products in that category. The images below show screenshots of the report described above with the group headers, the charts they contain, and a few detail records to illustrate:

The above chart shows unit prices for products in the "Beverages" category. The below chart shows unit prices for products in the "Condiments" category.

99

DataX = "Product Name" DataY = "Unit Price" Because the chart automatically selects the data based on the scope of the section that contains it, creating charts in grouped reports is very easy.

Aggregate Charts
The Chart field has a powerful feature called "aggregated charting". This feature allows you to create charts that automatically aggregate data values (DataY) that have the same category (DataX) using an aggregate function of your choice (sum, average, standard deviation, and so on). To illustrate this feature, consider an "Invoices" report that groups data by country, customer, and order ID. The general outline for the report is as follows:

Report Header section Page Header section Group Header section (Country) Group Header section (Customer) Group Header section (OrderID) Detail section Group Footer section (OrderID)

100

Group Footer section (Customer) Group Footer section (Country) Page Footer section Report Footer section

Now imagine that you would like to add a chart to each Country header displaying the total value of all orders placed by each customer in the current country. You would start you adding a Chart field to the "Country" header section and set the DataX and DataY properties as follows: DataX = "CustomerName" DataY = "ExtendedPrice" This would not work. The data for each country usually includes several records for each customer, and the chart would create one data point for each record. The chart would not be able to guess you really want to add the values for each customer into a single data point. To address this scenario, we added an Aggregate property to the Chart field. This property tells the chart how to aggregate values that have the same category into a single point in the chart. The Aggregate property can be set to perform any of the common aggregation functions on the data: sum, average, count, maximum, minimum, standard deviation, and variance. Continuing with our example, we can now simply set the chart's Aggregate property to "Sum". This will cause the chart to add all "ExtendedPrice" values for records that belong to the same customer into a single data point. The result is shown below:

Notice how each customer appears only once. The values shown on the chart correspond to the sum of the "ExtendedPrice" values for all fields with the same "Customer". Because the chart appears in the "Country" header field, it is repeated for each country, showing all the customers in that country. If you place the chart in the report header section, it will aggregate data over the entire report. For example, suppose you want to start the "Invoices" report with a chart that shows the total amount ordered by each salesperson. To accomplish this, you would add a Chart field to the report header section and would set the following properties:

101

DataX = "Salesperson" DataY = "ExtendedPrice" Aggregate = "Sum" The image below shows the resulting chart:

Since the chart is placed in the report header section, the values displayed include all countries and all customers. If you moved the chart field from the report header to the "Country" group header, you would obtain a similar chart for each country, showing the total amounts sold by each salesperson in that country.

102

Working with C1ReportsScheduler

The following topics contain important information about C1ReportsScheduler, a stand-alone application used to schedule report creation to run in the background. Using the C1ReportsScheduler application, you can choose what reports to export or print, formats to export the report to, and the schedule and frequency for creating reports.

About C1ReportsScheduler
The C1ReportsScheduler application is designed to run scheduled ComponentOne ReportViewer for ASP.NET AJAX tasks in the background. The following report task types are supported: An XML report definition loaded into a C1Report component. An XML report definition imported into a C1PrintDocument component. A data bound C1PrintDocument loaded from a C1D/C1DX file. An executable user program generating and exporting or printing a report.

For each task, multiple actions can be specified. For example, a report can be exported to PDF and Excel files and also printed. Each task also has an associated schedule that specifies when the task needs to be executed. The C1ReportsScheduler application consists of two related interacting parts: The C1ReportsScheduler frontend application (C1ReportsScheduler.exe). The C1ReportsScheduler Windows service (C1ReportsSchedulerService.exe).

In the recommended mode of operation, the service (C1ReportsSchedulerService.exe) runs in the background, executing specified tasks according to their schedules. The frontend (C1ReportsScheduler.exe) can be used to view or edit the task list, start or stop schedules, and control the service. While the frontend is used to install and setup the service, it is not needed for the service to run, so normally it would be started to adjust the list of scheduled tasks as needed, and exited. (If the service is installed on a machine, the frontend connects to it automatically when started.) While not recommended, standalone mode of operation is also possible. In this mode, the frontend is also used to actually run the scheduled tasks. In that case, of course, terminating the frontend application will also stop all schedules. Note that all service specific operations (installation, setup, and un-installation) can be performed from the frontend application.

Installation and Setup

By default, the C1ReportsScheduler application and service (C1ReportsScheduler.exe and C1ReportsSchedulerService.exe) will be installed in the C:\Program Files\ComponentOne\Studio for WPF\C1WPFReport directory in the Scheduler or Scheduler.4 folder. To install and setup the application and service, complete the following steps: 1. Navigate to the installation directory and double-click the C1ReportsScheduler.exe application to open it. When the C1ReportsScheduler.exe application is run for the first time, a dialog box will appear asking whether you would like to install the C1ReportsScheduler service. 2. Click Yes to install the service (recommended). A form should appear which will allow you to set up the service parameters such as the WCF address used by the frontend to communicate with the service, the path of the service configuration file (.c1rsconf), service startup type (manual or automatic), and log options.

103

3.

Adjust the parameters if necessary (defaults should normally work), and click OK to install the service. The progress window should appear, and when it closes the frontend should be running in client mode. This is indicated by the words "client mode" in the form's caption, and "[ Client ]" in the status line (which should also contain an icon showing a gear with a green checkmark).

If you clicked No when asked whether to install the service, the frontend will start in standalone mode, as indicated in the form's caption and status line. You can still add tasks, specify their actions and schedules and start them. The only difference is that in standalone mode you will need to keep the frontend running for the tasks to run on schedules. Note that when in standalone mode, you can install the service at any time and transfer your task list to it. To install the service, open the frontend application, and select Install Service from the Service menu. To uninstall the service, select Uninstall Service from the Service menu.

User Interface
When you open the C1ReportsScheduler application, it appears similar to the following image:

The main C1ReportsScheduler window is divided into three areas: The upper part of the main window shows the task list. Each task defines a report or document scheduled for generation. For more information, see Task List (page 105). The lower left part of the main window shows the list of actions defined for the current task. For more information, see Action List (page 107). The lower right part of the main window shows the schedule for the current task. For more information, see Schedule (page 109).

The following topics detail the C1ReportsScheduler application's user interface.

104

Caption and Status Bar

When working with the C1ReportsScheduler application, you may notice that the caption and status bars provide various indicators and information. The form caption is used to show the current mode (client or standalone). For example, the caption bar in the image below indicates that the application is running in client mode and lists the service it is connected to:

The status bar has two areas. The right side of the status bar displays an icon and a brief text description of the current mode. The two available modes are Client and Standalone mode. For example, in the image below, the status bar indicates it is in Client mode:

The left side of the status bar displays any warnings or error messages. If the current task or action has errors, the main status area shows a related icon and the error description (for example, the report definition file is not found). For example, in the image below the status bar displays a warning:

Task List
The task list appears at upper part of the main window and consists of a grid with several columns where you can add various tasks to complete. Each task defines a report or document scheduled for generation. The task list appears similar to the following image:

105

The task list is represented by a grid with the following columns: File Name The File Name column lists the name of the C1Report, C1PrintDocument, or executable file on which to schedule an action. For C1Report/Imported C1Report type of tasks, this is the name of the report definition file, for C1PrintDocument type of tasks, this is the name of C1D/C1DX file containing the document, and for external executable type of tasks, this is the name of the executable file to run. To select a file, click the ellipsis button to the right of the file name text box. Report Name Used only for C1Report/Imported C1Report tasks, this column specifies the name of the report. It's a combo box: when a report definition file is selected in the first column, the combo drop-down box is automatically filled with available reports' names. Report Type This column specifies the type of the current task. The following report task types are supported:
States C1Report Description For tasks of the C1Report type, an instance of C1Report component is used to load the report definition and generate the report. For tasks of the Imported C1Report type, an instance of C1PrintDocument component is used to import the report definition and generate the report. For tasks of the C1PrintDocument type, an instance of C1PrintDocument is used to load and generate the document. Tasks of the External executable type are represented by external programs. The intention is to run applications that rely on code when generating reports.

Imported C1Report

C1PrintDocument

External executable

Task state This column shows a small image representing the current state of the task. Note that this column does not have a caption. Image indicators used in the column include:
Description

106

A gray ball representing an unchecked task. A green ball representing a successfully checked task that is currently not running. A yellow ball representing a successfully checked task that is currently running. A yellow triangle with an exclamation mark representing a task that has errors.

Status This column shows the current state of the task. States include:
States Ready Description Task is ready but is not scheduled. This is the only status allowing to edit the task. Task is scheduled for execution. Changes are not allowed to a task with this status. A scheduled task that is currently running. Changes are not allowed to a task with this status. Task is scheduled for execution but the schedule is paused. Changes are not allowed to a task with this status.

Scheduled

Busy

Paused

To manipulate the task list, use the Task menu or the toolbar on the left of the task grid:

Action List
The task action list appears in the bottom-left of the screen and represents the list of actions associated with the current task (the task selected in the Task List). The action list appears like the following image:

107

The action list is represented by a grid with the following columns: Action This is the type of action. The following action types are supported:
Type Export Description Exports the report or document represented by the current task to one of the supported external formats. This action type is not allowed for External executable type of tasks. Print Prints the report or document represented by the current task. This action type is not allowed for External executable type of tasks. Run Runs the executable. This action type is only allowed for External executable type of tasks.

Export Format For export actions, this column specifies the export format. Note that different sets of export formats are available for tasks using C1Report and C1PrintDocument components (this is similar to the way export of those components is handled by the preview controls).

Output File/Printer Name Specifies either the name of the exported file, or the name of the printer used. Click the button to the right of this textbox to select the file or printer name (depending on the action type).

Current Status The last column (without a title) is used to show a small image representing the current status of the action:
Description A gray ball representing an unchecked task. A green ball representing a successfully checked task that is

108

currently not running. A yellow ball representing a successfully checked task that is currently running. A yellow triangle with an exclamation mark representing a task that has errors.

To manipulate the action list, use the Action menu or the toolbar on the left of the action grid:

Schedule
The scheduling panel displays the schedule associated with the current task and allows you to schedule and run the task. The scheduling area appears similar to the following image:

The scheduling section of the application includes the following options:

109

Frequency In the upper left part of the panel there are four radio buttons specifying how often the task will run: One time, Daily, Weekly, or Monthly. The first option, One time, allows the task to repeat every specified number of seconds, minutes or hours. The other options allow recurrence on a daily, weekly, or monthly basis. As each radio button is selected, the schedule panel shows different scheduling options.

Start Date and Time The start date and time do what you'd expect set the date and time that the scheduling action should begin.

Start, Stop, and Pause In the bottom part of the panel, there are two buttons allowing you to start, stop, pause or resume the current task. The buttons change and become available depending on the status of the current task.

Next scheduled run To the right of the buttons, the time of the next scheduled run of the task is shown. Recurrence This section changes depending on the frequency radio button selected. For example, the Daily option includes a numeric box allowing you to choose the number of days between the schedule tasks, the Monthly option allows you to select the months to run the task and the date each month, and so on.

To start, stop, pause, or resume a scheduled task, you can also use the Schedule menu:

Menu System
The C1ReportsScheduler application includes several menu options, and the application menu includes File, Task, Action, Schedule, Service, and Help options which appear similar to the following:

This topic describes each of the available menu options. File

110

The File menu includes the following options: Task The Task menu includes the following options: Add Task Adds a new task to the task list. The task is added to the end of the list, but can be moved up and down in the list using appropriate commands. Remove Removes the current task from the list. Move Up Moves the current task up in the list. Move Down Moves the current task down in the list. Check Checks the validity of the current task and all its actions' specification. Items that are checked include the existence and validity of report definition, correctness of output file names, and so on. A task is checked automatically when it is scheduled. A successfully checked task has a green ball icon in the "State" column. If a check failed, the task cannot be scheduled, and an exclamation mark icon is displayed. Hover the mouse over that icon to see the error message (it is duplicated in the status line when the task is current). Check All Checks the validity of all tasks in the list. Preview Generates the current task's report or document, and shows it in a print preview dialog. Note that this command is disabled when the task is scheduled. Action The Action menu includes the following options: Add Action Adds a new action to the action list of the current task. The action is added to the end of the list, but can be moved up and down in the list using appropriate commands. New Clears the current task list. Open Opens an existing C1Reports Scheduler configuration file (.c1rsconf). Save Saves the current task list. Save As Saves the current task list in a C1Reports Scheduler configuration file (.c1rsconf). Exit Closes the program.

111

 Schedule

Remove Removes the current action from the list. Move Up Moves the current action up in the list. Move Down Moves the current action down in the list.

The Schedule menu includes the following options: Service The Service menu includes the following options: Connect Connects to the C1Reports Scheduler service. This command is only available when the service is running. Disconnect Disconnects from the C1Reports Scheduler service. Transfer Tasks Transfers the current task list to the C1Reports Scheduler service. This command is available when the service is running but the frontend application is disconnected from the service and contains its own task list. Start Starts the C1Reports Scheduler service. This command is available when the service is installed on the machine but is not running. Stop Stops the C1Reports Scheduler service. This command is available when the service is installed on the machine and is running. Pause Pauses the C1Reports Scheduler service. This command is available when the service is installed on the machine and is running. Resume Resumes the C1Reports Scheduler service. This command is available when the service is installed on the machine and is paused. Start Starts the current task's schedule. When the schedule is started, the task or its actions cannot be edited. Stop Stops the current task's schedule. Pause Pauses the current task's schedule. Resume Resumes the current task's schedule if it has been paused.

112

Service Setup Launches the C1Reports Scheduler service setup dialog. That dialog allows to adjust the service parameters, and will restart the service when OK is pressed in the dialog. This command is available if the service is installed on the machine.

Install Service Installs the C1Reports Scheduler service on the machine. This command is available when the service is not installed on the machine.

Uninstall Service Uninstalls the C1Reports Scheduler service. This command is available when the service is installed on the machine.

Help

Service Log Shows or shows the window with the C1Reports Scheduler service log.

The Help menu includes the following options: Contents Shows the help file. About Shows the About box which includes information about the application, as well as links to online resources.

113

ReportViewer for ASP.NET AJAX Samples

Please be advised that this ComponentOne software tool is accompanied by various sample projects and/or demos which may make use of other development tools included with the ComponentOne Studios. Samples can be accessed from the ComponentOne Sample Explorer. To view samples, on your desktop, click the Start button and then click All Programs | ComponentOne | Studio for ASP.NET | Samples | Palomino Samples.
Note: For information about using C1Report and C1PrintDocument, see the Reports for WinForms documentation.

C# Samples The following pages within the ControlExplorer sample installed with ComponentOne Studio for ASP.NET AJAX detail the C1ReportViewer control's functionality:
Sample C1ReportViewer Description This sample demonstrates how to use the C1ReportViewer control.

The following pages within the C1ReportViewer sample installed with ComponentOne Studio for ASP.NET AJAX detail the C1ReportViewer control's functionality:
Sample BrowseC1Reports BrowseRDLs Browse C1PrintDocuments Description This sample allows you to choose a C1Report to view at run time. This sample allows you to choose a Report Definition Language (RDL) report to view at run time. This sample allows you to choose a C1PrintDocument to view at run time.

ReportViewer for ASP.NET AJAX Task-Based Help

The task-based help assumes that you are familiar with programming in ASP.NET and know how to use controls in general. By following the steps outlined in the help, you will be able to create projects demonstrating a variety of ReportViewer for ASP.NET AJAX's features, and get a good sense of what the C1ReportViewer control can do. Each topic provides a solution for specific tasks using the C1ReportViewer control. Each task-based help topic also assumes that you have created a new ASP.NET AJAX-Enabled project. For additional information on this topic, see Creating an AJAX-Enabled ASP.NET Project (page 14). For information about using C1Report and C1PrintDocument, see the Reports for WinForms documentation.
Note: ReportViewer for ASP.NET AJAX requires Microsoft ASP.NET AJAX Extensions installed and a ScriptManager on the page before the C1ReportViewer control is placed on the page. You must create an ASP.NET AJAX-Enabled Project so that the ScriptManager and Microsoft AJAX Extensions are included on the page. For

115

more information, see Creating an AJAX-Enabled ASP.NET Project (page 14). For more information about Microsoft ASP.NET AJAX Extensions, see http://ajax.asp.net/. For information about the ScriptManager, see MSDN.

Creating a C1ReportViewer in Code

Creating a C1ReportViewer control in code is fairly simple. In the following steps you'll add a PlaceHolder control to the page, add an import statement, add and customize the C1ReportViewer, and add the control to the PlaceHolder. Complete the following steps: 1. 2. 3. In Design view, navigate to the Visual Studio Toolbox and add a PlaceHolder control to your page. Double-click the page to create the Page_Load event and switch to Code view. Add the following statement to the top of the Code Editor to import the appropriate namespace: 4. Visual Basic Imports C1.Web.UI.Controls.C1Report.C1ReportViewer C# using C1.Web.UI.Controls.C1Report.C1ReportViewer; Visual Basic ' Create a new C1ReportViewer. Dim reportviewer1 As New C1ReportViewer ' Add the C1ReportViewer to the PlaceHolder control. PlaceHolder1.Controls.Add(reportviewer1) ' Set the control's size. reportviewer1.Height = 350 reportviewer1.Width = 600 C# // Create a new C1ReportViewer. C1ReportViewer reportviewer1 = new C1ReportViewer(); // Add the C1ReportViewer to the PlaceHolder control. PlaceHolder1.Controls.Add(reportviewer1); // Set the control's size. reportviewer1.Height = 350 reportviewer1.Width = 600;

Add the following code to the Page_Load event to create and customize the C1ReportViewer control.

Setting the Visual Style

The control includes several built-in visual styles, including Vista and Office 2007 styles, to style your application. For more information about available styles, see Visual Styles (page 41). You can easily change visual styles in Source view, in Design view, and in code using the VisualStyle property. The examples below set the VisualStyle to Vista. Note that when you change the VisualStyle property the VisualStylePath and C1ReportViewer.CssClass properties also change. In Source View In Source view add VisualStyle="Vista" to the <cc1:C1ReportViewer> tag so it appears similar to the following: <cc1:C1ReportViewer ID="C1ReportViewer1" runat="server" VisualStyle="Vista" /> From the Tasks menu

116

You can select a visual style to apply from the C1ReportViewer Tasks menu: 1. 2. 3. Click on the C1ReportViewer's smart tag to open the C1ReportViewer Tasks menu. Click the Visual Style drop-down arrow. In the Visual Style drop-down box select a Visual Style, for example Vista. The Visual Style you chose will be applied to the C1ReportViewer control. From the Properties window You can select a visual style to apply from the Properties window: 1. 2. 3. In Code Add the following code to the Page_Load event to set the VisualStyle property to Vista: Visual Basic Me.C1ReportViewer1.VisualStyle = "Vista" C# this.C1ReportViewer1.VisualStyle = "Vista"; Click on the C1ReportViewer control to select it. Navigate to the Properties window and to the VisualStyle property. Type in a style to apply, for example "Vista". The Visual Style you choose will be applied to the C1ReportViewer control.

Resizing the Control

You can easily change the height and width on the C1ReportViewer by setting the Height and Width properties. You can easily change the control's height and width in Design view, Source view, the Properties window, or code. In Design View To resize the C1ReportViewer control in Design view, click the bottom-right corner of the control and perform a drag-and-drop operation to set the control's size. In Source View In Source view add Height="350px" Width="600px" (or substitute values you choose) in the <cc1:C1ReportViewer> tag so that it looks similar to the following: <cc1:C1ReportViewer ID="C1ReportViewer1" runat="server" Height="350px" Width="600px" > The above will resize the control to 350 pixels tall and 600 pixels wide. In the Properties Window You can change the Height and Width properties to set the control's height and width in the Properties window: 1. 2. 3. 4. 5. In Code Click on the C1ReportViewer to select it. Navigate to the Properties window and if needed expand the Layout node to locate the Height and Width properties. Next to Height, enter the size you want the control's height to be, for example "350px". Next to Width, replace "600px" with the size you want the control's width to be, for example "600px". Press the ENTER key or click outside of the Properties window for the height and width you set to be applied to the C1ReportViewer control.

117

Add the following code to the Page_Load event to set the Height to 350 pixels and the Width to 600 pixels: Visual Basic Me.C1ReportViewer1.Height = 350 Me.C1ReportViewer1.Width = 600 C# this.C1ReportViewer1.Height = 350; this.C1ReportViewer1.Width = 600;

Sharing Documents Between Client Sessions

The C1ReportViewer control can share generated documents between different client sessions. So, for example, multiple clients can view the same generated report rather than generating a copy for each client. The ShareBetweenSessions property is used to control that. By default this property is set to True. In that case, a report that has the same FileName/ReportName pair will be reused if requested by another client session once it has been generated on request of a single client session. If this property is set to False, each session will generate its own reports. For example, add the following code to the Page_Load event to set the ShareBetweenSessions property to False: Visual Basic Me.C1ReportViewer1.Cache.ShareBetweenSessions = False C# this.C1ReportViewer1.Cache.ShareBetweenSessions = false;

Switching Documents at Run Time

You can switch between different report documents on the client side at run time. For example, to switch between different documents on the client, you can add the following script to the page: <script language="javascript" type="text/javascript"> function getReport() { return $find("<%=C1ReportViewer1.ClientID%>") } function changeReport(fileName, reportName) { var c1Report = getReport(); c1Report.set_fileName(fileName); c1Report.set_reportName(reportName); c1Report.generate(); } </script> Then, you can use a link on the page, like in the following markup, to switch to a particular report: <a href='javascript:changeReport("~/SpanningGroups.rdl", "")'>SpanningGroups</a> Clicking this link will navigate to the selected report.

118