5.) The Designer Interface

Users who have some familiarity with other report writers will recognize the banded-style interface of the Report Designer.  Report elements can be added and modified within the designer window, and then the resulting report can be previewed in the preview window.


Report Designer Interface

5.1.) Report Sections

Each of the bands within the designer interface represents a different report section.  The section names are listed on the buttons to the left of each report band.

5.1.1.) Nested Sections

In addition, the Report Header, Table Header, Group Header, Group Footer, Table Footer, and Report Footer sections, can spawn nested sections.  Nested sections are useful for placing sub-reports, and rich text fields with variable lengths.  This allows these type of elements to re-size without overlapping any elements below. Nested sections inherit most of the section options from their parent sections, including page-breaking and repeating options.

To add a nested section select 'Insert Section' from the section options pop-up menu for the parent section.  For more on section options see section 5.3.  Note that if you select to insert a section from a nested section, it will inherit the same parent section (i.e. nested sections cannot be a parent).

5.2.) Resizing Sections

To resize section height, place the mouse over the section divider within the design window.  The pointer will change to a resize pointer.  Click and drag the mouse to expand or decrease the section height.

5.3.) Section Options

There are several formatting and display options available for each report section.  You can access the section options menu by clicking on the button with the section name at the left-hand side of the designer, or by right-clicking on a blank portion of the section field.


Background Color Dialog

5.4.) Rulers

The Report Designer has two rulers at the top and left-hand edge of the design window.  The rulers measure how the report will look in terms of the physical page dimensions.  (The dimensions do not include page margins.) The rulers allow you to get a good idea of how the printed report would look.  You can also use the rulers to adjust the bounds of elements in your report.  The selected element's bounds will appear as shaded areas within the rulers, and can be adjusted by clicking on and dragging the markers.


Rulers and in/cm button

5.4.1.) Toggling Between Inches and Centimeters

The button in the upper left-hand corner of the design window allows you to toggle between inches and centimeters for the report measurements.  By default, EspressReport uses inches for measurement.  Depressing the button will change the ruler measures to centimeters.  If centimeter is selected all of the manually entered values like element bounds and page margins will also be entered/displayed in centimeters.

You can set Report Designer to run with metric (cm) measurements as the default.  To do this, specify an additional command line argument - metricSystem:true/false when executing the ReportDesigner.bat/.sh file.  For example: ReportDesigner -metricSystem:true will launch Report Designer with metric measurements.  You can also add this argument in the batch file itself.

If you're running Report Designer through an applet, you will need to add the following parameter to the applet HTML page: <PARAM NAME="metricSystem" VALUE="true">.

5.5.) Designer Menus

Most of the Report Designer's features can be controlled by using the drop-down menus at the top of the designer.

5.5.1.) File Menu

This menu performs most of the file operations.

5.5.2.) Edit Menu

This menu allows you to edit and cut/paste report elements

5.5.3.) Insert Menu

This menu allows you to insert elements into the current report.

5.5.4.) Format Menu

The format menu contains the formatting options for the currently selected element within the report.  Some menu options will not work depending on the type of element which is currently selected.

5.5.5.) View Menu

The view menu contains options allowing you to navigate through the report in the preview window, and sort the data. It is only active when you are previewing the report.

5.5.6.) Data Menu

The data menu contains options that allow you to see and manipulate the data used in the current report, and its properties.

5.5.7.) Drill Down Menu

The drill down menu contains options that allow you to add, remove, and navigate layers of drill down within the report.  For more on drill down, please see Chapter 10.

5.5.8.) Option Menu

This menu contains display and printing options

5.6.) Designer Toolbar

The toolbar at the top of the designer offers easy access to EspressReport's most commonly used features. The first row of buttons perform the following functions:

 Start a new report  Open an existing report
 Save the current report  Export the current report
 Apply a template to the current report  Selection box for group selection
 Cut the selected element and place it on the clipboard  Copy the selected element
 Paste the current clipboard object into the report  Delete the selected element
 Insert a label  Insert a formula
 Insert a column field  Insert a rich text field
 Insert a sub-report  Insert a horizontal line
 Insert a vertical line  Insert a grid rectangle
 Insert a chart   Insert an image
  Insert the current date   Insert page number
  Change Data Mapping   Change Data Source
  Edit Query

