Include Data in a Report

DataField Property

The mechanism by which data is included in a template is the same for all types of data: the control's DataField property is set to the field name of the data that will be bound to the control. For print templates, the DataField property is set to _MainMap. All Report Designer controls, with the exception of design elements like shapes and page breaks, have a DataField property.

Components dragged from the Geocortex Essentials panel are assigned a DataField value automatically. Do not edit the DataField values of these controls. For controls taken from the Controls panel, however, you must type the field name in the DataField box:

If you forget to enter the DataField value for a control, or you make an error when typing the field name, the control will not be populated with data when the report is generated. In the final report, the control will contain its default value or it will be blank if no default value has been defined. Text controls such as TextBox and Label controls use the value of their Text property as the default value if no data can be bound to them.

Field Aliases

If you have fields in your spatial layers that have been assigned aliases at the data source level (in the MXD, for example), you must ensure that you still use the original field name in the DataField property. Do not use the field alias.

If you have aliased fields in external data sources, such as by using the "AS [Field Attribute]" syntax in the SQL query, you must ensure that you use the alias in the DataField property of the report, as the original field name does not get communicated to the reporting engine from the original data source.

Combine Different Types of Data Using Subreports

A Report Designer template can have:

If you want your template to combine different types of data, you must encapsulate the external data sources and /or map data inside subreports. This ability to include other template files as subreports to the main report allows you to create templates that combine layer data, external data and map data in a single report.

A template can have as many subreports as you want, but subreports cannot themselves contain subreports.

The SubReport control is in the Controls panel. When you drag the SubReport control to the design area, it appears as an empty rectangle in both Designer and Preview views. When the report is generated, the subreport's template file executes and populates the control.

Include a Subreport in a Report

If you want a report to contain a subreport, you must configure the name and location of the subreport's template file in the main (or parent) template file.

To specify a subreport's template file in the parent template:

  1. Select the SubReport control whose template file you want to specify.

  2. Set the Tag property:

    1. Locate the Tag property in the Properties area.

    2. Click the Tag property to make it editable.

    3. Type the path to the subreport's template file (.rpx file). The path is relative to the current template file, so if both files are in the same directory, you can simply enter the file name.

  3. If your subreport contains linked data, set the ReportName property to the ID of the appropriate data link configured in your Geocortex Essentials site. Note that although the ID of a data link is often identical to the display name of the data link, in cases where they are different you must ensure that you use the ID. You can use Geocortex Essentials Manager to verify the ID of a layer's data link.

    A SubReport control selected and LowIncomesSubReport.rpx loaded

    The properties of the control are set to ensure that the template file LowIncomeSubReport.rpx is loaded and executed when the main report executes. The configuration element with ID "SubReport" will be applied and bound to the linked data using the ProjectsDataLinks element.

Group Data

When creating reports with multiple features, it can be useful to group features together that have identical values for fields. For example, in a property report you may want to group all properties in the same municipality together, and avoid having to repeat the municipality name for each individual parcel.

Grouping data in a Geocortex Essentials report is accomplished using group headers and footers in the report template. For each attribute on which you would like to group data, you must add a new Group Header and Footer section by right-clicking on the report template canvas and choosing Insert | Group Header / Footer. Once the new group header and footer have been added, the attribute on which the data is to be grouped should be specified in the DataField property of the Group Header section.

Typically, the field on which the data is grouped is displayed inside the Group Header section, and any summary of group data is displayed inside the group footer section, but you are free to organize the data however you wish.

Note that it is very important that data being grouped is sorted on the grouping field. This sorting does not occur automatically. It must be done inside a report script. While many complex tasks can be performed using scripting, scripting only a sort of the records in the data is straightforward. The simplest method of doing this is by copying the script text below into the Script tab in Geocortex Report Designer, and replacing FIELDNAME with the name of the column on which your report is to be grouped:

public void ActiveReport_DataInitialize()
        {
        rpt.DataSource = ((DataSet)rpt.DataSource).Tables[0].Select(null, "FIELDNAME");
        }

