Setup Guide

Including

Introduction

Forena is a report writer that is designed to help developers who are knowledgeable in writing SQL.

Report definitions are stored as files on the file system in .frx files. These files are basically XHTML template files extended with frx namespaced attributes and elements. Report authors need only to learn a few special attributes and tags (e.g. frx:block, frx:foreach, frx:if) to create reports in virtually any layout. FRX report files are typically stored in a location writable by the web user, so that they can be authored using a WYSIWYG report editor. Report definitions can typically be modified by a group of power users. These users do not need to know SQL, but should be comfortable in html/css.

Data are typically accessed through "data blocks" which are basically references to parameterized SQL files. The .sql data blocks are stored on the file system, typically in a location that is not writable by the web user.

Installation and Configuration

After following normal practices for installing a drupal module there are a few steps that must be preformed prior to using forena:

  1. Configure private file system support
  2. Prepare a text format for use with forena (optional)
  3. Configure forena to use this text format and specify installation and configuration directories.
  4. Enable document types
  5. Configure Forena permissions

Configure private file system

Configure a private file system location. I usually use the value sites/default/files/private. This is done so that when using the Forena Query module, newly created .sql data block files cannot be viewed by prying eyes.

Prepare a text format to be used by forena

In a subsequent administration step, a text format will have to be specified as the input format for any of the report specifications. To select such text format, basically 2 options exist:

  • Use a newly created text format (preferred): The advantage of using a new text format is that the impact of tuning the selected text format will be limited to forena reports only. If you're planning on using any of the WYSIWYG editors to edit the body of a report, it might be a good practice to even create two new text formats (an extra one for reports that will contain graphs)
  • Use an existing text format such as Full HTML: this is the easiest option, but will likely require you to change the configuration of the existing format.

If you want to use the input format filtering system, it is strongly recommended create a dedicated text format for use with Forena (e.g. one named "Reports"). Text format configuration may be found at Text formats.

Regardless as to which Input Format you choose to use with forena, make sure these entries are turned of for the chosen text format :

  • Limit allowed HTML tags.
  • Display any HTML as plain text.
  • Convert line breaks into HTML.
  • Correct faulty and chopped off HTML.

Note: Especially if you're planning to use SVG graphs it is important to avoid that tags are being stripped out, as this could cause such graphs to not be shown at all or with errors.

General Forena Configuration

Navigate to the general tab of the Configuring Forena Reports and configure the following options:

  • Report Repository: this is the directory to be used for saving the report specifications (.frx files). In order to be able to save reports, this directory should be writable by the web user. Relative paths should be entered relative to the base path of your Drupal installation.
  • Custom Data Block Repository: this is the directory to be used to save custom Data Blocks (e.g. using the forena query builder tool). This should be a directory that is writable by the web user, but it should not be possible to browse it via the web.
  • Default Report Skin only makes sense after defining 1 or more custom Skins. Leave the proposed default value for it unchanged for now.
  • Text Format If you want to use Drupal's custom markup in reports, specify the text format you configured for use with forena earlier.

Use the Save Configuration button to save changes.

Recommended video tutorials

For more info about this topic, checkout Basic Reporting on External Data - Quick introduction to reporting using the Northwind sample database (00:30 to 02:10).

Enable Allowed Document Types

Navigate to the Document Types tab of the Configuring Forena Reports. Indicate which document formats should be enabled to select from when creating the specifications of any report (for the report developer to pick from), and which ones should be enabled by default.

Notes:

  • Users are presented with links to export the report in formats that were enabled for that report. The default types specified here are presented when no overriding values are set for the report.
  • Users will not be able to export the report in any formats that are not enabled, regardless of the doctypes specified in the report.
  • Don't confuse document formats with text formats described earlier. They are not related to each other.

Permissions