The first two boxes in the second row of the toolbar allow you to select the font face, and size for the currently selected element.  The buttons in the second row perform the following functions:

  Set the font style to bold   Set the font style to italic
  Underline the text   Set the horizontal alignment to left
  Set the horizontal alignment to center   Set the horizontal alignment to right
  Edit the selected element   Set data formatting for the current element
  Apply a script to the current element   Set the font color for the current element
  Set the background color for the current element   Set the border thickness for the current element
  Set the border color for the current element   Set dual colors for the current element
  Set bounds for the current element   Page setup
  Limit preview display rows

5.7.) Inserting and Manipulating Report Elements

When you finish with the report wizard, a rough version of your report will be generated based on the mapping, and display options you selected. To polish the report, you may want to insert new report elements, as well as format the existing elements.

5.7.1.) Inserting Elements


Insert Label Dialog


Formula List & Formula Editor


Insert Column Field


Insert Database Field Dialog


Insert Column Header Dialog


Insert Parameter Value Dialog


Insert Image Dialog


Background Image Dialog

5.7.1.1.) Inserting Charts

You can insert a chart in one of two ways, by selecting 'Insert Chart' from the Insert menu, or by clicking on the insert chart button on the toolbar.  After you select this option a small box will follow your mouse pointer around the design window.  Position the box where you would like to place the chart and click.  You will see the following dialog box:


Insert Chart Dialog

You have the option to use data from the current report or use an external data source.  If you choose to use the data from the report, you will be shown a preview of your dataset and be taken directly to the chart selection window in the Chart Designer. Otherwise, you will be given the chance to select a different data source for your chart.

Once you have selected your options, the Chart Designer will open in a new window, allowing you to design and customize your chart.  Please see the Charting Guide for about using the Chart Designer.

Note that the actual chart will not appear in the design window.  Instead, you will see a gray rectangle with the chart URL. You can see the actual chart in the preview window.

If your report contains grouping (Summary Break, CrossTab, or Master & Detail Reports), you also have the option to 'Include Section Data'.  If you select this option, you will be able to use group aggregations that are located within any section that the chart encompasses.  This means that you can create charts using data from any aggregation located in the same section as the chart or in any inner sections.

For example, if you were to create a Summary Break Report with two row break columns, this will result in two group header and two group footer sections.  Let us also suppose that you have a group aggregation for a column in your report. The report might look like the following:


Summary Break Report with Two Row Break Columns

If you position the chart in the inner group header (Group Header 1) or inner group footer (group footer 1), you will only be able to use the group aggregation for the inner section in your chart (the aggregation in Group Footer 1).  If you positioned the chart in the outer group header (Group Header 0) or outer group footer (Group Footer 0), you will be able to use the aggregation for the outer section as well as the inner section in your chart because the outer section encompasses the inner section.  Positioning the chart in the table header or table footer sections will allow you to use any group aggregation in the report.

Suppose you moved the column headers to Group Header 1 and positioned the chart in Group Header 0 as shown below.


Insert Chart in Outer Group Header

When you see the data mapping window in Chart Designer, you will be able to use the summary data from both Group Footer 0 (TBL0_F_SEC0_FORM0) and Group Footer 1 (TBL0_F_SEC1_FORM0).


Chart Mapping with Section Data

To make the aggregation easier to recognize, you can use Custom IDs. For more information on using Custom IDs, see section 8.2.1.

The resulting report looks like the following, notice that the chart plots the aggregation for each company.  If you used the aggregation from Group Footer 0, the chart would have shown the aggregation for each region instead.


Report with Chart Using Section Data (East)

Since the chart is placed in Group Header 0, a new chart will be displayed for every region. The above image shows the chart for the East region only, but the report will contain charts corresponding to each of the other regions as well.  Here is the chart for the Midwest region.


Report with Chart Using Section Data (Midwest)

Keep in mind that if you select the 'Include Section Data' option, the data available to the chart will vary between sections, so moving the chart between sections is not recommended.  If you must move the chart after it is made, make sure that the data mapped to the chart is also available from the location where you are moving the chart to.

Here is another example using 'Include Section Data'.  Suppose you had the following CrossTab report and you wanted to use the aggregation for each column as data points in your chart.


CrossTab Report with Group Aggregation

To make the aggregations easier to use later, give each group aggregation a Custom ID that match their column header. For example, give SUM(COL(1)) the ID 'East', give SUM(COL(2)) 'Midwest', and so on.  For more information on Custom IDs, see section 8.2.1.  Then insert the chart in the Table Footer Section using Report Data and Include Section Data.


Insert Chart in Table Footer

Since the data points are in different aggregations, you will need to use the transpose feature at the data preview screen to coalesce the separate aggregations into one data column.  For more on the transpose feature, see Charting - section 3.2.


