Commit 68d18728 authored by Pierre.Vriens's avatar Pierre.Vriens
Browse files

#2124777 Correct typos, add missing links in development guide

parent 7e7f202f
......@@ -16,7 +16,7 @@
<link>hooks</link>
</chapter>
<chapter>
<title>Field Formatters</title>
<title>Custom 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>
......
......@@ -184,8 +184,12 @@
new data block repository using <strong>local</strong> as the machine readable name (which is used in referencing all data
blocks used by this data source and which should not contain any special characters or spaces):
</p>
<pre frx:renderer="FrxSource"> global $_forena_repositories; $_forena_repositories['local'] = array( 'path' =&gt;
'sites/default/local_blocks', 'title' =&gt; 'Site Specific Data Blocks' ); </pre>
<pre class="code">
global $_forena_repositories;
$_forena_repositories['local'] = array(
'path' =&gt; 'sites/default/local_blocks',
'title' =&gt; 'Site Specific Data Blocks' );
</pre>
<p>The following table illustrates the options provided:
</p>
<table>
......@@ -284,7 +288,7 @@
</p>
<ul>
<li>the most common format for these files is <abbr title="Structered Query Language">SQL</abbr>, used for all supported data engines except for FrxFiles (XML Files). Here is a sample of such SQL file:<br />
<pre>
<pre class="code">
--ACCESS=access administration pages
SELECT type, count(type) as typecount
FROM {watchdog}
......@@ -331,7 +335,7 @@ LIMIT 50
To specifying Data Blocks Security for a data block in SQL format, use an SQL comment starting with <strong>ACCESS=<em>some_permission</em></strong>,
as in this example:
</p>
<pre>
<pre class="code">
--ACCESS=administer users
SELECT u.uid,u.name
FROM {role} r
......@@ -339,7 +343,7 @@ FROM {role} r
JOIN users u ON ur.uid=u.uid WHERE r.rid = :role
--INFO
type[role]=int
</pre>
</pre>
<h3>XML Data Blocks Security</h3>
<p>
To specifying Data Blocks Security for a data block in XML format, use an XML comment line containing <strong>ACCESS=<em>some_permission</em></strong>.
......@@ -373,20 +377,20 @@ type[role]=int
<p>You can use the --INFO section of your data block to specify data types for parameters in the data block as in this
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>
<pre class="code">
--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 last line of it), the <strong>:limit</strong> parameter is specified to be of type <strong>int</strong>. The following Parameter Data Types are supported:
</p>
......@@ -422,7 +426,7 @@ type[role]=int
The <strong>--IF / --ELSE / --END</strong> syntax provides a way to test a value of an incoming parameter to conditionally
construct part of an SQL statement. The following example illustrates this technique:
</p>
<pre>
<pre class="code">
SELECT * from
states
--IF=:state
......@@ -431,7 +435,7 @@ WHERE code=:state
WHERE code='AL'
--END
ORDER BY NAME
</pre>
</pre>
<p>
In the above example the WHERE clause is only added to the SQL if there is a value specified for the report parameter
<strong>:state</strong>. If no value for the :state parameter is provided, then the WHERE clause limits the selection to code
......@@ -442,7 +446,7 @@ ORDER BY NAME
Alternatively the <strong>--SWITCH / --CASE / --ELSE / --END</strong> syntax provides a way to test for multiple values of an
incoming parameter and conditionally construct part of an SQL statement. The following example illustrates this technique:
</p>
<pre>
<pre class="code">
SELECT * from some_database_table
--SWITCH=:sort
--CASE=code
......@@ -452,7 +456,7 @@ ORDER BY total
--ELSE
ORDER BY name
--END
</pre>
</pre>
<p>
In the above example, if the report parameter
<strong>:sort</strong> passed a value of
......@@ -465,13 +469,13 @@ ORDER BY name
<h2 id="datablockincludes">Data Block Includes</h2>
<p>Data blocks can be build from other data blocks. To accomplish this use the --INCLUDE directive as in this example:
</p>
<pre>
--ACCESS=access content
SELECT * FROM (
--INCLUDE=users_by_state
) t
WHERE state=:state
</pre>
<pre class="code">
--ACCESS=access content
SELECT * FROM (
--INCLUDE=users_by_state
) t
WHERE state=:state
</pre>
<p>Be aware however of these restrictions / limitations when including other data blocks:
</p>
<ul>
......@@ -485,16 +489,16 @@ ORDER BY name
your data block as illustrated in this 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>
<pre class="code">
--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>This example illustrates loading a node, but any entity type (like users, or some custom entity type) may be loaded.</p>
<h2 id="rawmodequeries">Raw Mode Queries</h2>
<p>
......@@ -502,12 +506,12 @@ ORDER BY name
option of <strong>raw</strong> in the data block.
</p>
<p>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>
<pre class="code">
SELECT nid, type, title, uid, sticky, promote from node
--INFO
; Use raw mode
return_type = raw
</pre>
<p>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
......
......@@ -6,13 +6,14 @@
<head>
<title>Developers Guide</title>
<frx:category>Help</frx:category>
<frx:options hidden="1" skin="tutorial" />
<frx:options hidden="1" skin="tutorial_skin" />
<frx:parameters>
</frx:parameters>
<frx:docgen>
</frx:docgen>
<frx:fields>
<frx:field id="title" link="reports/{name}" />
<frx:field id="title" link="reports/help.development#{link}" />
<frx:field id="security_admin" link="">{security.admin}</frx:field>
</frx:fields>
</head>
<body>
......@@ -55,12 +56,12 @@
</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>
<pre class="code">
function forena_forena_controls() {
$controls[] = array('file' =&gt; 'plugins/FrxControls.inc', 'class' =&gt; 'FrxControls');
return $controls;
}
</pre>
</pre>
<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.
......@@ -80,26 +81,25 @@ function forena_forena_controls() {
</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">
<pre class="code">
function forena_forena_controls() {
$controls[] = array('file' =&gt; 'plugins/FrxControls.inc', 'class'=&gt; 'FrxControls', );
return $controls;
}
</pre>
</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 class="code">
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
......@@ -108,24 +108,22 @@ function forena_forena_controls() {
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>
<pre class="code">
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.</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">
<pre class="code">
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>
</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.
......@@ -136,22 +134,22 @@ function myexample_forena_parameters_alter($report_name, &amp;$parms) {
<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>
<pre class="code">
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>
<pre class="code">
//date formats
public function formats() {
$formats = array('drupal_date_format' =&gt; 'Drupal Date',
'iso_date' =&gt; 'ISO Date',
);
return $formats;
}
</pre>
</body>
</html>
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