Version 4 > Developer's Guide > Reports

Reports

ReportBuilder supports several new features in V4:

Compact Reports

If the number of columns exceeds a configurable value (10 by default), reports automatically switch to more compact CSS. A link to toggle the compact view will be added to the report footer.

To change the number of columns that triggers this CSS change, using the configuration setting report.compact_columns.

Compact views use the ellipsis overflow CSS rule, which truncates data, and keeps it to a single line. This keeps your report entirely within your horizontal screen space, and maximizes the number of rows visible at once. If you toggle back to normal view, the report may exceed your page margins.

Saved Reports

Reports can be saved and reloaded later by a different process:

$report->save("unique key",$optional_number_of_days);

The second days parameter determines how long the report will be saved for. Later, you can re-load the report using:

$report->load("unique key");

and display, export, or modify it. (You need to re-save if you want your modifications preserved.)

Saved reports can be made available to the Database Query module; simply list the report keys you want to be able to view in Query.conf, like so:

saved_reports = Report #1
saved_reports += Report #2

... etc

Saved reports are good for:

  • quickly viewing reports that are slow and costly to generate
  • capturing snapshots of your data and saving them for later
  • passing large datasets around between different modules

Reports are saved to the report table, with the following columns:

  • section_id - controls access to the report
  • title - the name of the report
  • description - additional information about the report
  • type - a category, typically he name of the module that generated the report
  • data - a data blob that contains the frozen ReportBuilder data
  • source - the URL that the report was generated from
  • parameters - the parameters that were used to generate the report
  • schedule - an interval on which to re-run the report
  • ctime - when the report was generated
  • expiry - when the report expires and can be deleted

Note that parameters and scheduling are not fully supported yet.

Archived Reports

If you save multiple reports under the same title, they will all be treated as different instances of the same report. The most recent one will be used as the "current" report, whereas all previous ones will be treated as archived versions.

This allows you to build time-series reports to track the evolution of your data. Archived reports will be preserved until their expiry date and then removed, so you can set the expiry to be 1 year in the future, and then regenerate the report monthly; that would leave you with a time series showing the last 12 months at any given time.

Filtered Reports

You can preload a volume of raw data into a report, and then generate numerous reports by applying filters and rules to the raw data.

Raw data is one datahash per row, ie. a set of key => value pairs, using the same keys in each row. Preload your data using:

$report->rawhead(%head); # key => header name
$report->rawdata(@data); # each array element is a row/datahash
$report->rawpush(@data); # add more rows

Then generate a report using:

$report->select(%opt);

To select rows, use any of the following comparator options:

  • match => match hash, matching rows will be selected for display
  • notmatch => like match, but matches are excluded
  • like => like match, but ignores case, charset, and whitespace
  • notlike => like like, but matches are excluded
  • contains => match hash, rows containing the substrings will be selected
  • notcontains => like contains, but matches are excluded
  • gt => match hash, rows greater than the values will be selected
  • lt => { match hash, rows less than the values will be selected }
  • empty => [ array of keys, rows in which the key is empty will be selected ]
  • notempty => [ array of keys, rows in which the key is not empty will be selected ]

If you specify no conditions, rows will be automatically selected for display.

To apply logical operators to your conditions, use these options:

  • method => and|or - use this method to join multiple conditions in one call
    • or = select rows where any condition matches
    • and = select rows where all conditions match [default]
  • reselect => and|or - use this method to combine results with the results from a previous pass
    • or = add matches to the previous results
    • and = remove non-matches from the previous results

To select which columns to display in the final report, include a columns option:

columns => [ array of keys to include in the output ]

Then you can call make, export, or save, as usual.

You can include any number of conditions in the options, for example:

# select rows where a<5 and b>10 and c==15
$report->select(lt=>{a=>5},gt=>{b=>10},match=>{c=>15});

By default, the conditions are combined with a logical AND, ie. all conditions must match for a row to be selected.  Set method=>"or" to combine with a logical OR instead, ie. ANY condition may match for a row to be selected.

Use reselect=>and|or to perform multiple passes on the data in a similar way. This lets you create more complicated logical tests, for example:

# select rows where (a<5 || b<10) && (c==3 || d==6)
# first, select rows where a<5 OR b<10
$report->select(lt=>{a=>5,b=>10},method=>"or");
# of the selected rows, select rows where c==3 or d==6
$report->select(match=>{c=>3,d=>6},method=>"or",reselect=>"and");

# select rows where (a<5 && b<10) || (c==3 && d==6)
# first, select rows where a<5 and b<10
$report->select(lt=>{a=>5,b=>10}); # method=>"and" assumed by default
# also include rows where c==3 and d==6
$report->select(match=>{c=>3,d=>6},reselect=>"or");

Filtered reports are the engine behind interactive report builders:

  • generate a list of datahashes for your dataset
  • select a list of columns to display
  • specify a set of conditions
  • generate the report

The user interface for this will depend on the modules generating the reports. Examples can be found in the Membership report builder, and the Forms filtered responses.

 

User Interface