Transpose Group Aggregations

Then, in the data mapping window, select the 'ColumnLabel' for the Category (X) and the 'Value' for the Value (Y).


Chart Mapping for Transposed Data

Depending on the type of chart you select, the finished report might look like the following.


Report with Chart Using Section Data

5.7.1.1.1) Inserting Summary Charts into Fixed-field Crosstab Reports

You can also insert summary charts into fixed-fields crosstab reports.  A summary chart is a type of chart that is created from summarized data of a fixed-field crosstab report.  For more information about fixed-field crosstab reports, please see Designer, section 4.3.3.

When you are going to insert a chart into a fixed-field crosstab report, you will still have the option to use data from the current report or use an external data source.  Otherwise, you will be given the chance to select a summary data source for your chart.  Note that a summary chart can only be inserted into the Table Header/Footer sections, dependently on the Formula Position.  For example, if you have created a fixed-field crosstab report with the formula position set to be drawn in the Header section, you can only insert a summary chart into the Table Header section.  If you try to insert chart to other report sections, the 'summary data' option won't be available in the Insert Chart dialog.


Insert chart dialog

For example, say we have the following data mapping for a fixed-field crosstab report.


Data Mapping

We selected Day as a 'row break' field, Drink and timing as 'column break' fields, quantity as a 'column break value' field with an aggregation of 'Sum'.  We also chose the 'Formula Position' to be drawn in the Table Footer section of the report, which means we have to insert the summary chart into the Table Footer section in which data will be summarized.

Inserting a summary chart into the table footer section and selecting the 'Summary Data' as datasource in the 'Insert Chart' dialog will show the following Query Result dialog.  The dialog shows data that will be used for a summary chart.


Query Result

Depending on the type of chart and formatting you select, the finished report might look like the following.


Report Preview

5.7.1.2.) Inserting Elements into the Table Data Section

Generally when elements are inserted into a report section, they will repeat each time that the report section repeats.  However, this does not apply when certain elements are inserted into the Table Data section.  Charts, images, and sub-reports when inserted into the Table Data section, do not repeat for each row of data (labels, column fields, and formulas do).  This allows you to design a report in a side-by-side configuration where you might have a chart, or sub-report placed next to a data table as pictured below.


Side-by-Side Data Table & Chart

Normally, when you insert a chart, image, or sub-report into a report section you will want to re-size the section so that the entire element fits within the section (otherwise it is truncated).  This is not the case for charts, images, or sub-reports inserted into the Table Data section.  In this situation, you will want to keep the section the same height as your column fields regardless of the size of the element you're placing in the section.


Side-By-Side Data Table & Chart (Designer)

You can size the element in the Table Data section, using the rulers, or by temporarily re-sizing the section to adjust the element size.

5.7.2.) Editing Elements

You can edit elements in one of four ways: by selecting 'Edit' from the 'Format' or 'Edit' menu, clicking on the edit button in the toolbar, right-clicking on the element, and then selecting 'Edit' from the pop-up menu, or by double-clicking on the element.


Edit Column Header Dialog

You can also copy and paste cell attributes between report elements.  This will apply all attributes including data formatting (assuming the data types are the same), alignment, font, color, and border attributes, as well as the bounds of a cell.

To copy the attributes of an element, right-click on the element, and select 'Element Appearance' from the pop-up menu.  This will expand in to two additional choices.  Select 'Copy' from the second menu.  To apply the copied attributes to another cell, repeat the same steps as before, and select 'Paste' from the secondary menu.

5.7.2.1.) Editing Element Attributes

In addition to directly editing an element, you can directly access all of an element's attributes by right-clicking on an element, and selecting 'Edit Attributes' from the pop-up menu.  This will bring up a tabbed dialog that allows you to set a number of properties for the element at once.


Multi-Attribute Editing Dialog

The options will vary depending on what type of element you select.  For each tab in the dialog, you can set the option that you would like, and them click the 'Apply' button to set the changes for that attribute.

5.7.2.2.) Word Wrapping

By default, any text within report elements, including labels, formulas, and columns will wrap to the next line if the cell boundaries are not wide enough to fit the text.  This behavior, however, can be disabled.  To set text wrapping select an element and select 'Wordwrap' from the Format menu, or right-click on an element and select the option from the pop-up menu.  This will bring up a dialog allowing you to enable/disable text wrapping.


Word Wrapping Dialog