How Data is Bound to a Report

When Geocortex Essentials generates a report, it takes the preconfigured template, the dynamic data from the map, and mashes them together. Understanding how this process occurs is useful both when creating custom functionality in an Essentials as well as when configuring layer and print template reports using the out-of-the-box tools.

A Geocortex Essentials template report can accept data in one of two main formats—DataSet or DataTable. A DataTable is analogous to a single database table or a single Excel worksheet. A DataSet is a collection of DataTables; as such it is analogous to a multi-table database or a multi-worksheet Excel workbook. The actual data to be included in the report is contained inside a DataTable. When a report needs to display data from only a single source (from a single spatial layer, for example), a single DataTable is sufficient. When a report needs to bring together data from multiple different data sources, each with their own combination of attributes, then a DataSet is needed to collect all of the different DataTables together.

Any type of data source that a report can contain—spatial data, linked external data, or map data—needs to be pushed into a DataTable format. In the case of spatial data and linked external data this is easy to visualize. In the DataTable, each separate record (or feature) is represented by a single row in the table, with each attribute representing a single column. So, when a property report is generated in Geocortex Essentials from a selection of 5 parcels, a DataTable with 5 rows is constructed where each row represents a single parcel. If the property report also needs to include owner information retrieved from an external Oracle database, another DataTable is constructed with each row representing a single property owner. This can result in more than five records if there can be multiple owners for each property (a one-to-many relationship).

In the case of map data where a report must display images representing the main map, scale bar and other map elements, Geocortex Essentials constructs a DataTable with a single row and multiple columns. Each column represents a different component of the map; for example, the main map image, the north arrow, scale bar, overview map, etc. Into each of the columns in this DataTable, Geocortex Essentials inserts the raw data representing the map. For images this is the binary image data representing JPG, PNG or other image format. For text (such as the map's current scale) content, it is the raw text which is inserted into the column.

In addition to this single-column DataTable created for the map data, another DataTable is created by Geocortex Essentials to represent the map legend. In this DataTable, each separate symbol for each layer is stored in a single row. Layers which are drawn with a single symbol have a single row in the database. Layers drawn with multiple symbols (using unique values or classified symbology) have multiple rows in the database—one row for each unique symbol and another one for just the layer name itself. If you look at a legend as drawn in one of the default print templates, each distinct line corresponds to a row in the legend DataTable.

Geocortex Essentials collects all of the relevant DataTables required for the report and stores them into a single DataSet, which it provides to the report template. Since a single report template can only display data from a single source (or DataTable), in order to create a report which shows all of the data in the DataSet, a separate subreport must be used for each separate DataTable. When running the report, Geocortex Essentials finds each subreport in the template and assigns the correct DataTable to it—the linked data containing the owner information gets passed to the owner subreport, the map image data gets passed to the map subreport, and so on.

The mechanism by which Geocortex Essentials knows which DataTable to pass to each subreport is by inspecting the ReportName property of the subreport control itself. Geocortex Essentials assigns a unique name to each DataTable in the DataSet which is supplies to the report. The name given to the DataTable depends on what data is being represented. Externally linked data gets stored in a DataTable with a name equal to the ID of the data link that is configured in the site. Map data is stored in a DataTable named MapSubReport. Legend data is stored in a DataTable called _Legend. When a subreport is configured, ensuring the ReportName property matches the correct DataTable name ensures that the correct data is passed into the subreport.

The main (parent) report template is assigned the first DataTable found in the DataSet (at index zero)—Geocortex Essentials does not use a name to determine which DataTable to use. While this is transparent for most interactions with reporting in Geocortex Essentials, it is necessary information if you want to do any custom reporting.

Understanding this process will help greatly if you need to run a report based on dynamic, arbitrary data which has been collected in custom code or inside a custom workflow. The Geocortex Workflow activity called TemplateReport can accept any DataSet which you construct. Since you are in charge of constructing this DataSet rather than Geocortex Essentials, you need to make sure you give your DataTables names which match the corresponding subreport's ReportName property in the main report template.