The root item of the tree is the report itself. From the popup menu, you have access to the Report Properties (Figure 3.3, “Report Properties”. Here, you can change the report name, control settings that apply across the report and control any RenderBegin and RenderEnd scripts for the report as a whole. The RenderBegin script will run before the first section is rendered. This means that it happens before the render sequence is used and before any data is loaded. Therefore you can control the render sequence programmatically. The RenderEnd script is run after all appropriate sections have been completely rendered, allowing some clean up, if necessary.

Keep Page Count: This property is enabled by default, allowing you to use Page count substitutions (i.e. ${##}) within your report. Page counting is expensive because the whole report needs to be kept in memory until the page count is known, only then can the first page be output (presumably showing the page count). If you do not need to show an overall page count, you will get much better memory use by turning off this option. PDF output format is special, in that it allows page counts to be forward referenced, so page counts will still work in PDF even with this option disabled. Therefore, for optimal PDF output (smallest memory use), you should disable this. In all other formats, you will get a value of 0 for page count if this flag is not enabled.

Figure 3.3. Report Properties

Cache All Properties: This property is enabled by default. When rendering a report, each component has an explicit or implicit style associated with it. Searching for the appropriate property to apply, requires checking both the parent hierarchy and any style hierarchy. This is expensive to perform repeatedly. If you know that the styles will not change while the report is being rendered, it is best to cache the styles at the start. This means any subsequent scripted style changes will not be used. If you are manipulating styles at runtime using scripts, then set this value to false, to ensure that the renderer knows the styles are volatile and always identifies the correct style property.

Disable CSV AutoWrap: This property controls the wrapping of text onto multiple lines. By default, text in fields is separated at word breaks and those words are moved to the next line when the field width has been reached. This is usually not appropriate for CSV where there is no field width to consider and the whole record is on one line. By selecting this option, long text that might wrap onto multiple lines is all retained as a single line when rendering into CSV.

Disable Excel AutoWrap: This property controls the wrapping of text onto multiple lines. By default, text in fields is separated at cell breaks and those cells are moved to the next line when the field width has been reached. This is not always appropriate for Excel where there is no field width to consider and the number of cells vary in each file. By selecting this option, long text that might wrap onto multiple lines is all retained as a single line when rendering into Excel.

Grid Enabled: This property enables users to define a snap-to-grid for all components in the report template. This allows for accurate placement and sizing of report components.

Grid Visible: This property toggles the appearance of grid dots in the report template. To customize the appearance of grid, you can specify pixel values in the Grid X and Grid Y fields.

If you have selected a datasource from the Add Report Template wizard then a reference to it as the 'Default' datasource will be included in the repository. A datasource reference is a short name for a datasource file in the repository. For example, the full path might be repository:/Workspace/Samples/Employee.ds, but the reference name can just be Employee. A datasource reference also holds values for any dynamic parameters that the datasource requires. You can add or modify the datasources that the report references using the popup menus in the tree. A report can only use datasources that are listed here, and refers to them by their reference name. Any number of data sources can be defined; each must have a reference name. You can include the same datasource more than once (with different reference names), to allow variations in dynamic parameters, or independent iteration through the records.

Each datasource may be accessed in one of two modes: Table mode or Streamed mode. Select the mode from the DataSource wizard. The default mode is Table mode. When operating in Table mode, the records are loaded into memory so that they can be sorted and grouped and you can query the total number of records. In Streamed mode, only a single record is loaded into memory at one time, which greatly improves the memory efficiency, but prevents complex operations that require access to more than one record. Streamed mode is best suited for operations such as billing, for example, where each customer record has no connection with prior or subsequent records. If you turn off Table mode (therefore adopting Streamed mode), then any operations which depend on the presence of the table, such as sorting, grouping and cross-record operations will fail.

There are two ways of opening a datasource when a report template is already opened. First, in the Data|Shapes|Styles tree panel, right-click the datasource and then select Open DataSource. The same procedure applies to the datasource(s) listed under the Report tab.

A DataSource reference can be copied using the popup menu and pasted into another report template. It can also be pasted into the same report, to make a copy before modifying it.

Datasource(s) added in the Report Tree can do filtering of data without the use of a Composite datasource. However, this is only restricted to filtering. For other operations, a Composite datasource must be used. To filter, right-click or double-click the datasource listed in the Report Tree and then click Next. The filter page is displayed, as seen in Figure 3.4, “Add Filter For DataSource”.

Alternatively, click the Data tab on the right of report layout. Right-click the datasource and select Edit DataSource.... Click Next. The page displayed will be identical to the one seen in Figure 3.4, “Add Filter For DataSource”.

Figure 3.4. Add Filter For DataSource

When a Report Template is created, a 'Default' Page Setup will be added under the Page Setup section of the tree. Each section of the report can have its own page setup, or several sections can share the same page setup. This allows reports to combine landscape and portrait sections, or multi-column and single column sections within the same report. Popup menus on the tree provide the usual abilities to add or modify page setups. The Page Setup Wizard appears as shown in Figure 3.5, “Page Setup”.

Select the paper type from the Paper combo box and also the unit of measurement. The width and height of the paper type will be automatically entered in the corresponding text boxes.

Select the page orientation, either Portrait or Landscape. The number of horizontal pages that the report will span, has to be specified in the Horizontal Pages field. Enter the left, right, top and bottom margin values in the corresponding text boxes and select the unit of measurement from the combo box. Optionally, click Global Properties on the workspace toolbar, and set the default unit of measurement.

Select the Column Count method. Most reports are "Down Then Across", which means the content flows down one column before proceeding to the next. Some templates, such as labels may be need to be "Across Then Down" - each band of the report, e.g. each detail is laid out in subsequent columns of the same row, returning to the first column of the next row when a row is complete.

Figure 3.5. Page Setup

The Column Separation field denotes the space between two columns. Similarly, the Row Separation field corresponds to the space between the rows of data.

A Page Setup can be copied using the popup menu and pasted into another report template. It can also be pasted into the same report, to make a copy before modifying it.

Every report template will have at least one section. A new section can be added using the popup menu of the Sections node. The newly added section will be added to Render Sequence automatically.

The Sections Properties Wizard appears as shown in Figure 3.6, “Section Wizard”. It consists of four tabs: Section, Group and Sort, Watermarks and Scripts.

Figure 3.6. Section Wizard

Section

The name of the section is entered in the text box and the datasource is selected from the DataSource combo box. A section can have no datasource, in which case it will still have a section header and footer, but no details will be generated. This can be useful for special purpose sections, such as cover pages or watermarks.

Select the Keep blank pages option if any blank pages produced during generation should be preserved. Blank pages are usually the result of combinations of page breaks due to the way the report is defined and should usually be discarded. Each section may contain a page header, section header, section footer and page footer. A section header is shown before any details, starting on the first page and a section footer is shown following any details.

By default, each section after the first one, will increment the page number as a continuation of the previous section. If you need the page number to restart again at 1, then select the Reset Page Count option. This will break the report into logical page sequences which will each have individual numbering and page totals. You can also begin a new page sequence within a section by adding an explicit page break with a Reset Page Count option.

A Section can be copied using the popup menu and pasted into another report template. It can also be pasted into the same report, to make a copy before modifying it. A report can have any number of sections.

Within a section, you can refer to fields belonging to the section datasource by their field names. You can also refer to fields belonging to other datasources, but you need to refer to them by their full name. For example, the field Salary in the datasource named Employee would be known as Salary if Employee was the section datasource or as Employee:Salary otherwise. You can only refer to fields in datasources that are referenced by the report template.

Watermark

A watermark can be a valuable addition to your report. May be you want to enhance the appearance of the document by adding a seal or image, or may be you want to add a text watermark that identifies the report contents as a draft or confidential information - the watermark feature in the report helps you accomplish this effortlessly.

A watermark may contain graphics and text that appears behind the main text of the report. It is usually a lighter shade than the text, so you can read the report easily. Watermarks add visual attention and a professional look with the use of imagery such as logos.

Watermarks are very flexible in Elixir Report Designer - a watermark is just another section, either belonging to the current template or a section from any other template in the repository, that is shown behind the main information on a page. Anything you can do in a section can also be done in a watermark. A watermark can contain traditional text and images, but also data, charts, tables and subreports.

When using a section as a watermark, you need to consider its data requirements. If the section has no datasource, for example it is just an image or literal text, you can leave the datasource blank. Also, if the section has a datasource, then that source will be used by default and there is no need to redefine it here. The only time you need to set the watermark datasource is if you need to supply a missing datasource (the section needs one, but does not define one) or if you want to override the existing datasource.

Group and Sort

Grouping is done for categorization of data into various logical collections. Sorting is to arrange the data in ascending or descending order.

In the Group and Sort tab there are four columns - Name, Sort Order, Group On and Group Data. There are five buttons, namely Add, Edit, Move Up, Move Down and Remove.

Click Add to display the Sort dialog. Select the name of the Field to be sorted from the combo box. Select one of Ascending, Descending, Ascending(Simple) or Descending(Simple) sort orders from the combo box.

The differences between Sort (Ascending, Descending) and Sort(Simple) Order:

If your datasource is already sorted (e.g. as a result of an SQL "ORDER BY" clause), then you can select None here. Select the Group On option from the combo box. If a range, substring, etc. is selected as a Group On option then a text box appears where you can specify the value for that range or substring, based on which the grouping will be done. The Show Group Header and Show Group Footer check boxes are selected, if required. Click OK, after entering the values in the Sort dialog, to assign the values to the corresponding Name, Sort Order, Group On and Group Data columns in the Wizard.

Scripts

There are three text fields for the Render If, On Render Begin and On Render End functions. The JavaScript functions that are entered in these text boxes are executed when the report section is rendered. For a detailed explanation of the interactions of scripts when rendering, refer to Chapter 6, Scripting with JavaScript.

Set the values in the tabbed panes and click Finish. The section is then added under the Sections node of the report template.

A Section can be copied using the popup menu and pasted into another report template. It can also be pasted into the same report, to make a copy before modifying it.

Every Report template will have a set of styles. When a new Report template is added, the default style settings will be included for the report elements in the Styles node.

The default style can be edited to suit your requirements. Add a new style by selecting Add Style from the Styles popup menu. A wizard appears as shown in Figure 3.8, “Style Wizard”.

Figure 3.8. Style Wizard

The name of the Style is entered in the text box. Select the style to be included in the report from the All Properties list box and click the > button. The style properties will be added to the Name column and the property can be specified in the value column.

The Base combo box contains the list of styles that have been added to the report template. This is an optional field. If you want to add a new style based on an existing style, then select a Base style from the combo box. The new style will inherit the style properties from the base style that has been selected. The style properties of the Base style will be included along with the style properties that have been set in the new style. When you select the new style that extends the base style for any particular field, the style properties of both the base style and the new style will be set for the field. Click Finish, after setting the properties, to add the style to the Styles section.

If you want to edit an existing style, select Edit Style from the popup menu of the Style option. A style can be copied from the report template of the Styles section and pasted in another report template in the Styles section. It can also be pasted into the same report, to make a copy before modifying it.

The order of precedence in checking styles and their description are given below:

Explicit Named Style: An element placed in the report layout first checks if it has a style associated with it. If for instance, a style has been defined in the master and sub report, then the element placed in the sub report first looks for the style name starting with that of the master report and then the sub report. If there is a style with the similar name in the master report or the sub report, then that style applies to the fields. This is an explicit named style.

Implicit Style: If there is no associated style, then the system checks to see whether there is any default style for the element i.e. if it is a literal field, then it takes the "field-literal" style. See the <cite>RML Raw Model document</cite> for the style names associated with each kind of component.

Inherited Style: The style associated with the parent of this element. If for example, the detail has some style associated with it, then all the elements placed in the detail section will get that style.

Finally, if there is no match found, then it makes use of the global style which is fixed as black.

Some styles can be inherited from the parent, while others cannot be inherited. The styles that can be inherited (defined by CSS) include FontName, FontColor, FontSize, FontBold, FontItalic FontUnderline and FontStrikethrough.

Initially, when a report template is added to the repository, it contains a default section. When a template contains multiple sections, it is the Section Invocation table that controls the order of section rendering. The initial configuration of the Section Invocation table shows that the default section is enabled for rendering.

If a new section is added to the report template and has to be rendered, then click New from the Section Invocation panel. The Render Sequence Wizard appears as shown in Figure 3.9, “Render Sequence”. The render sequence wizard can include sections from both the current report template and other reports in the repository. Choose the report (if not the current report) and then select a section name from the combo box. You can also choose to specify a datasource, which will override any other datasource defined within the section. This allows the same section to be used repeatedly in the render process, with a different datasource each time.

Figure 3.9. Render Sequence

You can edit the Section Invocation details by double clicking the desired column. The Render Sequence Wizard appears in which the values can be altered. Click Finish to save the edited values.

If there is more than one row specified in the Render Sequence table, you can change the sequence in which the sections are being rendered, by selecting the column and clicking the Up and Down arrows.

The Parameters panel is a table containing Name, Value and Enabled columns. The parameter name and value are entered in the corresponding columns of the table. Select the Enabled option to enable the parameter.

The parameters are used to control the way a report is rendered. The parameters can also be used to control data like selecting a range of employees from a list of employees.

If the Propagate data source parameters to report option is selected in the Choose DataSource screen of the Report Wizard, then any datasource parameters are added to the Parameters panel.

When the Propagate data source parameters to report option is not selected in the Choose DataSource screen of the Report Wizard while adding a report template, then the parameter name and value can be added later. Similarly, if you switch over to another data source from the existing data source, or add a new data source that may contain parameters, then you can add the parameter name and value to the Parameters panel by clicking New.

The Parameter details that have been added to the Parameters panel can be edited or deleted by selecting the row and clicking the corresponding button. You are allowed to have multiple parameters with the same name, but only one parameter can be enabled at a time. This allows you to store alternate sets of parameters for different situations without having to re-enter the values.

By default, report jobs are set to time out after 60 seconds. For large reports, you can increase this timeout, using the following parameters:

The following screenshot gives an example of setting these timeouts.

Figure 3.10. Set Report Timeouts

The Layout tab was shown earlier in Figure 3.1, “Report Layout”. It contains the Navigation bar at the top, the parts of the report such as headers, and footers, and the markers in the central panel, the toolbar containing the report components on the left and the Data|Shapes|Styles tree panel and the Properties panel on the right.

Navigation Bar

The Navigation Bar contains the Zoom and Section combo box. The Zoom combo box contains the Zoom percentage. You can select the desired Zoom percentage from the combo box based on which the Report parts will be Zoomed.

The Section Combo box contains the list of sections of the report template. You can select the section for which the layout has to be modified.

The Redo button changes the element to the previously changed stage and Undo button reverts the element back to the state before the change.

The Render Report button is used to open the Render Wizard, as shown in Figure 3.11, “Render Wizard”, to guide you through the report rendering process. Select an output type from the icons shown and click Next to edit any custom properties of that output type. Alternatively, you can immediately press Finish to use the default properties (or the values selected previously, if you are rendering the same report again). The different output types are explained in detail in Chapter 5, Report Rendering and Output Formats.

Figure 3.11. Render Wizard

If you want to repeat a render with the same output type and parameters, you can choose the Repeat Render button, which will by-pass the wizard.

Toolbar

The toolbar contains a set of elements that can be used for adding more features and elegance to the reports. The description and properties of the report elements will be covered in the next chapter on Report Elements.

Horizontal and Vertical Rulers

The horizontal and vertical rulers are used like a scale for page measurements. By default, the width of all the headers and footers in the reports layout remains the same.

The height of the headers and footers can be altered in a report. The vertical rulers are used to measure the height of the headers, footers and the detail sections.

Toggle the Expand/Collapse button to expand or collapse the report parts (headers, footers, etc). When a part is initially in the expanded state, click the button to collapse it. Then the part get collapsed and you will not be able to work on it. If you click the button to expand it again, the part will be expanded and you can continue working on it.

The markers on the horizontal and vertical rulers are used to insert guidelines. To insert your own guideline, click on the horizontal or vertical ruler - a red triangle will appear. To align the fields, drag them to the guidelines. Move the guideline markers on the ruler and all the elements currently snapped to the guideline will automatically move. For Instance, if you place a horizontal guideline in the report header and then drag all the column heading labels to the guideline, you can reposition the guideline marker to automatically move all the column headings up or down. This saves you from selecting and moving each of the column heading labels manually.

When the markers are no longer required then they can be removed by opening the marker popup menu and choosing Remove or by dragging them to the edge of the report layout.

Report parts

The illustration shown in Figure 3.12, “Sample Layout” depicts a typical layout. Although the particular arrangement of these parts will vary depending on the report type and style you have selected, the parts themselves remain constant and can be manipulated in a variety of ways.

The page header can contain information relevant to the current page and appears at the top of every page. The page header might contain the page number, column headings, border lines or a bitmap.

The page footer can contain information relevant to the current page and appears at the bottom of every page. You can use the page footer to print the page total or other pertinent text. Page headers and footers can contain static content, but they are more commonly used to display varying content like page numbers or information about the contents of a page.

The section header contains information that will be displayed at the beginning of each section. The section footer contains information that is displayed at the end of each section in the report.

Figure 3.12. Sample Layout

Group header presents information about the particular data group being viewed - for instance the group name and a brief description about the data contained in the group. The group header appears at the beginning of a new group of records. Group footers might contain totals or other similar information and appears at the end of each group. Group headers and footers can be added by turning on the corresponding options when adding the group column in the Group and Sort tab of the Section.

The Detail section contains the main body of the report's data. The detail section prints individual records, and repeats until all records have been printed. You can expand the Detail section to place multiple fields above or below each other.

Field labels specify the fields displayed in the report. By default, Elixir Report Designer uses the field names from the original data source as the field labels in the report, but you can edit the field labels as needed.

Fields are items of data, from the data source specified in your report.

Data|Shapes|Styles tree panel

This panel consists of the the Data tab, the Shapes tab and the Styles tab.

The Data tab contains the tree view representation of the DataSources that this report references. A new datasource can simply be added under the Data tab by dragging and dropping the datasource from the Elixir Repository to the Data tab. The DataSource fields can be directly selected from the Data tab and placed inside the report layout. The popup menu provides a Refresh option to update the tree if the datasource structure has changed.

The Shapes tab contains the tree view representation of the report parts and the type and names of the fields placed in the layout headers, footers, etc.

The Styles tab contains the tree view representation of the styles of the report parts, fonts, fields placed in the group header, group footer and section label etc. Styles can be added to adjust the report outlook and alignment etc.

Properties Table

The Properties table contains the Name and the Property column. The property name and the corresponding values are listed in the Properties table. When a part of the report or the field placed in the layout is selected, then the corresponding properties are listed in the table.