To disable word wrapping, un-check the option and click 'Ok'.  Note that when word wrapping is disabled the entire contents of the cell will be printed regardless of the cell boundaries.  This can overlap and obscure other report elements.  Also, word wrapping cannot be disabled for rich text fields, and the rich text and Excel exports will still display the wrapped text.

5.7.2.3.) Editing Side-By-Side Master & Details Reports

As noted in section 4.4 of this guide, you can specify a side-by-side layout for master & details reports.  This will print the master field (group header) next to the details section (table data), rather than it's traditional position above the details section.  When you select this report format, the master section will appear as a gray rectangle next to the column fields within the table data section of the report.


Side-by-Side Master & Details

The master section can be moved in free-form like any other report element.  You can edit the contents of the master field in one of three ways: by selecting it and clicking the 'Edit' button on the toolbar, by right-clicking it and selecting 'Edit' from the pop-up menu, or by double clicking it.  The master section will then open in a new window, allowing you to modify its contents.


Edit Master Section Dialog

The elements in this section can be moved, resized, and edited in the same manner as other elements in the report.  The master section acts the same as a group header section.  It repeats for each unique value in the primary key column.  After you have finished editing the contents of the master section, it can be closed by selecting 'Close' from the File menu.

*Note - After you finish editing the master section, it will automatically resize to fit its contents.

5.7.3.) Data Formatting for Formulas and Column Fields

You can change the output of formulas and column fields in one of three ways: by selecting 'Data Format' from the Format menu, by clicking the data format button on the toolbar, or by right-clicking on a formula or column field and selecting 'Edit Attributes' from the pop-up menu.  When you select the format option a dialog box will appear (or the format tab of the multi-attribute editing dialog).  The box that appears is dependent on what type of data is present in the selected element: numeric, string, date/time, or logical/Boolean.


Numeric Format Dialog


Locale-Specific Formatting


Fixed Point Formatting


Bar Code Formatting


Scientific Formatting


String Data Format


String Formatting


Bar Code Formatting


Date/Time Data Format


Locale-Specific Formatting


Standard Formatting


Boolean Data Format

5.7.3.1.) Formatting Null Data

By default null data will display in a report as "Null".  You can change the appearance of null data by selecting 'Null Data Handler' from the Option menu.  This will bring up a dialog, prompting you to specify a string to be displayed for nulls.


Null Data Handler

Enter the value that you would like, and click 'OK'.  All the null values in the report will display as the value you specified.

5.7.4.) Line/Rectangle Format

You can format the appearance of lines and rectangles in the report by right-clicking on a line or rectangle element.  The pop-up menu will contain a list of available options.

5.7.5.) Chart Export Format

This option allows you to specify the attributes for charts exported to HTML (not applet), and DHTML.  You can format the chart export properties by selecting 'Chart Export Format' from the Format menu, or by right-clicking on a chart, and selecting 'Export Format' from the pop-up menu.  When you select this option a dialog box will appear.  You can select GIF, PNG, or JPEG for the image type, and set some options for each type.  For GIF images you can set the background to be transparent.  For PNG images you can set the compression. For JPEG images you can set the quality (Image quality is directly proportional to file size).

You can also specify to create an image map when the report is exported.  If you create an image map, and hyperlinks defined in the chart will be active when the report is exported.  If no hyperlinks are defined then the map will contain display pop-up labels for the chart containing data point information.


Chart Export Format

5.7.6.) Font, Color, and Border Options

You can change the appearance of report elements by changing the font, color, and border properties.


Font Style and Size Dialog


Font Color Dialog


Background Color Dialog


Dual Colors Dialog


Border Thickness Dialog


Border Color Dialog

5.7.6.1.) Show Cell Outline

Sometimes you may want to show the boundaries/borders of report elements in the Design Window, without actually turning on the borders.  This is especially important if you have blank place-holder cells, or columns where the first record is empty.  To turn on the cell boundaries, select 'Show Cell Outline' from the Option menu.  This will draw a gray dotted border around each report element in the Design window.

5.7.7.) Rich Text Fields

One of the common reporting needs is the ability to create form letters or other blocks of formatted text to a report, and merge in data fields and functions.  This functionality is available using rich text fields.  Rich text fields, unlike labels or string function fields, allow for complex paragraph, font, and color formatting within the cell, as well as the ability to embed column fields, and functions directly in the text flow.

To add a rich text field to a report, select 'Insert Rich Text Field' from the Insert menu, or click the 'Rich Text Field' button on the toolbar.  After you have selected this option a small box will follow your mouse pointer around the design window.  Position the box where you would like to insert the field, and click.  A new window will open allowing you to enter the rich text field.


