Plugins/Reports

The Bar Code & Reports plugin allows users to create reports from Omeka items. The plugin can create reports in HTML and PDF formats, including bar codes, and is extensible to additional formats.

Using this plugin, you can create PDF QR Codes for your Omeka items, HTML output, as well as other custom formats (see Extending).

To read more about using QRCodes in museums and making them work in your gallery, see the Powerhouse Museum.

Requirements

The Reports plugin requires Omeka version 1.0 or higher.

If you are using Omeka.net, please see instructions for this plugin in Help pages for Omeka.net.

Configuration

  • Path to PHP-CLI: This option must point to a PHP-CLI command that satisfies Omeka's requirements. For more information about the correct value for this option, check with your hosting provider.
    • Default: The plugin will attempt to guess an appropriate path to PHP-CLI
  • Reports save directory: This is the path (on your server, not on the Web) where created reports will be saved. This directory must be writable by the server for reports to be generated.
    • Default: [Omeka directory]/plugins/Reports/generated_reports

Screencast

Watch a quick screencast demonstrating how a bar code might be used inside a museum.

Instructions

A report is a named set of items in Omeka. You can create reports that encompass all items in the system, or choose to report on one specific item, or anything in between. Reports will automatically update as new items are added to Omeka.

Creating a Report

  1. Go to Admin > Reports
  2. Click the link in the top-right that reads "Add a Report."
  3. On the "Add" page, choose a name and a description for the report.
  4. On the "Edit Filter" page, you can choose the criteria under which items will be included in the report. Leaving the form blank will select all items in Omeka.

Generating a File

Once you have created a report, you can create report files. To generate a file, you can either click the "Generate File" button on the main Reports page, or a specific report's details page (accessible by clicking the report's name).

The drop-down box next to the "Generate File" button allows you to select the type of report that will be generated.

The report will be generated in the background; you can refresh the report details page as the report's status changes from "In Progress" to "Completed."

Built-in File Types

The Reports plugin ships with two output formats.

  • HTML
    • Outputs all the metadata for each item as one HTML document
  • PDF (QR Code)
    • Outputs a PDF document containing QR Codes for each item, 10 to a page.

Other report formats can be added (in the Reports/libraries/Reports/ReportGenerator directory) to support additional types of output (see Extending).

Viewing a File

All report files with a status of "Completed" on the report details page have two links, allowing you to view or delete the file.

"View file" allows you to view the generated file in your browser. You can then save the file to your local machine, and/or leave it on your Omeka server.

"Delete file" deletes the generated file from your Omeka server. Before clicking the "Delete file" link, make sure you have saved a copy of the file if you want to keep it.

Extending

You can add new report output formats or edit the existing ones to add or change the functionality of the reports plugin. The existing formats give examples of how to accomplish PDF and HTML output, but you can add other formats (text, XML, etc.) by creating new report generators.

Adding New Formats

Report generators are stored in Reports/libraries/Reports/ReportGenerator, and each generator is a PHP class extending Reports_ReportsGenerator.

All the generation takes place in the function generateReport(). For examples of how to generate reports, study the two included report generators.

Altering Existing Formats

The included formats are an HTML and a PDF output. Both can be modified from their original forms to suit specific needs.

When modifying a included report format, first make a copy of the file, and change both the file name and the class name (so, for example, you could copy HTML.php to HTMLCustom.php, and change the class name to Reports_ReportGenerator_HTMLCustom).

The HTML report format is simple to edit. By default, all the elements in all element sets are printed. You can replace this behavior with printing only specific elements or specific element sets. This is accomplished with the function _outputSetElements(). It takes three arguments. The first is the Item which will be printed, the second is the name of the element set to print, and the third is an array of the specific elements to print.

For example, this is the code that prints all elements for all sets (the default).

// Output all the metadata for all the element sets
foreach($sets as $set) :
    $this->_outputSetElements($item, $set->name);
endforeach;

In comparison, this would cause only Dublin Core elements to be printed:

// Output all Dublin Core elements
$this->_outputSetElements($item, 'Dublin Core');

Finally, this would cause only Dublin Core Item elements to be printed, if any:

// Output all Dublin Core Title elements
$this->_outputSetElements($item, 'Dublin Core', array('Title'));

In this way, you can easily create a customized HTML report format. The PDF output format can also be edited an customized, but requires some more advanced techniques.