Forena allows for a lot of granularity as it comes to reporting related authorizations, by using the standard Drupal administration facilities to grant permissions to roles. The list of Forena related Drupal permissions that can be granted may be a bit overwhelming at first. Because there are 3 entries for each defined data source, and vanilla Forena already comes with 3 data sources. Available Drupal permissions related to using and/or managing Forena Reports are as follows ([data source] represents the name of a data block's repository).:

Right Grants access to
Administer Forena Reports
  • admin/config/content/forena.
  • admin/config/content/forena/data/configure.
  • admin/config/content/forena/data/add.
  • admin/config/content/forena/data.
  • admin/config/content/forena/formats.
List reports
Create a report
  • menu item Create Report.
  • Create a new (custom) report from a template (via reports/%/add).
  • Create a new (custom) report translation (via reports/%/translate).
Design reports
  • Editing the specifications of an existing (custom) report (via reports/%/edit, or any of its sub-paths to edit general report options, document types, report layout, report parameters, add/remove data blocks, report fields, etc).
  • Translating an existing (custom) report (via reports/%/translations), an option that is available if Drupal core module local is enabled.
  • admin/structure/forena.
  • admin/structure/forena/reports.
  • admin/structure/forena/data.
  • forena/data.
Delete reports Deleting an custom report via reports/%/delete.
Perform email merge Use of the email document type to send email form letters using Forena.
Access xml from data blocks directly Forena/xml/%, useful for AJAX calls to data blocks.
Access [data source] Data Data contained in the [data source] repository (one such permission for each defined [data source]), which is a prereq for access to any data contained in any data block of data source.

Forena Query Builder Module Permissions

These are the available Drupal permissions related to managing data blocks using the Forena Query Builder (whereas "[data source]" represents the name of a data block's data source or database connection):

Right Grants access to
Build Forena Data Blocks using SQL Direct access to SQL should not be given without understanding of security ramifications.
Manage data security Allows to create new data queries and alter security on saved queries.
Create [data source] Data Blocks Grant access to create data blocks contained in the [data source] repository (one such permission for each defined [data source]).
Delete [data source] Data Blocks Grant access to delete data blocks contained in the [data source] repository (one such permission for each defined [data source]).

Enable SVGGraph

Forena also facilitates the creation of graphs such as piecharts, barcharts and radarcharts using the PHP SVG Graph library (version 2.11 or above), which is expected to be installed in the sites/all/libraries folder. To install this library:

  1. Download the PHP SVGGraph library.
  2. Unpack (extract) the downloaded SVGGraph library.
  3. Transfer (upload) the extracted library in a subfolder of sites/all/libraries, using SVGGraph (case sensitive!) as the name of the subfolder.

After completing the SVGGraph installation, go to the Drupal Status Report and check the line starting with Forena SVGGraph support: if it is shown with a status of Enabled, then the SVG Graph library is installed correctly.

For a video tutorial about this topic, checkout Graphing with PHP SVG Graph and Forena - Part 1 (i.e. what is explained from about 00:10 to 03:10).

Validate your text formats configuration

Assuming you completed the setup of your SVG graph library, you should now be in good shape to start using Forena's charting features. To perform an easy validation about this, just checkout one of the SVG samples delivered with Forena. Use the external SVG graph sample in case you're using an older browser that does not support inline SVG. Alternatively, if you're using a more recent browser, try using the Master Summary with drill down.

If you don't see a nicely formatted graph, but only some square with a gray background (about the size of the SVG graph you should see if it would have worked), or you're getting some error messages, you may want to checkout the issue queue on Drupal.org (search for html filter), such as in the Graph generation issue.

Additional info

Checkout the Configuration Settings section within the Skins Guide for instructions about how to assign appropriate default values for various SVG Graph settings.

Refer to the PHP SVGGraph documentation for more info about the SVG Graph library (e.g. for all sorts of options/features available in SVG Graph).

Enable Data Tables

Forena also facilitates the use of the dataTables JQuery plugin to enhance the display of tables in your reports, such as presenting paged tables or filtering of rows. If you're not familiar with the dataTables plugin, refer to the dataTables examples to understand its features.

To install this library:

  1. Download the dataTables library from http://www.datatables.net/.
  2. Extract the downloaded dataTables library from the zip archive.
  3. Copy the extracted library into your sites/all/libraries folder, making sure to name it dataTables (case sensitive!).

After completing the dataTables installation, go to the Drupal Status Report , and check the line starting with Forena dataTables support: if it is shown with a status of Enabled, then the dataTables library is installed correctly.

Refer to the dataTables documentation for more information about the dataTables library.

For a video tutorial about this topic, checkout Create skins that integrate JQuery plugins (i.e. what is explained from about 08:15 to 10:20).

Upgrading From Prior Versions

Forena version 7.x-4.x is a major release upgrade, with lots of new features. In preparation of your reports migration, make sure to checkout the release notes found on the Forena project page for details about this new release.

Review permissions

This release come with quite some enhancements (and changes) to user permissions and access to data blocks. So make sure to review and tune the various Forena related permissions. The following steps should be preformed after upgrading from any 7.x-3.x version.

Revert module delivered reports

After installing this release, make sure to Revert all delivered reports to original which will cause all customizations to reports that are delivered with contributed or custom modules to be lost. Failure to do this will leave outdated versions of help files and sample reports on your site. The two provided ways to revert customized reports are:

  • Visit the Structure Forena screen and check the box to "Revert Delivered Reports to original" (near the bottom) and press the Revert button.
  • Use DRUSH, by executing the drush frxrevert command.

Replace legacy options in custom reports

The new skin tag replaces the previous form tag within the frx:options element. Even though the form tag is still supported it has been depreciated, you are encouraged to replace it in all custom reports. Checkout the Report Layout options for more details about these tags.

Apply corrections for charts created with SVG Graph

Apply these modifications to any custom reports containing graphs that are created with the SVG Graph template renderer:

  • Change from legend_entry to legend_entries.
  • Change from colors_XX to colour_XX. Not applying this change will not actually cause any errors during the rendering of a graph, but colors_XX options will simply be ignored. This will result in using the default SVG Graphs colour_XX options.

Upgrade SVGGraph library to at least version 2.11

The PHP SVGGraph library version 2.10 will cause 'Zero length axis' problems because the SVGGraph renderer now uses the structured data syntax that is supported only as of SVG Graph 2.11. So ensure the PHP SVG Graph library is at version 2.11 or above. Even version 2.16 is confirmed to work fine.

To verify the version, just browse sites/all/libraries/SVGGraph/SVGGraph.php and check the line near the top of it that contains SVGGRAPH_VERSION, followed by the actual version id which should be something like 2.11, ..., 2.16.