How to use AddNamedItem API in ActiveReports.

AddNamedItem method on the SectionReport class provides the ability to add an instance of a class or type to report script's global namespace. Report's script becomes aware of this custom class within a project or one coming from an external class library. Once a type or an object has been added to the the report's scope , any method or properties contained within that type can then be called from the script. Since the RPX file format is a plain XML format and cannot be compiled, this method allows you to add objects such as data base information or business objects from the calling application into the context of report's script. This method is typically used when running reports in stand-alone mode and not compiled into the application. Why use AddNamedItem?

  • A very simple example would be to have an Order class that contains a method for computing total sales tax for a given order. When you print the order you can pass an Order class instance to the report to allow you to call that method from the report script. One advantage of doing it this way is to keep the sales tax implementation separate from report. At the same time, if the sales tax value changes, the only this class is required an update.
  • Another advantage is when the custom class is not part of the containing project. Using an external class library for the named item is helpful as the main application containing report doesn't need to be recompiled again. All that needs to be done it to make the changes in the external class library and update the main application reference with this assembly.

AddNamedItem makes sense for RPX reports. RPX reports are plain XML based layout with scripts. However, it doesn't make sense to use this API in code base reports because the reports by itself can be compiled. Usage:

  • In code-behind ReportStart method of the RPX report, where
  • Before Run method is called on the report from a button click event for example.

Examples: A simple report: Run the sample and click on 'Simple Example' from 'AddNamedItem with RPX reports' menu: Files:

  • AddNamedItemSimple.rpx: ActiveReport RPX file for this example. Report's script (click on 'Script' tab to view the script)
  • ViewerForm.cs: See method '_simpleExampleToolStripMenuItem_Click_' that runs this sample. This methods sets this report with a NamedItem. The method calls are in the ReportStart and other relevant events in the Report's script.
    • Just a reminder; if a control is in a particular section in a report, that section's Format event is where you would edit/assign the control's properties.
  • MyClass.cs: This class is part of the AddNamedItem project is used as the NamedItem. Identifier 'NameInfo' is used to reference an instance of this object in the report's script. For this example we use the the FirstName and the LastName properties to assign and get the values in the report . Display method from MyClass is used to assign the text 'Created by FirstName LastName...'. to the label in the page header section of the report.

I create an instance of MyClass right before the report is Run. I then set the FirstName and the LastName properties for this instance to values of 'GrapeCity' and 'India' respectively. MyClass myClass = new MyClass(); myClass.FirstName = "GrapeCity"; myClass.LastName = "India"; This instance is given an alias of 'NameInfo', which is a string, and can then be used in the report's script using that identifier. Here 'addNewItemRpx' is an instance of the report. addNewItemRpx.AddNamedItem("NameInfo", myClass); If you look at the report's script, in the PageHeader format event the header label on page header section is getting assigned the text from MyClass's Display method, with the literal 'NameInfo' being used as an alias. _this.headerLabel.Text = NameInfo.Display(); And that is all there is to it. See screen-shot for this example. A more realistic example, a Database example. Run the sample and click on 'Database Example' from 'AddNamedItem with RPX reports' menu: We follow the same methodology as above, with couple of differences;

  • The report file is a little bit more real; an Invoice report and is pulling date from a database. See AddNamedItemDB.rpx.
  • We use two NamedItems this time.
    • One from the above example, MyClass that will provide us a first name, a last name and a sales tax value that is used to calculate grand total sales for the invoices in the report.
    • I add another one called MyConnection that I use to provide database connection information to the report. I am using 'ConnectionInfo' as the identifier/alias for this NamedItem. MyConnection class provides the type of data source, the connection string and the sql query to the report.
      • Sometimes the report developer doesn't want the database connection information residing directly in the report and using a NamedItem is another way to hide that information from his end users.
  • See _databaseExampleToolStripMenuItem_Click_ method in ViewerForm.cs

