Forean reports are defined using the Forena Report XML (frx) template format. Templates are XHTML documents which are extended by some custom HTML tags and attributes. The result should be something familiar to anyone that uses HTML.
These reports are stored as .frx files on the reporting server, and may be edited with any text editor directly, or via the {wysiwyg_editor}.
This guide documents the available FRX elements and attributes, and is best used in combination with the {data_renderers}.
To create a brand new report, just create a new .frx file in your report directory with a minimal set of XMTML content, as further explained below.
Each .frx file should start with the mandatory lines at the very top of any .frx file. These lines specify XML version, DOCTYPE and xml entities. Checkout default.frx in the root of the Forena module directory for a good sample to start from. Note that sometimes you may have more then just those 4 lines, i.e. when using HTML entities such as ® or ©. In such case an extra ENTITY line is added to those lines, to match the entity name with its entity number. Browse the .frx source file of this tutorial for a sample containing such extra ENTITY lines.
These mandatory 4 lines should be followed by a html tag, and a corresponding /html, which should include the lines starting from the head tag and ending with the /body tag, as in this example:
Note: most of the tags shown above are optional, though it appears to be a good practice to have them available already in the .frx file whenever a reports requires some of them.
Here is an example of a report definition for a very simple report:
{code} - {name}
The above .frx example illustrates a few of the most commonly used FRX elements and attributes (custom HTML tags), i.e.:
| xmlns:frx element | Defines the document as a Forena Report XML template document. It should appear at the top of every .frx file, and exactly as shown here. |
|---|---|
| frx:category attribute | Set the category that you want the report to appear when listing reports. |
| frx:options attribute | Sets some specific options that apply to the entire report, e.g. to display the report using a specific skin. Refer to {reportingfrx_general} for additional information about this FRX attribute. |
| frx:block attribute | Loads data from the defined data block (in this case sample/sampleXML). Data blocks are usually parameterized queries. If you are a developer, you might want to read more about defining data blocks in the Forena Data source. |
| frx:foreach attribute | Causes the containing tag to be repeated for every row returned in the data block. The attribute value can be any valid XPATH expression, but is often simply '*', which creates a repeating pattern for every row or element returned by the query. |
| frx:parameters | when used in conjunction with the frx:block attribute overrides the parameters provided to the block that is run. When used these values are merged with the values of the current {reportingfrx_datacontexts} prior to calling the data block. Refer to {reportingfrx_parameters} for additional information about this FRX attribute. |
| frx:renderer | uses a custom class to render this object. How the tag is rendered is defined by implementation of the renderer. Typical syntax looks something like frx:renderer="FrxSVGGraph" or frx:renderer="FrxXML". Other attributes are interpreted directly from the {renderers_intro}. Refer to the {renderers_intro} for additional information about this FRX attribute. |
Advanced FRX attributes:
| frx:skip_root attribute | Causes the current node of the report to not be rendered, but children will be rendered as normal. This is most commonly used when you want the frx:foreach to not render the node containing the frx:foreach attribute. |
|---|---|
| frx:skip_id attribute | To ignore the id of this element, use frx:skip_id="true". For more details check out the issue about {skip_id_issue}. Thanks {jamesdixon} for your contribution via that issue. |
| frx:invalid_link attribute | Validates links prior to presenting them, and supports the following values:
|
The general options of a report are used to set these specifications of a report:
Here is an example illustrating various general report options, which are further explained below.
The title element specifies the report's page title and tab title.
The frx:category element specifies under which group the report appears under the {my_reports} list. A report without a category will not show up in the list.
The frx:options element specifies various options of the report, as shown in the above example. The following properties may be defined:
| hidden | Indicate if the report is to be included or excluded in the My Reports list, using either of the following values:
|
|---|
Note that the frx:options element is also used to specify some of the {report_layout} options of a report, i.e.:
| skin | Specify an alternate skin for the report, whereas skin_file_name is the filename of the skin, without the .skinfo file extension of it. |
|---|---|
| form | This attribute has been deprecated and has been superseded by the skin= attribute. |
The frx:menu element specifies the properties of a Drupal menu link to be created pointing to the report, as shown in the above example. The following properties may be defined:
| enabled | Indicate if the menu item is to be enabled or disabled, using either of the following values:
|
|---|---|
| path | The site relative path for the menu item. |
| args | Additional parameters that should be extracted after the menu path using a :parm syntax, e.g. :parma/:parmb. |
| type | Use standard conventions for creating a menu item in the format of normal menu items, tabbed menus, etc. |
| title | The title of the menu item to be created. |
| weight | The weight of the menu item to be created. |
| plid | The plid of the menu item to be created. |
| menu_name | The name of the menu in which the menu item is to be created. |
Note: changes to menu properties only become in effect after {clear_drupal_cache} .
The frx:cache element specifies the caching properties of each report, as shown in the above example. The following properties may be defined:
| duration | The duration that a cached report remains in the cache. Use relative formats according to the php documentation. |
|---|---|
| per_user | 1 indicates that caches will be maintained for each drupal UID. |
| per_doctype | 1 indicates that caches will be maintained for each document type. CSV files will be rendered differently than other files. |
The normal output of any report is an HTML document. It which can optionally be exported in several common document formats. The document types options are used to set the available formats in which a report can be saved.
Here is an example illustrating some of the document types options
...The frx:docgen element specifies the document types options of the report, as shown in the above example. Add a frx:doc element for each format to be allowed for the report as follows:
| web | Web page (= the entire content of the webpage containing the report). |
|---|---|
| csv | Comma Separated Values. |
| eMail message. | |
| html | HyperText Markup Language (= the body part of the webpage containing the report). |
| Adobe PDF document requires mPDF or Prince libraries | |
| svg | Scalable Vector Graphics. |
| doc | MS Word format. |
| xls | MS Excel format. |
| xml | eXtensible Markup Language. |
The report layout options are used to set these specifications of a report:
Here is an example illustrating various general layout options, which are further explained below.
...| code | name |
|---|---|
| {code} | {name} |
The frx:options element specifies various options of the report, as shown in the above example. The following properties may be defined:
| skin | Specify an alternate skin for the report, whereas skin_file_name is the filename of the skin, without the .skinfo file extension of it. |
|---|
Note that the frx:options element is also used to specify some of the {general_report_options} of a report, i.e.:
| hidden | Indicate if the report is to be included or excluded in the My Reports list, using either of the following values:
|
|---|
Use the style element within the head element to specify small CSS snippets that can be used anywhere in the report. Using a style content as in the above example will change the look-and-feel of the table content a little bit. In this specific case the height of the table rows will be higher then the height for standard table displays, while the color of the text in the table cells is shown in a kind of orange.
The body element specifies the content of the HTML body. Using a body content as in the above example will
create a report for which the actual body will start with a line like "This is the very first line of the report body ...", it
will end with a line like "... And this is the very last line of the report body.".
The div tag in
between those 2 lines is to include the actual data from the sampledb/states data block. In this case the data block is shown
using a traditional table.
URL query parameters can be passed directly into the SQL queries that drive the report. However, there are many circumstances where you may want to prompt users for specific data prior to generating a report. In such cases you can use a set of frx:parm elements contained in a frx:parameters element in the head section of the .frx file to define parameters, as in this example:
The id of each frx:parm element should match the parameters in the data block, and will further control how the user is prompted for each data element. The text contained in the frx:parm element defines the "default" value for the parameter. The following attributes are supported in the frx:parm element:
| id | The id of the parameter, which must match what is expected in the data block. This field is required. |
|---|---|
| label | The parameter's label or prompt shown to the user. |
| desc | The description provided for each label. |
| require | Set to 1 to require this before form submission. |
| type | Type of control to use for prompting the user. Supports the following values:
|
| data_source | The data block used to provide values for radio buttons, check-boxes or select lists. The value should be a data block that users of this report will have access to. Note: this is indeed assumed to be a data block, and not a data source. |
| data_field | The name of the column from the data block in data source that is used for the select value. If omitted, then the 1st column of the data block is used as the data_field. |
| label_field | The name of the column from the data block in data source that is used for the select label (description). If omitted, then the 2nd column of the data block is used as the label_field, provided such 2nd column exists (if not, then the 1st column is used instead). |
In the head section of the .frx file, you will find a series of frx:field elements contained in a frx:fields element. These elements define special formatting rules for report fields referenced in the .frx file, as in this example:
Each report field allows for configuring various properties of it, i.e.:
Each report field for which a frx:field element is specified, is identified by the required id attribute. The options available to configure these properties are further detailed below.
The frx:field element supports field formatting. Fields can be formatted a number of different ways by specifying the format and format-string attribute for a field. The following table illustrates the supported options:
| Format | Description | Format String |
|---|---|---|
| drupal_date_format | Formats a Drupal date. Drupal dates are natively large numbers that are expressed as the number of seconds since the UNIX epoch date. | Use small, medium or large to specify any of the site defined dates, or alternatively specify a custom date format. See http://php.net/manual/en/function.date.php for possibilities for custom formatting. |
| drupal_node_content | Loads content from the given nid and display it using teaser or full display. | Specify teaser to get teaser view. |
| drupal_translation | Use Drupal's translation API to translate the value prior to display. | Specify a field that contains the serialized data used for translations (e.g. watchdog table). Normally you can leave this blank. |
| iso_date | ISO standard dates are of the form, YYYY-MM-DD followed by a 24 hour timestamp (e.g. 2012-12-01 20:30:30). Dates in this format may be reformatted. | Use small, medium or large to specify any of the site defined date formats, or alternatively specify a custom date format. See http://php.net/manual/en/function.date.php for possibilities for custom formatting. |
| number | Use the PHP number formatter function. | Indicate a sample numeric format for decimal places and thousands separator. (eg. 9.999.00). |
| sprintf | Use PHP's sprintf function for adding labels and such. | See http://us.php.net/manual/en/function.sprintf.php for possibilities. |
The frx:field element supports following attributes related to field linking:
| link | Specify the URL that the field is to be linked to as in this example. You can refer to any tokens in the current content using the normal curly brace syntax:
...
|
|---|---|
| rel | Relationship attribute to apply to the link. |
| class | Class to be applied to the link. |
| target | The value of the target attribute in the link to be created, such as _blank to open the link in a new browser window or tab. Target values that begin with popup will be opened in a new window using JavaScript. |
The frx:field element supports following attributes related to the default value of the field:
| default value | The value to be displayed in the report output when no value exists. |
|---|
Any data from any other section of a report may be used by referencing those data by their id. For example: if you place an id attribute on the tag that you place an frx:foreach attribute on (e.g id='state' frx:foreach='*'), then you can reference any data element in that data context using that id as follows:
Modules may provide their own custom data contexts either by adding them in a hook_forena_parameters_alter implementation or by implementing a custom context class of their own.
{report_time} can be referenced anywhere in the report to display the render time of the report. This is useful for cached reports because you may want to include an "as of {report.time}" in your report so that users know that they are working in stale data. Here are a few more variations of this:
A custom FrxReport context is provided to allow you to embed reports easily. For example, consider the Simple Table of States report, which is located the report repository in a subdirectory named sample, in report template states.frx. This report may be embedded in another report simply by including the string FrxReport.sample.states, enclosed by curly braces, anywhere in a report, as in this example:
It is important to understand that the data from the current context will be used as parameters to the report when this context is used.
By adding the frx:if="some_test" attribute to any HTML tag, that HTML tag is only rendered if some_test evaluates to true. The normal php rules apply to values specified here: frx:if="0" evaluates to false, while frx:if="1" evaluates to true.
Normally you would use token replacements in the attribute to map this to some column in the database or value of a tag in case of data stores in XML format. As an illustration, consider this example:
This would cause the tag sometag and its children only to be rendered if the my_column field in the database returned true.
Here is a variation of the previous example:
In the above example the tag sometag and its children would only be rendered if the type field in the SQL query were article.
You may use an exclamation point to indicate negation as in this example:
This frx:if attribute would only evaluate to true if my_column was not present or zero.
Because of the way PHP string expressions work, listing multiple conditions in an frx:if attribute is interpreted as an OR. As an illustration, consider this example:
This frx:if attribute would evaluate to true if either column my_column OR your_column contains data. If instead you need to use an AND operator, separate the conditions by & as in this example:
This frx:if attribute would evaluate to true only if both columns my_column AND your_column evaluated to true.
Each field in the report is referenced by an XPATH expression enclosed by curly braces, as in this example:
In its simplest form the XPATH expression can be thought of as the name of the field in the database, but when using more complex data sources, there is a lot that can be done using these XPATH expressions.