Skip to content

GitLab

Commit afd10ef7 authored by David Metzler's avatar David Metzler
Browse files

Updated development docs 

Removed {skin.forena} reference.
parent d8eefa7c
Hide whitespace changes
Inline Side-by-side
repos/forena_help/development_topics.xml
View file @ afd10ef7
<?xml version="1.0" encoding="UTF-8"?>
<root>
<row>
<title>Overview</title>
<name>help.development</name>
</row>
<row>
<title>Forena provided hooks</title>
<name>help.forena_hooks</name>
</row>
<row>
<title>Implementing Data Plugins</title>
<name>help.plugins</name>
</row>
<row>
<title>Implementing Field Formatters</title>
<name>help.formats</name>
</row>
<row>
<title>Implementing Templates</title>
<name>help.templates</name>
</row>
</root>
<book>
<booktitle>Development</booktitle>
<bookfolder>help.development</bookfolder>
<chapters>
<chapter>
<title>Introduction</title>
<subtitle>Content at a glance</subtitle>
<abstract></abstract>
<link>intro</link>
</chapter>
<chapter>
<title>Available hooks</title>
<subtitle>Available hooks for adding reporting extensions</subtitle>
<abstract>Custom hooks are implemented to allow the report engine to be extended in many ways. Using OOP methodologies, any of the available classes may be extended, or new ones can be written from scratch.</abstract>
<link>hooks</link>
</chapter>
<chapter>
<title>Field Formatters</title>
<subtitle>Implement custom formatters either in control objects or in data plugin objects</subtitle>
<abstract>Implementing a formatter requires the implementation of Formatter Methods and a Formats Registration Function.</abstract>
<link>formats</link>
</chapter>
</chapters>
</book>
\ No newline at end of file
repos/reports/help/development.frx
View file @ afd10ef7
......@@ -16,25 +16,134 @@
</frx:fields>
</head>
<body>
<p>Forena implements custom hooks to allow the report engine to be
extended in many ways.&#xA0; Forena does use OOP methodogies, but
also leverages the observer pattern so prevalent in Drupal.</p>
<p>There is then a common pattern that is used to extend
Forena.&#xA0;</p>
<p>1. Implement a custom php class that lives in your module
directory.&#xA0; You may extend any of the forena classes, or write
your own from scratch.&#xA0;</p>
<p>2. Implement the expected registration methods in your class.
(e.g. templates, formats)</p>
<p>3. In your module implement a hook (e.g.
mymodule_forena_controls)&#xA0; that tells forena the location of
your class definition file.</p>
<p>See Also:</p>
<p>&#xA0;</p>
<div id="nav" frx:block="forena_help/development_topics">
<div class="toc" id="help-toc-1" frx:block="forena_help/devlopment_topics">
<h3>Including</h3>
<ul>
<li id="nav-row" frx:foreach="*"><span>{title}</span></li>
<li id="help-toc-2" frx:foreach="/book/chapters/chapter">{title}<span frx:if="{subtitle}">: {subtitle}.</span></li>
</ul>
</div>
<h2 id="intro">Introduction</h2>
<p>Forena implements custom hooks to allow the report engine to be extended in many ways. Forena does use OOP
methodologies, but also leverages the observer pattern so prevalent in Drupal.</p>
<p>There is then a common pattern that is used to extend Forena:
</p>
<ol>
<li>Implement a custom php class that lives in your module directory. You may extend any of the Forena classes, or
write your own from scratch.</li>
<li>Implement the expected registration methods in your class (e.g. templates, formats).</li>
<li>In your module implement a hook (e.g. mymodule_forena_controls) that tells Forena the location of your class
definition file.</li>
</ol>
<h2 id="hooks">Forena Hooks</h2>
<h3>hook_forena_controls</h3>
<p>This hook defines controls that are always loaded during Forena. The most common uses are for implementing custom
field formatters or templates. This hook should return an array of control definitions. Each control definition is represented
as an associative array of the following key/value pairs.</p>
<table>
<tbody>
<tr>
<th>class</th>
<td>The name of the control class provided by the module</td>
</tr>
<tr>
<th>file</th>
<td>The filename to include prior to instantiating the class</td>
</tr>
</tbody>
</table>
<p>Forena uses its own mechanisms for advertising its controls. The following can be used as a reference
implementation for this hook.</p>
<div class="php">function forena_forena_controls() { $controls[] = array('file' =&gt; 'plugins/FrxControls.inc', 'class'
=&gt; 'FrxControls', ); return $controls; }</div>
<h3>hook_forena_plugins</h3>
<p>This hook defines custom data providing plugins for Forena. The most common use is for implementing custom XML
data repository types, but they can also be used for defining formatting functions that are specific to a data provider type.
Like hook_forena_controls, this hook should return an array of plugin definitions. Each control definition is represented as
an associative array of the following key/value pairs.</p>
<table >
<tbody>
<tr>
<th>class</th>
<td>The name of the plugin class provided by the module</td>
</tr>
<tr>
<th>file</th>
<td>The filename to include prior to instantiating the class</td>
</tr>
</tbody>
</table>
<p>Forena uses its own mechanisms for advertising its controls. The following can be used as a reference
implementation for this hook.</p>
<pre class="php">
function forena_forena_controls() {
$controls[] = array('file' =&gt; 'plugins/FrxControls.inc', 'class'=&gt; 'FrxControls', );
return $controls;
}
</pre>
<h3>hook_forena_repos_alter</h3>
<p>Use this hook to advertise your own data connections and data blocks to be delivered by a custom module. Use the
following implementation as a sample:</p>
<pre class="php">
function myexample_forena_repos_alter(&amp;$repos) {
$m_path = drupal_get_path('module', 'myexample');
$repos['myexample'] = array(
'path' =&gt; $m_path . '/data',
'title' =&gt; 'My Sample repository',
'access callback' =&gt; 'user_access',
'user callback' =&gt; 'forena_current_user_id',
'data provider' =&gt; 'FrxDrupal',
);
}
</pre>
<p>In this sample, the module would provide custom SQL data blocks that access data from the drupal default database. Data
would be referenced in the report using frx:block="myexample/myblock". The SQL files for this block would be in the
data/myblock.sql file. The data blocks would use drupal security and the :current_user parameter in any data block would be
populated with the uid of the current drupal user.</p>
<h3>hook_forena_report_directory</h3>
<p>Use this hook to advertise module provided report include directories. Use the following as a sample implementation:</p>
<pre class="php">
function myexample_forena_report_directory() {
return drupal_get_path('module', 'myexample') . '/reports';
}
</pre>
<p>In the above example any reports defined in the modules 'reports' directory would also be displayed. Note that currently
after a module is enabled, you would need to {clear_the_cache}</p>
<h3>hook_forena_parameters_alter</h3>
<p>This alter hook allows you to alter the incoming parameters for any report, but also to provide additional data contexts
that can be made available in your reports. A simple implementation follows:</p>
<pre class="php">function myexample_forena_parameters_alter($report_name, &amp;$parms) { // Set a data context for use in
reports $sec['admin'] = user_access('access administration pages') ? 'Y' : ''; Frx::Data()-&gt;setContext('security', $sec); }
</pre>
<p>
In the above example, you would be able to reference <strong>:security.admin</strong> in any data block or <strong>{security_admin}</strong>
to reference a value of 'Y' whenever the user had access to Drupal's access administration pages right.
</p>
<h2 id="formats">Custom Formatters</h2>
<p>Custom formatters may be implemented either in control objects or in data plugin objects. Formatters that are implemented in plugin objects are only available within data blocks that reference data block repositories that use that plugin type. For example, formatters defined by the FrxOracle plugin will only be available fore repositories that are Oracle repositories. Formatters defined in FrxControls, however, will be available in all reports.</p>
<p>To implement a formatter in control or plugin class requires the implementation of two methods.</p>
<h3>Formatter Methods</h3>
<p>Formatter methods should take a value and a format string parameter, and should return the formatted value. The
following function can be used as a reference implementation of a formatter function.</p>
<pre class="php">
public function iso_date($value, $format_str) {
if ($value) $date = strtotime($value);
return $this-&gt;drupal_date_format($date, $format_str);
}
</pre>
<h3>Formats Registration Function</h3>
<p>Each class that implements formatters should also implement a formats registration function that returns an associative array that lists the function names and their appropriate user label. Forena uses its own registration mechanisms for advertising its controls. The following can be used as a reference implementation for this method.</p>
<pre>
//date formats
public function formats() {
$formats = array('drupal_date_format' =&gt; 'Drupal Date',
'iso_date' =&gt; 'ISO Date',
);
return $formats;
}
</pre>
</body>
</html>
repos/reports/help/setup.frx
View file @ afd10ef7
......@@ -70,8 +70,8 @@
title="Structered Query Language">SQL</abbr> files. The .sql data blocks are stored on the file system, typically in a
location that is not writable by the web user.
</p>
<p>This guide documents how to install and configure {skin.forena} as well as how to leverage the power of some external
libraries to enhance {skin.forena}'s capabilities.</p>
<p>This guide documents how to install and configure Forena as well as how to leverage the power of some external
libraries to enhance Forena's capabilities.</p>
<h2 id="installation">Installation and Configuration</h2>
<h3 id="text-formats">Prepare a text format to be used by forena</h3>
......
repos/reports/help/skins.frx
View file @ afd10ef7
......@@ -26,8 +26,8 @@
<h2>Defining Skins</h2>
<p>
Skins are defined be creating skin configuration files (.skinfo) in the reports directory (usually
sites/default/files/reports). {skin.forena} comes with a few example configuration files, such as <strong>default_skin.skinfo</strong>,
located in {skin.forena}'s subdirectory repos/reports and which can be used as a template for creating new skins. Using the
sites/default/files/reports). Forena comes with a few example configuration files, such as <strong>default_skin.skinfo</strong>,
located in Forena's subdirectory repos/reports and which can be used as a template for creating new skins. Using the
'Revert all delivered reports to original' option (by checking its checkbox) within <a href="/admin/structure/forena"
target="_self">admin/structure/forena</a> will create a copy of default_skin.skinfo in the reports directory.
</p>
......@@ -37,7 +37,7 @@
; The name indicates the name displayed in the skin select box
; on the Format tab when editing reports.
name = Default Skin
description = Default skin for use with {skin.forena}.
description = Default skin for use with Forena.
; JavaScript include example
scripts[] = dataTables/media/js/jquery.dataTables.min.js
; css Include example
......@@ -73,13 +73,13 @@
<p>Stylesheets can be included using the same syntax for Drupal themes. Including a stylesheets[all][]=sheet.css line in
your .skinfo file, will cause the sheet.css file to be loaded for any media types.</p>
<p>If you are using a PDF generator (MPDF or Prince), understand that you can specify stylesheets[pdf][] entries to include
particular stylesheets only in the PDF transformation. {skin.forena} looks first in the reports directory for the stylesheets
particular stylesheets only in the PDF transformation. Forena looks first in the reports directory for the stylesheets
and then at the site root level, so you can specify theme css files by fully qualifying the path to the theme. This can be
particularly useful when you want to include a typography stylesheet in your PDF translations.</p>
<h2>JavaScript Libraries</h2>
<p>
JavaScript libraries are included using the same syntax as is used in the theme info file. In the above example the
scripts[]=dataTables/media/js/jquery.dataTables.js is used to load the JQuery dataTables library. {skin.forena} will search
scripts[]=dataTables/media/js/jquery.dataTables.js is used to load the JQuery dataTables library. Forena will search
for these libraries first in the report directory and then in the sites/all/libraries folder (checkout <a
href="./help.setup.datatables" target="_self">Enable DataTables</a> for instructions about how to install the dataTables
library). This is particularly useful if you want to load additional JQuery plugins for a set but not all reports. You can add
......@@ -93,7 +93,7 @@
; The name indicates the name displayed in the skin select box
; on the Format tab when editing reports.
name = Custom Skin
description = Custom skin for use with {skin.forena}.
description = Custom skin for use with Forena.
; Javascript include example
scripts[] = dataTables/media/js/jquery.dataTables.min.js
scripts[] = custom_skin.js
......@@ -104,7 +104,7 @@
<p>
Note the <strong>custom_skin.js</strong> and <strong>custom_skin.css</strong> that were added. Storing them in the same
directory as the custom_skin.skinfo (i.e. the reports directory, usually sites/default/files/reports) is a good practice that
will simplify upgrading to future {skin.forena} versions.
will simplify upgrading to future Forena versions.
</p>
<h3>Adding content to the custom CSS file</h3>
<p>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment