Commit 6a2f159f authored by metzlerd's avatar metzlerd
Browse files

#2124777 Rework table of contents.

parent 6f3b6f16
<?xml version="1.0" encoding="UTF-8"?>
<book>
<booktitle>Skins and Theming)</booktitle>
<bookfolder>help.skins</bookfolder>
<chapters>
<chapter>
<title>Defining Skins</title>
<subtitle>How to create a .skinfo file</subtitle>
<abstract>Overview of skins and how they are formatted.</abstract>
<link>define</link>
</chapter>
<chapter>
<title>Assigning Skins</title>
<subtitle>Set default skins and assigne custom skins to reports </subtitle>
<abstract></abstract>
<link>assign</link>
</chapter>
<chapter>
<title>CSS Libraries</title>
<subtitle>Add css libraries to a skin</subtitle>
<abstract></abstract>
<link>css</link>
</chapter>
<chapter>
<title>Javascript Libraries</title>
<subtitle>Add a javascript libraries for use in reports</subtitle>
<abstract></abstract>
<link>javascript</link>
</chapter>
<chapter>
<title>Configuration Options</title>
<subtitle>Defining skin configuration options</subtitle>
<abstract></abstract>
<link>options</link>
</chapter>
</chapters>
</book>
\ No newline at end of file
......@@ -7,59 +7,14 @@
<title>Creating A Simple Report</title>
<frx:category>Help</frx:category>
<frx:options hidden="1" />
<frx:parameters>
</frx:parameters>
<frx:docgen />
<frx:fields>
<frx:field id="title" link="reports/{name}" />
<frx:field id="admin_reports" link="admin/structure/forena">admin/structure/forena</frx:field>
<frx:field id="title" link="reports/help.reportingfrx">FRX Reporting Guide</frx:field>
</frx:fields>
<frx:parameters />
<frx:docgen />
</head>
<body>
<div id="design_topics_block" frx:block="forena_help/design_topics">
<h2>Create Report</h2>
<p>To create a report, visit the {admin_reports}
page and select the . Site administrators can relocate this menu so
contact your site administrator if you have trouble finding it.</p>
<p>
The <b>Report Name</b> is a unique name that is used as the base
file name for your report. In this example will use a title
test/simple. This will mean that the filename of the report will
be test/simple.frx.
</p>
<p>
The <b>Title</b>field indicates the title of the report as it will
appear for the user. In this example we'll call our report "Test
Simple Report".
</p>
<p>For a simple report, you can leave the remaining fields
blank, and hit save. The report body will be generated when we add
data to our report.</p>
<h2>Data</h2>
<p>
After saving your report, you will be taken directly to the data
tab. In the <strong>Data Block</strong> field, specify a data
source to be used on the report. You may search for the name of
any provided data blocks. These data blocks are created or
installed by your site administrator or developer. For this
report, we'll reference one of the sample queries provided with
forena. Enter sampledb/users_by_state and press <strong>Preview</strong>.
Forena will show you a sample table layout of the data returned by
that data block. You may need to specify required parameters in a
report in order to gernate sample data before forena will be able
to store your report preview. You will be able to cusotmize the
columns and layout later. Press <strong>Add </strong>to add this
data to the report.
</p>
<p>The preview shows the format of the data that will be added
to the report. If parameters were required in order for the data
block to return any data, you'll be prompted to enter the
parameters. You cannot use the editor to add data to the report
unless you can provide parameters that cause the query to actually
return data.</p>
<p />
<ul>
<li id="forena-2" frx:foreach="*">{title}</li>
</ul>
</div>
<p>This document is no longer in use please see the {title}</p>
</body>
</html>
</html>
\ No newline at end of file
......@@ -6,32 +6,15 @@
<head>
<title>Report Writers Guide</title>
<frx:category>Help</frx:category>
<frx:options />
<frx:options hidden="1" />
<frx:parameters>
</frx:parameters>
<frx:docgen />
<frx:fields>
<frx:field id="title" link="reports/{name}" />
<frx:field id="title" link="reports/help.reportingwysiwyg">WYSIWYG Reporting Guide</frx:field>
</frx:fields>
<frx:parameters />
<frx:docgen />
</head>
<body>
<div id="forena-1" frx:block="forena_help/design_topics">
<p>
Forena provides a <strong>What You See Is What You Get </strong>(WYSIWG)
compatible report editor to make the creation of a basic reports
very easy. &nbsp;You don't have to know XHTML and CSS to create a
simple report, but Forena is designed to leverage your html/css
knowledge, so the more you now about html and css, the more you
will be able to do with forena.&nbsp;
</p>
<p>Novice users may want to start by creating reports using the
report editor built into forena. &nbsp;Users with knowledge of
XHTML, CSS and XML may choose to edit the report defnition files
directly, or edit reports without the use of the WYSIWYG editor.
&nbsp;Forena Report XML (frx) reference is provided for those who
are interested in working on the XHTML files directly. &nbsp;</p>
<ul>
<li id="forena-2" frx:foreach="*">{title}</li>
</ul>
</div>
<p>This document is no longer in use please see the {title}</p>
</body>
</html>
......@@ -6,38 +6,15 @@
<head>
<title>Forena Site Administrators Guide</title>
<frx:category>Help</frx:category>
<frx:options />
<frx:options hidden="1" />
<frx:parameters>
</frx:parameters>
<frx:docgen />
<frx:fields>
<frx:field id="title" link="reports/{name}" />
<frx:field id="title" link="reports/help.setup">Setup Guide</frx:field>
</frx:fields>
</head>
<body>
<h2>Overview</h2>
<p>Forena is a report writing tool that is designed to help
developers who are knowledgeable in writing SQL.</p>
<p>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.</p>
<p>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.&nbsp;</p>
<p>This guide documents how to install, configure and maintain
forena as well as how to leverage the power of other drupal modules
to enhance Forena's capabilities.</p>
<ul id="forena-1" frx:block="forena_help/admin_topics">
<li id="forena-2" frx:foreach="*"><span>{title}</span></li>
</ul>
<p>&nbsp;</p>
<p>This document is no longer in use please see the {title}</p>
</body>
</html>
......@@ -6,177 +6,16 @@
<head>
<title>Building Custom Data Blocks</title>
<frx:category />
<frx:category>Help</frx:category>
<frx:options hidden="1" />
<frx:parameters>
</frx:parameters>
<frx:docgen />
<frx:fields>
<frx:field id="title" link="reports/{name}" />
<frx:field id="role_report" link="reports/drupaladmin.role_detail">Roles</frx:field>
<frx:field id="title" link="reports/help.data">Data Guide</frx:field>
</frx:fields>
</head>
<body>
<p>Custom data blocks are generally written as .sql files in a
database repository. Below is the contents of the
drupal/role_permissions data block that demonstrates role
permissions.</p>
<pre>
--ACCESS=administer permissions
SELECT * FROM {role_permission} p
WHERE p.rid = :role
</pre>
<p>The content of a data block is a SQL statement.&nbsp;</p>
<h3>Security and data blocks</h3>
<p>
The line beginning with<strong>--ACCESS=<em>some_permission</em>
</strong> is a comment that indicates the permission required to
access the data retrieved by this block. The security for data block
repository is configurable and pluggable, meaning that developers
may create functions that determine how the permission is checked.
In the drupal repository delivered with forena, access permissions
are tested using the drupal user_access() function, so the value
should match a drupal permission. If no value is provided, it assumed
that all users with the &quot;access <em>repository name</em> data&quot;
right will be able to access this data.
</p>
<p>In Drupal 7, drupal permissions passed to the user_access
function are string keys that are usually lower cased versions of
the rights found on the drupal permission tab. However, module and
core developers may use any string that they want in creating
rights. There is unfortunately no easy way in drupal to list module
permissions, but after the permission has been granted to a role,
you may use the {role_report} to determine a listing of rights that may be used
to identify permissons</p>
<h3>Parameters</h3>
<p>
The <strong>:role</strong> parameter in the above example is named token
that will be replaced in the SQL query with a parameter from the
report. The parameter replacement is done by forena in a way that
protects against SQL injection. Although these tokens are modeled
after a commonly used database binding syntax, the replacement is
done by Forena. Use this sytax instead of the native parameter
binding for any database you are accessing with Forena. Tokens may
be reference multiple times within the same SQL query.
</p>
<h3>Parameter Data Types</h3>
<p>All data coming in from parameter forms and from the url is considered string
data. In some cases you may need to make sure that a data block casts the incoming parameters
in a particular type. Numeric values should be included in the SQL without surrounding quotes, but
in a way that is safe from SQL injection attacks.
</p>
<p>
You can use the --INFO section of your data block to specify data types for parameters in the data block as is
seen in the following example:
</p>
<pre>
--ACCESS=access content
SELECT nid FROM node
WHERE promote=1
AND status=1
ORDER BY sticky DESC, created
--IF=:limit
LIMIT :limit
--ELSE
LIMIT 10
--END
--INFO
type[limit]=int
</pre>
<p>In the above example, the :limit parameter is specified to be of type int. The following type conversions are
currently supported:</p>
<p><strong>int</strong> - Convert to an integer. This is useful for limit queries as in the above example. </p>
<p><strong>numeric</strong> - Convert to a floating point number (e.g. 6.2)</p>
<p><strong>array</strong> - Convert to an array. This is useful for in clauses</p>
<p><strong>date</strong> - Convert to an ISO representation of a date string in YYYY-MM-DD HH:MI:SS format. PHP date
creation syntax is supported, so you can use values like now + 1 year</p>
<p><strong>unixtime</strong> - Convert to a unix timestamp version of time and treat this as an integer. This is particularly
useful for working with drupal dates. PHP date creation syntax is supported, so you can use values lke now + 1 year. </p>
<h3>Conditional SQL</h3>
<p>When building data blocks you can specifcy sections of sql that
are only included if a particular parameter is present. This lets
you create SQL that has optional filters that can be of signifciant
complexity and don't get included unless needed. The following
example illustrates this technique</p>
<pre>
--ACCESS=access content
SELECT * from states
--IF=:state
WHERE code=:state
--ELSE
WHERE code='AL'
--END
ORDER BY NAME
</pre>
<p>In the above example the Where clause is only added when there
is a value specified for :state. If no value for :state is provided
the WHERE clause limits the selection to code of 'AL'. The order by
clause is always included.</p>
<p>
Alternatively a switch/case syntax provides a way to test the values of an
incoming parameter and conditionaly run some SQ:
</p>
<pre>
SELECT * from some_database_table
--SWITCH=:sort
--CASE=code
ORDER BY code
--CASE=total
ORDER BY total
--ELSE
ORDER BY name
--END
</pre>
<p>
In the above example, sort pased a value of code it would sort by the code column,
but if it passed a value of total it would sort by the total column, otherwise it would sort by the
name column.
</p>
<h3>Includes</h3>
<p>Blocks can be build from other data blocks. To accomplish this
use the --INCLUDE directive as follows:</p>
<pre>
--ACCESS=access content
SELECT * FROM (
--INCLUDE=users_by_state
) t
WHERE state=:state
</pre>
<p>Note that when icluding other data blocks you can only include
blocks within the same repository, and that the security of the new
datablock is the security that is used for that data. The --ACCESS
line of the included block is ignored.</p>
<h3>Drupal Entities</h3>
<p>When using the Drupal data driver you can create data blocks that
load drupal entities instead of selecting columns from the database. To do this specify an entity_type and entity_id column
in the --INFO section of your data block as is shown in the following example:
</p>
<pre>
--ACCESS=access content
SELECT nid, type, title, uid, sticky, promote from node WHERE type=:content_type
and status=1
ORDER BY title
--INFO
; This demonstrates loading node entities.
entity_type = node
entity_id = nid
</pre>
<p>The example illustrates loading a node, but any entity may be loaded.
</p>
<ul id="forena-1" frx:block="forena_help/admin_topics">
<li id="forena-2" frx:foreach="*"><span>{title}</span></li>
</ul>
<h3>Raw Mode Queries</h3>
<p>In some cases where forena is being used to export data, memory consumption can be reduced by specificying a return_type option
of raw in the data block. Currently this option is only supported in the Drupal and PDO drivers. The one drawback for using raw mode is
that all of the xpath features are disabled for that data query as forena will not prerender the result set into XML. This means that your iterators can only use an frx:foreach attribute of *
and only column names may be used as token replacements in the query. You also will be unable to use xpath evaluation expressions
in your reports that use this feature. The following example illustrates raw mode used in a drupal query.</p>
<pre>
SELECT nid, type, title, uid, sticky, promote from node
--INFO
; Use raw mode
return_type = raw
</pre>
<p>This document is no longer in use please see the {title}</p>
</body>
</html>
......@@ -9,338 +9,12 @@
<frx:options hidden="1" />
<frx:parameters>
</frx:parameters>
<frx:docgen>
</frx:docgen>
<frx:docgen />
<frx:fields>
<frx:field id="title" link="reports/{name}" />
<frx:field id="title" link="reports/help.reportingfrx">FRX Reporting Guide</frx:field>
</frx:fields>
</head>
<body>
<ul id="design_topics_block" frx:block="forena_help/design_topics">
<li id="design_topics" frx:foreach="*"><span>{title}</span></li>
</ul>
<h2 id="overview">Overview</h2>
<p>Forena reports are defined using the Forena Report Xml template
format (frx).&#xA0; The template format is largely an XHTML document
which is extended by some custom HTML tags and attributes.&#xA0; The
result should be something familiar to anyone that uses html.</p>
<p>
<strong>Where are reports stored?</strong>
</p>
<p>Reports are stored as files on your reporting server, and may be
edited with a text editor directly, or via a user interface provided
by forena.</p>
<p>
<strong>A Simple Report:</strong>
</p>
<p>The following example illustrates a very simple report:</p>
<html frx:renderer="FrxSource">
<head>
<title>A sample report</title>
</head>
<body>
<div frx:block="sampledb/states">
<p frx:foreach="*">{code} - {name}</p>
</div>
</body>
</html>
<p>There are basically three custom tags that appear in the simplest
version of the report:</p>
<p>
<strong>xmlns:frx element</strong>- This defines the document as a
Forena Report XML template document.&#xA0; It should appear exactly
this way in the document.
</p>
<p id="block">
<strong>frx:block attribute</strong> - This tells forena to load data
from the defined data block (in this case sample/sampleXML.&#xA0; 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.
</p>
<p id="foreach">
<strong>frx:foreach attribute</strong>- This will cause 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 would imply creating a a repeating pattern for every row or
element returned by the query.
</p>
<p id="skip_root">
<strong>frx:skip_root attribute</strong>- This will cause 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.
</p>
<p id="invalid-link"><strong>frx:invalid_link attribute</strong>- To cause forena to validate
links prior to presenting them. Supports the following values: </p>
<table >
<tbody>
<tr>
<th>remove</th><td>Remove the feild (do not render it)</td>
</tr>
<tr>
<th>text</th><td>Render the text without the link</td>
</tr>
<tr>
<th>disable</th><td>Disable the link by removeing its href attribute.
This will also add a class="disabled" on the link for css styling.</td>
</tr>
</tbody>
</table>
<h2>Report fields (token replacement)</h2>
<p>Each field in the report is referenced by an xpath expression
enclosed by curly braces (e.g. {code}). In its simplest form the xpath xpression 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 this
syntax.
</p>
<p>
In the head section of the .frx file, you will find a series of
frx:field elements that define special formatting rules for each of the
report fields referenced in the .frx file.
</p>
<h3>Data Contexts</h3>
<p>
Reports from other section of a report may be used by referencing other data contexts by their
id. For example, if you place an id attribuute 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 the
a context by that id (e.g. {state.name}).
</p>
<h3>Custom Contexts</h3>
<p>
Modules may provide their own custom data contexts either by adding them in a hook_forena_parmaters_alter
implementation or by implementing a custom context class of their own.
</p>
<h3>FrxReport Contexts</h3>
<p>
Forena provides a custom FrxReport context that allows you to embed reports easily. For example, the
sample report (Simple Table of States) may be embedded in another report simply by including
{FrxReport.sample.states} anywhere in a report. 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.
</p>
<h2>Frx Attributes</h2>
<p id="parameters_attr">
<strong>frx:parameters</strong> 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.
</p>
<p id="if">
<strong>frx:if</strong> attribute determines whether the element will
be rendered. 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 replacement in the attribute to map this
to some column in the database or xml. For example, frx:if="{mycolumn}"
would cause this tag and its children only to be rendered if the
mycolumn field in the database returned true. You may use the
excalmation point to indicate negation, that is, frx:if="!{my_column}"
would only evaluate to true if mycolumn was not present or zero.
Because of the way php string expressions work, listing multiple values
can be interpreted as an "or". So frx:if="{mycolumn}{yourcolumn}" would
evalate to true if either database column contained data. If you need
to use an "and" operator, separate the conditions by "&amp;amp;". So
frx:if="{mycolumn}&amp;amp;{yourcolumn}" would evaluate to true only if
both columns evaluated to true.
</p>
<p id="renderer">
<strong>frx:renderer</strong> uses a custom class to render this
object. How the tag is rendered is defined by implementation of the
renderer. See the <a href="#renderers">Provided Renderers</a> section
for additional information. Typcial syntax looks something like
frx:renderer="FrxXML".
</p>
<p>Other attributes are interpreted directly from the custom
renderers section below.</p>
<h2 id="renderers">Provided Renderers</h2>
<h3 id="FrxInclude">FrxInclude</h3>
<p>This renderer includes a another forena report as an asset with
the approprate tag. The primary use of this renderer is to create
references to external SVG assets. When rendered in a web page, these
need to be wrapped in embed tags, but when being included in a PDF
document the raw SVG should be included. The following attributes are
supported:</p>
<table>
<tr>
<th>frx:source</th>
<td>The site relative forena url to the report asset that needs
to be rendered. (e.g. reports/sample.state_graph.svg?state=WA ).</td>
</tr>
</table>
<h3 id="FrxParameterForm">FrxParameterForm</h3>
<p>Place and customize the normal report parameters input form. Use
it on a div tag anywhere in your report to control exactly where the
parameter form renders. The renderer supports the following frx
attributes:</p>
<table>
<tr>
<th>frx:submit</th>
<td>The label applied to the submit button</td>
</tr>
<tr>
<th>frx:title</th>
<td>The title applied to the parameters fieldset</td>
</tr>
<tr>
<th>frx:collapsible</th>
<td>Set to 0 to make the form not collapsible</td>
</tr>
<tr>
<th>frx:collapsed</th>
<td>Indicate wether the fieldset is collapsed by default.</td>
</tr>
</table>
<p>The children of the FrxParmameterForm div allow you to specify
the exact layout of the parameters form using forena's token
replacement syntax. The default context is changed to be the rendered
form so that the parmeter ids will allow replacement of a form control.
</p>
<h3 id="FrxMyReports">FrxMyReports</h3>
<p>Displays the users list of reports. If you add an frx:category attribute you
can limit the display to a particular category.</p>
<h3 id="FrxCrosstab">FrxCrosstab</h3>
<p>When placed on a table tag, this will generate a crosstab version of
a table. The structure of the encolsed table determines the general layout. TH elements
in the tbody tag indicate the fixed columns of the table, while the TD elements
will be generated for each value in the cell. Liwise in the THEAD section of the table,
TH elements indicate fixed column headers, while the TD cell indicates the values that will
be generated for each dimention value. Special attributes are as follows:</p>
<table>
<tr><th>frx:group</th><td>Indicate which data field elements to group the rows by using the brace token replacement syntax.</td></tr>
<tr><th>frx:dim</th><td>TD columns will be generated for each value of the dimension attribute, again using the token replacement syntax. </td></tr>
</table>
<h3 id="FrxSource">FrxSource</h3>
<p>Display markup as a code snippet. No token replacement is done
for the children and all embedded code is escaped html. This is used in
the forena help files to display the source of reports.</p>
<h3 id="FrxSVGGraph">FrxSVGGraph</h3>
<p>Render the node as an SVG graph. The PHP SVGGraph library must be
installed in order for this renderer to function. The following
attributes are supported:</p>
<table>
<tr>
<th>frx:series</th>
<td>The column containing the series of the graph. Multple series
may be specified using an attribute of frx:series_1 for the first
series frx:series_2 as the second and so on.</td>
</tr>
<tr>
<th>frx:path</th>
<td>The xpath to the data to be graphed.</td>
</tr>
<tr>
<th>frx:label</th>
<td>The label that should be used for the series. Usually this is
specified in tokens (e.g. {code})</td>
</tr>
</table>
<p>
In additons any attributes supported as PHP SVGGraph options may be
included as frx: attributes. For example, to specify graph colors, you
can specify frx:color_1="red" and frx:color_2="blue". See the <a
href="http://www.goat1000.com/svggraph.php"> PHP SVGGraph</a>
documentation for more info.
</p>
<h3 id="FrxTitle">FrxTitle</h3>
<p>
Use the content of this tag as the Drupal Title. This allows both
the page title and the tab title to be replaced by token replaced values
in the report.
</p>
<h3 id="FrxXML">FrxXML</h3>
<p>
Displays the XML of the current data context and is particularly useful
for debugging purposes. If you embed this in a report, it will show you
the XML data source that is used for token replacement, so it can give
you a good idea as to what data is being returned and which tokens can
be used.
</p>
<h2 id="parameters">Report Parameters</h2>
<p>
Forena is designed to pass url query parameters 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 define parameters in the head section of the .frx file as follows:
</p>
<head frx:renderer="FrxSource">
<title>My Report Title</title>
<frx:parameters>