SpiReport

Members can access extensive documentation for creating reports and labels.

spireport SpecifyiReport

A report is used to present the results of a Query in an attractive and human-friendly arrangement, either on paper or on screen as a report preview.

Specify harnesses the power of iReport 3.0, an open source report writing software package, by modifying the original iReport version to interact with Queries created in Specify 6 and data supplied from the Specify 6 database.  Once within SpecifyiReport, the interface is identical to that of iReport.

The following documentation is meant to explain how to bring a Specify Query into the Specify 6 version of iReport, then create a simple report. 

The Specify staff also provide report-writing services for all members of the Specify Collections Consortium. To benefit from their expertise please contact them at support@specifysoftware.org.

SpecifyiReport ships with Specify but is a separate application and must be launched separately from Specify. SpecifyiReport is located in the Specify application bin directory, which stores the executable files for Specify. Double click the SpecifyiReport executable to launch SpecifyiReport.  As with Specify, you will be prompted for login information. In a multiple collection scenario you will also be prompted for the collection in which you would like to create the Report.

Reports can also be written directly in MySQL and then imported into Specify using the Resource Import/Export tool. The Report needs to include this Report Query "where" clause: "where co.collectionobjectid $P!{itemnum} . Also include a parameter named "itemnum".

Reports are viewed and printed from within Specify. SpecifyiReports does not include a preview. However, users can have both Specify and SpecifyiReport open at the same time and switch between the two to preview the report or changes being made in Specify. You will need to click the Refresh button in the Specify Reports sidebar for changes to be updated. For information on printing reports from within Specify, see Reports.

 

Creating a Report from a Query

Reports are generated by report definitions, which in turn are based on Specify Queries. Therefore, the first step in creating a Report is to create and save a Query within Specify. When constructing the query, remember that checking the Prompt box for a query field will ensure the option to change the criteria for the field before running a report.

Report Components

The following text is meant to familiarize the user with the basic components of SpecifyiReport and will lead the user through the set-up wizard, adding conditions and saving the report.

Choose File > Report Wizard from within SpecifyiReport and choose a saved query to associate with the report.

A Report Properties dialog will appear allowing for basic report set-up.

Report Name is the name that will appear associated with the report in the Specify side bar. Ensure that you name the report appropriately according to its function for optimal use.

Page Size designates the area assigned to the report. Choose a predefined size or create a custom size.

Page Margin delineates the non-printing margins around the page.

Columns can be used to create multiple labels per page or columns of data

Scriptlet Classes are Java classes that can be used to execute special events during printing. Users that are familiar with Java can include custom scriptlets in this tab.

More includes choices for printing title, summary, column footer, pagination, print order and how to handle no data.

i18n allows special Java classes, bundles and encoding to be implemented for printing formatted fields, internationalizing a report and saving source files.

 

Report Bands

Once the preliminary set-up is complete, an empty report template will appear. iReport separates reports into sections, or bands. Data is then printed according to the band definition. For example, a title is printed once, but detail is repeated for every record. Bands can be resized by holding the mouse on the separator line until cross hairs appear, then clicking and dragging the line. Bands can also be removed if not needed by dragging the lower edge of the band onto the upper edge (thereby making its height zero).

Report Band

Description

title

Only created once in the report and can be its own page.

page header

Appears on all pages (except title and summary pages that are included as their own page) in the same position.

column header

Printed at the beginning of each detail column.

detail

Corresponds to every record that feeds the report.

column footer

Appears at the end of every column.

page footer

Appears on every page that includes a page header.

last page footer

Creates a unique footer for the last page.

summary

Allows fields to be inserted for ending statements such as total calculations or means.

 

Text can be added to the report by clicking the static_text_button (static text) button in the Tool Bar, then clicking and dragging a box in the desired band. These are handy for creating captions, titles, headers and footers. Lines, shapes, images and barcodes can also be added using buttons on the tool bar. Simply mouse-over a button for a tool tip displaying its function. These elements are added as static text fields.

Once in a band, fields can be moved by dragging with the mouse or using the Ctrl and arrow keys while fields can be resized by pulling any of the edge or corner handles of an object. Objects can also be manipulated by using the Top, Left, Height and Width commands in the common section of the Properties pane (see below).

Report Panes

Menus on the side and bottom of the Workspace in iReport are called Panes. It is helpful to have three main panes open: Document Structure, Properties and Library. These can be opened/closed in View > Docking Panes. Any item within these panes can be dragged and dropped into a band. When the item is dropped into a band, the expression that represents it is displayed in a Text Field.

Right-button-click on an object within the panes to display a context menu with choices for Edit, Add, Move, Cut, Copy, Paste, Delete, Add a Group and Refresh.

Note: Objects within the panes can also be manipulated via a grid by choosing View > (Fields, Parameters or Variables).

Document Structure Pane

The Document Structure typically opens on the left side and is organized into 3 sections:

  • Parameters are the programmatic values created by Specify to print reports from SpecifyReport.
  • Fields lists the fields in the Query available for inclusion in the report.
  • Drag and drop a field into the detail band for inclusion in the report. The field will display as a 'textField' in the report structure. This refers to the data, or text, that will occupy the field when the report is run. Do not add or delete text inside a text field. The size of the field can be changed by clicking on the field to produce an outline, then grabbing one of the boxes on the outline and dragging it. Change the font or font size for the field data in the Properties pane, or by clicking on it to select it and using the font list box and font size list box in the Tool Bar located at the top of SpecifyiReport. SpecifyiReports are created from Queries and limited to the fields included in the query. Although it is possible to click the report_text_field(text field) button and add a text field with an expression, it will not be recognized when running the report in Specify.
  • Variables lists the elements included in each band along with their horizontal and vertical position on the page.