Rich Text Editor

The rich text editor works like a small word processor.  The first drop-down box allows you to select the font, and the second the font size.  The three buttons allow you to specify bold, italic, or underlined text.  The next drop down box allows you to specify font color, and the last one allows you to select function/column field formats.

You can specify a columnar layout for the text by selecting 'Columns' from the Option menu.  This will bring up a dialog allowing you to specify the number of columns for the rich text field, as well as the spacing between the columns.


Rich Text Column Options Dialog

You can add in-line images to the text flow in rich text fields as well.  To add an image, select 'Insert Image' from the File menu.  This will bring up a dialog prompting you to specify the image file that you would like to import.  After you have specified the file that you would like to import, a new dialog will open, allowing you to specify the size for the in-line image in pixels.  After you set the size, click 'Ok' and the image will be added to the rich text field.

You can import any rich text file (.rtf format) into a rich text field.  To do this select 'Import' from the File menu in the editor.  This will bring up a dialog prompting you to specify the file you would like to import.

*Note - Certain paragraph settings will be lost when you import a rich text file.

5.7.7.1.) Adding Formulas

You can add any formula directly into the text flow in a rich text field.  It is also possible to add column fields and database fields, however they must be added using formula syntax.  Formulas are denoted using special start and stop characters.  To add a formula simply types "<%Formula Syntax%>".  For more information about formula syntax, please see Chapter 8.

To format formulas and column fields, you must first pre-define a format.  To do this select 'New' from the editor Format menu, and select the data type for which you would like to create a format.  This will bring up the formatting dialog for that data type allowing you to define the format.  After you close the formatting dialog, you will be prompted to specify a name for the formatting.  For example, you could define a format called "Currency" that uses locale-specific currency formatting for numbers.

To apply a pre-defined format of a formula, select the formula, and then select the format that you would like to apply from the drop down box on the right-hand side of the rich text editor.

5.7.8.) Hyperlinks

You can apply a hyperlink to any report element except column fields.  To apply a hyperlink to an element, select it and then select 'HyperLink' from the 'Format' menu, or right-click on the element and select 'HyperLink' from the pop-up menu.  A dialog box will then pop-up asking you to enter the link, hint, and target. You can enter any URL as the link, or another .rpt file.  The hint will display text in a hint box on mouse over when the report is viewed.

If you are running EspressReport in stand-alone mode, then hyperlinks to URL's will not work from the preview window.  If you export to HTML, DHTML or PDF, links to .rpt files will no longer work.


Hyperlink Dialog

You can also apply dynamic hyperlinks to report elements including column fields using cell scripting.  For more about cell scripting, please see Chapter 9.

5.7.9.) Column Wrapping

This feature is useful for reports that have few, or narrow columns of data that are longer than one page.  Rather than have the data take up only a portion of the page width, and extend over multiple pages in length, you can 'wrap' the columns so that they will continue to the right of the original columns on the first page of the report.

For example, say you have the following report listing product names, and the number of units ordered:

Product Name

  

Units Ordered

Adad Chair

  

4

Addad Dresser

  

5

Amon Table

  

2

An Chair

  

5

Anahita Dresser

  

3

Anubis Table

  

7

Apep Table

  

10

Apsu Dresser

  

3

Asherat Dresser

  

2

Atun Table

  

4

Bast Table

  

4

Bes Table

  

3

Cula Chair

  

10

Enki Chair

  

12

Enlil Chair

  

7

...

  

...

...

  

...

Assuming this report is long enough to encompass multiple pages, using column wrapping is ideal because it uses fewer pages, and fills the blank space in the page width.  With column wrapping the report would look the following:

Product Name

Units Ordered

  

Product Name

Units Ordered

Adad Chair

4

  

Bast Table

4

Addad Dresser

5

  

Bes Table

3

Amon Table

2

  

Cula Chair

10

An Chair

5

  

Enki Chair

12

Anahita Dresser

3

  

Enlil Chair

7

Anubis Table

7

  

...

...

Apep Table

10

  

...

...

Apsu Dresser

3

      

Asherat Dresser

2

      

Atun Table

4

      

Column wrapping is available for simple columnar and summary break report types.  To implement column wrapping, select 'Column Wrap' from the Format menu.  A gray vertical bar will be drawn across the middle of the design window indicating the column wrapping placement.


Column Wrapping in Design Window

Column wrapping begins immediately to the right of the bar, so be sure to allow adequate space.  Also, anything to the right of the column wrap bar will be truncated.

You can edit the column wrap properties by first selecting the column wrap bar, and then selecting 'Column Wrap' from the Format menu, or by right-clicking on the column wrap bar, and selecting 'Column Wrap' from the pop-up menu.  A dialog box will then appear allowing you to edit the properties of the column wrapping.


Column Wrapping Options

From this dialog you can specify the x position of the column wrapping, as well as the number of times you would like the columns to wrap in the page.  The x position is the distance (in inches or centimeters) from the right hand side of the page, where column wrapping is to begin.  By default, column wrapping occurs once.  Setting 'Repeat Wrap' to "-1" will cause the wrapping to occur as many times as can fit within the page width.

*Note - you cannot specify column wrapping to occur more times than can fit within the page width.  For example, if you specify three times, and the resultant report would be wider than the page, it will only repeat the wrapping twice.

5.7.10.) Table of Contents

EspressReport has the ability to generate a table of contents for your report.  The table of contents can either show the defined groups in the report, or a list of user-defined bookmarks.  The TOC will display in report viewer, page viewer, HTML, DHTML, and PDF exports.

5.7.10.1.) Adding a Table of Contents

To add a table of contents to a report, select 'Insert Table of Contents' from the Insert menu.  Your cursor will turn into a cross.  Click to place the table of contents in either the Report Header or Table Header sections.  You cannot add it to any other section.  A dialog will open asking you if you would like to use groups, or bookmarks for the table of contents.


TOC Type Dialog

If you elect to use groups the table of contents will generate an entry for each group (and sub-group) in the report.  In order to use this option your report must contain grouped data (i.e. summary break, crosstab, master & details reports) with detail records.  A crosstab report with one row break, or a summary break report with column aggregation may be grouped, but because there are no detail records you cannot create a table of contents for this presentation.  If you elect to use bookmarks, a one-level table of contents will be generated for each bookmark that is defined in the report.  Bookmarks are defined using cell scripts, for more information about setting them, see section 9.2.1.

The next dialog that appears allows you to specify options for the table of contents


TOC Options Dialog

The first option in this dialog allows you to set the font for each level of the table of contents.  When you click the 'Select Font' button a new dialog will open allowing you to specify font options.


TOC Font Dialog

For each level you can set the font face, style, size, and color.  Note that a level corresponds with a level of nested grouping in the report.  If you've elected to create a report with bookmarks only the top level will be available.  Sub-levels can inherit the font from the parent level.  After you've made changes for the font for a particular level, click the 'Apply' button to save the changes.

The next option allows you to select whether to show numbering for the table of contents and the style to use.  You can customize some options for each style by clicking the 'Customize' button.  The following styles are supported:


Customization options for TOC Decimal Format


Customization options for TOC Outline Format

The next option allows you to specify indentation for sub-groups.  You can turn on/off the indentation, and specify the number of spaces to use.

The next option allows you to specify whether to show the page number in the table of contents, and whether to draw a spacer to the page number.  You can draw a dotted line or a solid line for the spacer.

The last option in the dialog allows you to set the layout for the table of contents, either right to left, or left to right.  Once you have finished setting options for the table of contents, click 'Done' and it will be added to the report.

In the report, the table of contents will appear as a small grey rectangle.  By default the resize to fit content option will be turned on, but the width of the table of contents will be based on whatever size you alot for it in the section.  Generally you want to make this at least as wide as your report.


TOC in Design Window

When you preview the report you can see the complete table of contents.  The table of contents is only supported for the HTML, DHTML, and PDF exports.  It will not appear if you export the report to other formats.


TOC in Preview Window

5.7.11.) Moving and Resizing Report Elements

There are several ways to move and re-size report elements.  You can use the rulers, the mouse, or you can manually enter the element bounds.


Set Bounds Dialog


Dynamic Resize Dialog


Group Options/Alignment Pop-up Dialog

5.7.11.1.) Controlling Element Overlapping

In EspressReport, each element in a report has an associated Z index.  This Z index number determines how elements behave when placed in the same space (on top of each other).  When elements are placed in the same space, the element with the highest Z index will appear on top, and subsequent elements with the lower Z indexs will be drawn successively below each other.  To set the Z index for a report element, right-click on the element and select 'Set Z-Index' from the pop-up menu.  This will bring up a dialog allowing you to specify a number for the index of that element.


Z Index Dialog

*Note - certain export formats that require a tabular layout, like HTML and Excel may not appear correctly if the report has elements that overlap each other.

5.7.11.2.) Locking Element Position