The setup is pretty much the same as the previous sample. Before the report is run, MyConnection class is instantiated. The connection strings are set to this instanced and is added as a NamedItem with 'ConnectionInfo' identifier. We are connecting to the NorthWind database that comes with ActiveReports 6 installer. MyClass instance has the FirstName and LastName set to 'GrapeCity' and 'Japan' respectively, with sales tax value of 8.5 %. Report's DataSource information is then retrieved in the ReportStart event of the script. Click on script tab of this report to see the code. Here we get the DataSource connection string and sql using the 'ConnectionInfo alias for MyConnection NamedItem and assign the values to corresponding properties of DataDynamics.ActiveReports.DataSources.OleDBDataSource object. This datasource instance is then assigned to report's datasource. DataDynamics.ActiveReports.DataSources.OleDBDataSource ds = new DataDynamics.ActiveReports.DataSources.OleDBDataSource(); // use ConnectionInfo NamedItem to get the database connection string and the sql associated with it. // See ViewerForm.cs ds.ConnectionString = ConnectionInfo.ConnectionString; ds.SQL = ConnectionInfo.SQL; rpt.DataSource = ds; In the GroupFooter format event, we use the GetFullName() method and SalesTax property off of MyClass NamedItem using 'NameInfo' alias. Both of them are used and appended together to form the text of the 'CreatedBy' label. _// Full Name assigned to label 'Created By' in the PageFooter is called from MyClass NamedItem. string createdBy = NameInfo.GetFullName(); this.lblCreatedBy.Text += createdBy + " with Sales Tax: " + salesTax * 100 +"%"; Additionally, SalesTax is used to compute grand total. // calculate the total based on values from textboxes in the group footer. double subtotal = Convert.ToDouble(subtotalTextBox.Value); double freight = Convert.ToDouble(freightTextBox.Value); _double salesTax = NameInfo.SalesTax; this.salesTax.Value = salesTax; // uses the sales tax value to compute grand total grandTotalTextBox.Value = String.Format("{0:C}", subtotal * (1 + salesTax) + freight); When you run this example, you will notice that the grand total is calculated using the above sales tax value. A label is also populated with the above first name and the last name as explained above. You will see that how easy it is to use the named item to display these information. Another example: The Database example from above that uses NamedItem from an external library. Run the sample and click on 'External Library Example' from 'AddNamedItem with RPX reports' menu: This example is the same as the database example, with the only difference is that the NamedItem now comes from a class library. The solution attached to this post has the MyClassLibrary project that contains MyExternalClass. This class is implemented almost the same as the MyClass that resides in the main project. I compiled this assembly and added this reference to the main project. MyClassLibrary.MyExternalClass myExternalClass = new MyClassLibrary.MyExternalClass(); myExternalClass.FirstName = "GrapeCity"; myExternalClass.LastName = "USA"; myExternalClass.SalesTax = 0.075;

  • See _externalAssemblyExampleToolStripMenuItem_Click_ method in ViewerForm.cs

MyExternalClass instance has the FirstName and LastName set to 'GrapeCity' and 'USA' respectively, with sales tax value of 7.5 %. See the screenshot for this example. One last one: Using ReportStart event in the code. Run the sample and click on 'Using ReportStart event through code' from 'AddNamedItem with RPX reports' menu: In general, developers like to keep the report related stuff separate from other application specific code. Sometimes, it helps that a button click event that does lot of other things on top of creating a report and running it, be kept very simple and easy to read and understand. In the above examples, if you look at the menu item click event code in ViewerForm.cs, there is just too much of report specific code, that might cause confusion. So, the one other way of using AddNamedItem is to put it in the ReportStart event of the report.

  • Remember that this has to be done in the code (cs/vb file; ViewerForm.cs file in this example) and NOT in the report's script.
  • See _usingReportStartEventToolStripMenuItem_Click_ method in ViewerForm.cs
    • I added the instance of report created here to ReportStart event and this cleans up the this method very nicely.
  • Also see addNewItemRpx_ReportStart method in ViewerForm.cs:
    • All the report specific code such as creating instance of NamedItems, general comments and the actual AddNamedItem call that are very specific to ActiveReport in this ReportStart event.

This example uses the external assembly sample from above. MyExternalClass instance has the FirstName and LastName set to 'GrapeCity' and 'Vietnam' respectively, with sales tax value of 6.5 %. And that is all!! Relevant links: ActiveReports Online Help on AddNamedItem AddNamedItem sample in VS 2010: AddNamedItem_ar6 AddNamedItem_AR7

MESCIUS inc.

comments powered by Disqus