Cut, Copy, Delete and rearrange the order of elements in these panes by right-clicking on them and choosing the appropriate item in the resulting context menu.

Properties Pane

Objects from the Document Structure that are placed into bands display their properties in this window. The Properties pane includes three sections:

  • Common lists properties for the band such as size, background color, and printing expressions.
  • Text/Graphic offers properties for the text or graphic as well as line spacing.
  • The third section is object specific (Barcode for barcodes, Image for images) and includes some useful expressions. An expressions is a combination of variables, constants, and functions linked by operation symbols. It may be easier to think of an expression as a formula within a report. Expressions are edited using an Expression Editor which can be opened by clicking the ... button next to expression in the list.
  • The properties pane also includes some useful pre-programmed expressions for text.
  • Stretch with Overflow to ensure that long records print correctly without losing text. The field will increase in size based on its contents. This however has implications for closely situated fields as they may be overwritten or overlap.
  • Blank when null will not print the word 'null' for blank records in a report.

Library (sometimes referred to in other documentation as the Object Library)

The library window contains a set of default stored procedures useful to perform common tasks such as Page Number, Total Pages, Page X of Y, Total, Current Date and Percentage.

 

Task Examples

Combining Fields, or creating a concatenated string, is often useful in a report.

  1. Add the first field in the concatenated string to the proper band (by dragging and dropping) and keep it active (a colored box will appear around the field).
  2. In the Properties pane scroll down to the Text Field section. Find Expression in the list. Click the ellipses (...) button on the right hand side.
  3. The Expression Editor will appear. The original field will be included in the top window as an expression. There are 3 boxes under the window, make sure the first box has Fields selected and find the next field in the second box and double click to add it to the top window.
  4. Each combination of fields requires a linking argument in the following format: + "x " + where x is the text string required to link the two fields. 'x' can also be omitted if no linking text is require i.e. + "" +

Note: Typing (+ " " +) between two field expression in this dialog will include whatever text is between quotation marks to appear on the report.

 

Report Groups

Groups allow users to structure the records in a report to better organize the content. A group is defined by an expression and a new group is started when the results of the expression change. A group will only function if the results of a query have been sorted correctly. SpecifyiReport reads the data and 'groups' similar data together as they are ordered. The report can then be structured based on the content of the report.

  1. Click View > Report Groups to open the Group editor.
  2. Click the New button and give the group a Name in the box provided by the Add/Edit dialog.
  3. In the Group Expression window click the Edit button. Click that button to open the Expression Editor.
  4. Click Field in the bottom left panel and double click the desired field in the list (displayed in the middle panel). The field name should appear in the expression window. Click the Apply button.
  5. The field should now show in the Group Expression window of the Add/Edit dialog.
  6. Designating a field as a Group allows choices for each data grouping:
    • Start A New Column will place each data group in its own column.
    • Start A New Page will put a page break at the end of each data group.
    • Reset Page Number starts each data group at page 1.
  7. Print Header on Each Page prints the group header on each page.

Creating a Group will add a Group band and Group Footer band to the report.

 

Including Barcodes

When creating or editing a report in SpecifyiReport it is often necessary to include a barcode. Include a barcode in a string field of a report by following these steps:

  1. Click the barcode button(barcode) button on the tool bar.
  2. Click and drag an outline for the barcode field in the detail band of the report.
  3. In the Properties pane, click the ... button for the Barcode exp. (at the bottom of the pane under Barcode).
  4. The Barcode Expression Editor dialog will appear.
  5. Delete anything that appears in the top box.
  6. Click Fields in the bottom left pane.
  7. Double click on the appropriate field in the middle box. It should appear in the top box.
  8. Click the Apply button.

barcode editor

 

SpecifyiReport supports the following barcodes:

2of7 Code128B EAN13 SCC14Shipping APCA
3of9 Code128C Global Trade Shipment Identifier UPC3
Bookland Code39 Int2of5 SSCC18 UPC4
Codabar Code39(extended) Monarch Std2of5 USPS
Code128 EAN128 PDF417 UCC128  

Saving a Report

Once a report is created to satisfaction, it can be saved by choosing File > Save. A Report Properties dialog will appear:

  1. Type a Name for the Report
  2. Choose the Report Type:
  3. Report or Label are separate report types for purely organizational purposes. Choosing Label will list the report under the Label heading on the reports side bar and choosing Report will list the report under the Report heading.
  4. Invoice reports are listed under Reports in the reports side bar. These are typically created to capture an interaction such as Loan, Gift or Borrow. Reports created from a Loan query are made available when a Loan is saved by checking the 'Print Invoice on Save' box on the Loan form.
  5. Save For refers to level of access given to the report. Discipline will allow all collections within the Discipline access to the report and User will limit the access to the current User only.
  6. Choose a Repeats variable:
  7. Once will create one report/label.
  8. Constant duplicates each record in the report/label and offers a number field for selecting the number of times for the repeat.

Saved reports can be opened from within SpecifyiReport to view and edit by choosing File > Open and selecting either the label or report from the list. It is important to remember when editing a report that reports are created from Queries; therefore, new fields may not be added to a report that are not present in the query. Fields may be removed.