In Report Designer, you can set a cell position to be locked, by right-clicking on the element, and selecting 'Lock Position' from the pop-up menu.  When this feature is enabled the report element cannot be moved either with the mouse, the rulers, or with any of the group formatting or alignment features.  The element can only be moved after the lock position option is turned off.

5.7.12.) Snap to Grid

By default, Report Designer operates in 'Snap to Grid' mode.  This forces report elements to move only in set increments.  The grid layout is represented by small dots drawn in the design window.  By default the grid step size is 0.1 in or 0.25 cm (depending on which measurement is selected).

To modify any of the snap to grid options, select 'Snap To Grid' from the Option menu.  A dialog will open allowing you to set grid properties.


Snap To Grid Options

In this dialog, you can elect to change the grid step size, or disable the snap to grid feature.  If you disable snap to grid, then the report elements can be moved in free-form around the design window.

5.7.13.) Shift Mode

Shift mode is toggled on and off by selecting 'Shift On/Off' from the 'Option' menu.  When shift mode is enabled, report elements will move to accommodate changes in other report elements.  Hence, if you resize the width of one report element from 1" to 2", then the elements next to the current element will shift to the right.  If shift mode is not selected than other report elements will not move, even if the resized element ends up overlapping another.

*Note - Shift mode works best if you are only resizing elements, or moving them a small amount.  If you move elements a pronounced distance with shift mode enabled, it will displace the other report elements a pronounced distance as well, giving the report an odd appearance.

5.7.14.) Guidelines

Another way to position and move groups of elements is to use guidelines.  Guidelines allow you to place arbitrary position lines within the design window, and snap report elements to those lines.  Guidelines allow you to precisely line up and position the report elements without worrying about performing precise movements.


Elements Positioned with Guidelines

5.7.14.1.) Inserting Guidelines

You can insert both horizontal and vertical guidelines by selecting 'Insert Guideline' from the insert menu.  This option will open a sub-menu, prompting you to select whether you would like a vertical or horizontal guideline.  After you select which option you would like, click in the design panel where you would like the guideline to be drawn.  The guideline will appear as a dotted line with a marker in the upper or left-hand ruler.  You can move the guideline by clicking and dragging the marker in the ruler.

You can remove any guideline from a report, by right-clicking on the guideline (or the guideline marker in the ruler) and selecting 'Delete' from the pop-up menu.

*Note - Horizontal guidelines cannot be moved between report sections.  If you wish to move your guideline to a new report section, you will need to insert a new guideline.

5.7.14.2.) Positioning Elements with Guidelines

There are two ways in which objects can be snapped to guidelines. The first option is to snap all the elements that are near the guideline.  To do this, right-click on the guideline (or the guideline marker in the ruler) and select 'Snap Elements in Range'.  You can then further select to snap the cells' left edge, right edge, or center.  This will snap all the cells that are up to 0.1 inches away from the guideline.

The other option is to selectively snap elements to guidelines.  To do this, first select the elements you would like to snap to the guideline using control+click (you can select only one element, but you must use control+click to select it), then right-click on the guideline (or the guideline marker in the ruler) to which you would like to snap it.  For both horizontal and vertical guidelines you can specify to snap the cell's left edge, right edge, or center to the guideline.  Select the option you would like from the pop-up menu and the cell(s) will snap to the guideline.


Guideline Positioning Options

Once an element is attached to a guideline, moving the guideline will cause the element to move as well.  You can also snap an element to multiple guidelines.  Snapping an element to two guidelines, will cause it to stretch to fit.


Element Snapped to Two Guidelines

When you have an element attached to two guidelines, moving either guideline will cause the element to resize (either stretch or shrink).

To release an element from a guideline, right-click on the element, and select 'Separate From Guidelines' from the pop-up menu.  This will release the element from any guidelines to which it is attached.  You can also release all of the elements attached to a guideline by right-clicking on the guideline (or the guideline marker in the ruler), and selecting 'Separate All' from the pop-up menu.

5.8.) The Report Explorer

In addition to the main design window, EspressReport provides another interface to select and edit the elements in a report, the report explorer.  The report explorer presents all of the elements in the report using a tree structure that is shown in the left-hand side of the designer.  The explorer can be turned on and off by selecting "Report Explorer" from the Option menu.


Report Explorer Window

Each parent node in the tree represents a section in the report.  Inside each section, an icon indicates the element type, and the element ID is displayed.  If you have specified a custom ID for the element, it will display instead.  For more information about custom IDs, see section 8.2.1.

