FRX Reporting Reference
Including
- Introduction: Content at a glance.
- Frx files anatomy: Understanding the main structure of an FRX file.
- General Report Options: Specify general options of a report.
- Document Types: Enabled document formats for optionally saving a report.
- Report Layout Options: Specify various layout options for a report.
- Report Parameters: Specify various parameter options for a report.
- Configure Report Fields: Define special formatting rules for any report field.
- Data Contexts: Access data from other report sections or even from other reports.
- Conditional Rendering: Optionally include or exclude some specific report section(s).
- Token Replacement: Using tokens to replace report fields by corresponding (data block or configuration) values.
Forena Reports XML
Forena 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 reporting user interface .
This guide documents the available FRX elements and attributes, and is best used in combination with the Data Renderers Guide .
Anatomy of an FRX File
Creating a new frx file
To create a brand new report, just create a new .frx file in your report directory with a minimal set of XHTML 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:
<html id="frxsrc-16"> <head> <title> </title> <frx:category> </frx:category> <frx:options> </frx:options> <frx:parameters> </frx:parameters> <frx:docgen> </frx:docgen> <frx:fields> </frx:fields> <frx:menu/> <frx:cache/> <frx:data/> <style/> </head> <body> </body> </html>
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.
Example of an frx file
Here is an example of a report definition for a very simple report:
<html id="frxsrc-2">
<head>
<title>A sample report</title>
<frx:category>Sample</frx:category>
<frx:options hidden="0" skin="skin_file_name"/>
</head>
<body>
<div frx:block="sampledb/states">
<p frx:foreach="*">{code} - {name}</p>
</div>
</body>
</html>
Commonly used FRX elements and attributes
The above .frx example illustrates some 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 General Report Options 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 data context prior to calling the data block. Refer to Report 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 Data Renderers Guide . Refer to the Data Renderers Guide for additional information about this FRX attribute. |
Advanced FRX attributes
Some more 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 Ability to have no id in frx:foreach elements . Thanks jamesdixon for your contribution via that issue. |
| frx:invalid_link attribute | Validates links prior to presenting them, and supports the following values:
|
General Report Options
The general options of a report are used to set these specifications of a report:
- Report title.
- Visibility options.
- Menu options.
- Report caching options.
Here is an example illustrating various general report options, which are further explained below.
<html id="frxsrc-11"> <head> <title>A sample report</title> ... <frx:category>Example</frx:category> ... <frx:options hidden="0" skin="skin_file_name"/> ... <frx:menu enabled="1" path="reports/my1strpt" args=":myparm1/:myparm2" type="normal-item" title="My 1st Report" weight="5" plid="270" menu_name="navigation"/> ... <frx:cache duration="+1 hour" per_user="1" per_doctype="1"/> ... </head> <body> ... </body> </html>
Report title
The title element specifies the report's page title and tab title.
Visibility options
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. |
Menu options
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 clearing the Drupal cache.
Report caching options
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. |
Document Types
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
<html id="frxsrc-7">
<head>
...
<frx:docgen>
<frx:doc type="web"/>
<frx:doc type="csv"/>
<frx:doc type="email"/>
<frx:doc type="html"/>
<frx:doc type="svg"/>
<frx:doc type="doc"/>
<frx:doc type="xls"/>
<frx:doc type="xml"/>
</frx:docgen>
...
</head>
<body>
...
</body>
</html>
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 either use of third party libraries (mPDF or PrinceXML) or a subscription to DocRaptor document generation services. | |
| svg | Scalable Vector Graphics. |
| doc | MS Word format. |
| xls | MS Excel format. |
| xml | eXtensible Markup Language. |
Layout
The report layout options are used to set these specifications of a report:
- Look and feel options.
- Report specific CSS styles.
- The layout of the report body.
Here is an example illustrating various general layout options, which are further explained below.
<html id="frxsrc-3">
<head>
...
<frx:options hidden="0" skin="skin_file_name"/>
...
<frx:fields/>
<style>
div.FrxTable {
line-height: 2.5;
color: #FF6633;
}
</style>
<frx:menu/>
<frx:cache/>
</head>
<body>
This is the very first line of the report body.
...
<div frx:block="sampledb/states" id="state-block" class="FrxTable">
<table>
<thead>
<tr>
<th>code</th>
<th>name</th>
</tr>
</thead>
<tbody>
<tr frx:foreach="*" id="state">
<td>{code}</td>
<td>{name}</td>
</tr>
</tbody>
</table>
</div>
...
And this is the very last line of the report body.
</body>
</html>
Look and feel options
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:
|
|---|
Report specific CSS styles.
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 layout of the report body.
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.
Parameters
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:
<head id="frxsrc-6">
<title>My Report Title</title>
<frx:parameters>
<frx:parm id="state" label="State" require="1" desc="Select a state from the list." data_source="sampledb/states" data_field="" type="select">WA
</frx:parm>
</frx:parameters>
</head>
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). |
Fields
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:
<html id="frxsrc-12">
<head>
<title>A sample report</title>
...
<frx:fields>
<frx:field id="state" link="" format="" format-string="" target=""/>
<frx:field id="name" link="" format="" format-string="" target=""/>
<frx:field id="total" link="reports/sample.user_distribution_simple?state={state}#test" format="" format-string="" target="">OH
</frx:field>
</frx:fields>
</head>
<body>
...
</body>
</html>
Each report field allows for configuring various properties of it, i.e.:
- The formatting of the field's output.
- The field's links to be created.
- The field's default value to be displayed if no value is present.
Each report field for which a frx:field element is specified, is identified by the required id attribute. The following reference describes the attributes availalabe in the
| Attribute | Description |
|---|---|
| add-query | Forces add of all report parameters to the generated link. |
| calc | Xpath expression used to calculate this field. |
| class | The class to use on the link generated by the link attribute |
| context | Context used by the calc attribute |
| format | Indicates the formatter to be used with this field |
| format-string | Provides further instructions to the formatter specified in format |
| id | Indicates the token/field replacement for which this field definition applies. |
| link | Makes an link out of the field using the path specified. |
| rel | Indicates the rel attribute used when creating the link. |
| target | When used with link specifies the link target. |
These attributes are described in greater detail below.
Field output formatting
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. |
| xhtml | Field contains XHTML Data. Use this to decode any htmlencoded data in the element and treat it as valid XHTML. If you see html as source in your report consider using this format. | Specify an input filter to run the data through after the XHTML decoding to use any of drupals input filter "markup extending" capabilities. |
| 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. |
| template | The field being referenced is a foreana template. The data is assumed to be valid xhtml with normal forena fields that will be replaced based on the current data context. | Indicates the machine name of an input format that is used to process the data after bing run through forena's templating system. |
Field linking
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:
<html id="frxsrc-8">
<head>
...
<frx:fields>
<frx:field id="profile" link="profile/{some_field_name}" format="" format-string="" target=""/>
</frx:fields>
</head>
<body>
...
</body>
</html>
This will create a link to this some_field_name 's profile.
|
|---|---|
| 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. |
Field default value
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. |
|---|
Field calculations
The frx:field element supports redefining fields as complex calculations using xpath expressions. These expressions are evaluated for the current selected data using PHP's DOMXMPATH evaluate method. Specify the the calculation you want to perform in the calc attribute of the field element. You can also use the forena field tokens in these calculations to further enhance the kinds of calculations you can perform.
Additional information on xpath expression syntax may be found in the XPath Operators seciton of the w3schools XPath Tutorial.
Data Contexts
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:
<div>... {state.name} ...</div>
Additional data contexts may be added to the document in the head section of the document. Data in the head section of the document is preloaded before the report renders. The example below illustrates the syntax for preloading data in the head section:
<head> .. <frx:data id="state" block="sampledb/state"/> </head>
Additional data that is only needed for the rendering of the report may be included by leaving of the block attribute and specifying XML data as child elements of an frx:data element as in the following example.
<head>
..
<frx:data id="scale">
<scale min="0" max="50" red="255" green="0" blue="0" red_scale="0" green_scale="255" blue_scale="0"/>
<scale min="50" max="100" red="255" green="255" blue="0" red_scale="-255" green_scale="-100" blue_scale="0"/>
<scale min="100" max="101" red="0" green="100" blue="100" red_scale="0" green_scale="0" blue_scale="0"/>
</frx:data>
</head>
In addition, data in the head section can be loaded into drupals settings objects for use later in javascript. as in the following:
<head> ... <frx:data block="sampledb/users_by_state" json="stateSummary"/> </head>
The data in the above example would be accessible to the javascript by referencing the object property Drupal.settings.forenaData.stateSummary.
The Site Context (site)
This predefined context provides useful information about the context of your drupal site. The following values are always available:
| Property | Sample | Description |
|---|---|---|
| site.args | See XML Below | The path as returned by drupals args function |
| site.dir | Root Relative reference to your site. Useful when referencing assets. | |
| site.base_path (deprecated) | / | Same as above but the raw result for drupal_base_path() call. |
| site.base_url | http://placeto.be | Full url reference to the base url of your site |
| site.destination | reports/help.reportingfrx | Return of drupal_get_destination |
| site.language | See XML Below | Full language object which can be converted to XML an caclulations based on it |
| site.page | /reports/help.reportingfrx | Root relative reference to the current drupal page |
| site.theme_dir | sites/all/themes/mix_and_match | Directory of current theme. |
| site.theme_path | /sites/all/themes/mix_and_match | Root relative reference to the current theme. |
| site.uid | 0 | The id of the current user |
| site.user_name | The name of the current user. |
You can use the following XML as a reference for deriving calculations from this object.
<root> <base_path key="base_path">/</base_path> <dir key="dir"></dir> <theme_path key="theme_path">/sites/all/themes/mix_and_match</theme_path> <theme_dir key="theme_dir">sites/all/themes/mix_and_match</theme_dir> <base_url key="base_url">http://placeto.be</base_url> <user_name key="user_name"></user_name> <uid key="uid">0</uid> <language type="object"><language key="language">en</language><name key="name">English</name><native key="native">English</native><direction key="direction">0</direction><enabled key="enabled">1</enabled><plurals key="plurals">0</plurals><formula key="formula"></formula><domain key="domain"></domain><prefix key="prefix"></prefix><weight key="weight">0</weight><javascript key="javascript"></javascript></language> <args type="array"><element key="0">reports</element><element key="1">help.reportingfrx</element></args> <page key="page">/reports/help.reportingfrx</page> <destination key="destination">reports/help.reportingfrx</destination> </root>
The Report Context (report)
The Report data context is always available to help provide information regarding the current report.
| Property | Sample | Description |
|---|---|---|
| report.name | help/reportingfrx | Machine name of the current report. |
| report.dir | /sites/all/modules/forena/repos/reports/help | Directory of the current report. |
| report.link | reports/help.reportingfrx | The site relative path where you will find this report. |
| report.language | en | The language code of the current report. |
| report.format | web | The document format that the report is being viewed. |
| report.time | 2020-01-17 15:37:44 | The time that this report was rendered. |
The Skin Context (skin)
The Skin data context is always available to help provide information regarding the current skin for the report. In addition to the tokens below, arbitrary varialbes may be defined in the skin and used in the report for skin specific variables.
| Property | Sample | Description |
|---|---|---|
| skin.name | Documentation Tutorial Skin | The display name of the current skin. |
| skin.dir | /sites/all/modules/forena/repos/reports | Directory of the current skin. Useful for including skin assets. |
The FrxReport Context (FrxReport)
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:
<div>... {FrxReport.sample.states} ...</div>
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.
The FrxReport Context (FrxReport)
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:
<div>... {FrxReport.sample.states} ...</div>
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.
Custom Contexts
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.
Conditional Element Rendering
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.
Using token replacements in frx:if attributes
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:
<div id="frxsrc-1">
...
<sometag frx:if="{my_column}">something surrounded by sometag</sometag>
...
</div>
This would cause the tag sometag and its children only to be rendered if the my_column field in the database returned true.
Using conditions in frx:if attributes
Here is a variation of the previous example:
<div id="frxsrc-13">
...
<sometag frx:if="{type[text()='article']}">something related to article and surrounded by sometag</sometag>
...
</div>
In the above example the tag sometag and its children would only be rendered if the type field in the SQL query were article.
Using negations in frx:if attributes
You may use an exclamation point to indicate negation as in this example:
<div id="frxsrc-14">
...
<sometag frx:if="!{my_column}">something surrounded by sometag</sometag>
...
</div>
This frx:if attribute would only evaluate to true if my_column was not present or zero.
Combining multiple conditions in frx:if attributes
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:
<div id="frxsrc-4">
...
<sometag frx:if="{my_column}{your_column}">something surrounded by sometag</sometag>
...
</div>
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:
<div id="frxsrc-5">
...
<sometag frx:if="{my_column}&{your_column}">something surrounded by sometag</sometag>
...
</div>
This frx:if attribute would evaluate to true only if both columns my_column AND your_column evaluated to true.
Token Replacement
Each field in the report is referenced by an XPATH expression enclosed by curly braces, as in this example:
<div>... {SomeXpathExpression} ...</div>
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.