You can also edit report elements from within the explorer.  When you select an element in the tree, the element will also be selected in the design window, and the design window will scroll to bring that element into view on the screen.  You can then use the toolbars, menus, or pop-up menu to set any of the element properties.  The pop-up menu can also be activated by right-clicking on the element in the tree.

5.9.) Global Formatting, Group Formatting, and Templates

To this point you've seen how to edit and format the properties of individual report elements.  Often times in the name of time and consistency, you will want to format many elements at once.  To accomplish this you can use global formatting, group formatting, and templates.

5.9.1.) Global Formatting

The global formatting feature allows you to give all of the elements in your report a consistent look and feel.  To set the global formats select 'Global Format' from the 'Option' menu.  This will bring up a second menu with each of the different report element types listed: chart, column, formula, image, label, line, grid, and column header.  Selecting one of these will bring up a tabbed dialog box prompting you to set the formats for those elements.  Each tab contains formatting options for an element attribute. The formatting options are as follows:

At the bottom of each tab is a checkbox marked 'Apply Property'.  Checking this box will apply the property to the global formats when you click 'OK'.  The box automatically becomes checked when you change a property.  After you have made all of the property changes you would like, clicking 'OK' will cause the properties you selected to change for all elements of that type in the report.  It will also become the default attribute for any additional elements placed in the report.

*Note - You have the option to insert images in the original size (default attribute).  This is selected by using the checkbox marked 'Default Size' in the 'Set Bounds' tab of the image global format dialog.


Global Format Dialog

5.9.1.1.) Global Format Import/Export

You can pass global formats from one report to another using the Import/Export feature.  You can export global formats by selecting the 'Export' from the Global Format sub-menu.  This will bring up a dialog box prompting you to specify a file name.  The global formats will then be saved as an XML file.  You can load a global format XML file by selecting the 'Import' option from the Global Format sub-menu.  This will bring up a dialog box prompting you to specify the XML file that you would like to import.  Click on 'OK' and the formats stored in the XML file will be applied to the current report.

5.9.1.2.) Global Formatting & Crosstab Reports

Global formatting is very important when dealing with crosstab reports.  Due to the nature of the report the number of columns can increase/decrease depending on changes in the data, data source, or filtering criteria.  When new columns are generated in a crosstab report they will take on whatever default formatting is specified.  In order to control the appearance of new columns in a crosstab report, you will need to set the default formatting using global formats.

Global formatting is also important because it will control the intervals that new columns appear in the report.  New columns will appear in intervals defined by the column width in the global formats.  Therefore if you set the default width to be inch, new columns in the crosstab report will appear at one inch intervals.  Because of this, it is recommended that you maintain consistent widths for the data columns in a crosstab report.  Setting different widths can result in unexpected behavior when new columns are added to the report.

5.9.2.) Group Formatting

To apply formatting to a group of elements, first select a group of elements, by either drawing a selection box around them, or by using control + click.  You can insert a selection box by either selecting 'Selection Box' from the 'Edit' menu, by clicking on the selection box button on the toolbar, or by clicking and dragging in an empty portion of a report section.  You can also select a row or column of cells by right-clicking on a cell and selecting the 'Select Column' or 'Select Row' option from the pop-up menu.  If you want to move or resize the group, you must use one of these two options.  If you merely want to format properties, then you can select multiple elements by pressing control + click.

Once you have selected the group, format the properties as you would for a single element.  Formatting will only take effect on elements where it is applicable.  For example, if you select four elements, two labels, a formula, and a chart, and then change the font size, it will have no effect on the chart.

5.9.3.) Applying a Template

The features and elements of any report (.rpt or .xml) file can be applied to another report.  This is accomplished using the apply template feature.  To apply a template to the current report select 'Apply Template' from the 'File' menu, or click on the apply template button on the tool bar.  A dialog box will appear prompting you to select the file that you would like to apply. When you apply a template, all of the elements and their respective formatting will be applied to the current report.  Only the data source information is not carried over (this includes functions and scripts in the table data section of the report).


Apply Template Dialog

There are two additional options available in the dialog.

If you would like to have a report that merely has the same look and feel as another without replacing the labels, formulas, etc., you can accomplish this by using the global format import/export feature rather than applying a template.

5.10.) Report Designer in Mac OS X


Report Designer in OS X

When running Report Designer in OS X most of the controls are the same as for Windows or Unix/Linux, with two exceptions:

EspressReport also works well with Apple's WebObjectsTM.  For more details about developing and deploying using EspressReport in a WebObjects application, see Chapter 6 of the Programming Guide.