renderers.frx 16.5 KB
Newer Older
Pierre.Vriens's avatar
Pierre.Vriens committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE root [
<!ENTITY nbsp "&#160;">
]>
<html xmlns:frx="urn:FrxReports">
<head>
<title>Custom Renderers</title>
<frx:category>Help</frx:category>
<frx:options hidden="1" />
<frx:parameters>
</frx:parameters>
<frx:docgen />
<frx:fields>
  <frx:field id="title" link="reports/help.renderers#{link}" />
  <frx:field id="role_detail_report" link="reports/drupaladmin.role_detail" target="_blank"> Roles</frx:field>
  <frx:field id="setup_svggraph_report" link="reports/help.setup#svggraph" target="_blank">PHP SVGGraph library</frx:field>
  <frx:field id="state_summary_report" link="reports/sample.state_summary" target="_blank">State Summary</frx:field>
    <frx:field id="state_summary_ie8_report" link="reports/sample.state_summary_ie8"
    target="_blank">External SVG Graph Example</frx:field>
  <frx:field id="watchdog_stats_report" link="reports/drupaladmin.watchdog_stats?prmsev=4" target="_blank">Watchdog Statistics (for entries with severity 4)</frx:field>
</frx:fields>
</head>
<body>
  <div class="toc" id="help-toc-1" frx:block="forena_help/renderers_topics">
    <h3>Including</h3>
    <ul>
      <li id="help-toc-2" frx:foreach="/book/chapters/chapter">{title}<span frx:if="{subtitle}">: {subtitle}.</span></li>
    </ul>

  </div>
  <p>
metzlerd's avatar
metzlerd committed
32
33
34
    A renderer specifies how an tag in the report template is to render. A good example is to render
    the use of the svg renderere using the <a href="http://www.goat1000.com/svggraph.php" target="_blank"> PHP SVGGraph</a> library, as in
    the {state_summary_report} sample report:
Pierre.Vriens's avatar
Pierre.Vriens committed
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
  </p>
<html frx:renderer="FrxSource" id="frxsrc-1">
<head>...
</head>
<body>
  ...
  <div frx:block="sampledb/users_by_state" id="users_by_state-block" class="FrxSVGGraph">
    <svg id="state-chart" frx:renderer="FrxSVGGraph" frx:type="bargraph" frx:xpath="*[total&gt;10000]" frx:color="{color}"
      frx:link="sample.user_distribution_simple?state={state}" frx:series_1="{total}" frx:label="{state}">
      </svg>
  </div>
  ...
</body>
</html>
<h2 id="frxtitle">FrxTitle</h2>
metzlerd's avatar
metzlerd committed
50
51
<p>Use the content of this tag to override the title of the report. This allows both the page title and the tab title to be replaced by token replaced values in the report.</p>
<p>As an illustration of how to use this renderer, consider the {user_distribution_report} sample report:</p>
Pierre.Vriens's avatar
Pierre.Vriens committed
52
53
54
55
<div frx:renderer="FrxSource">
  <h2 frx:renderer="FrxTitle" id="frx-frxtitle">Users in cities in state {name}</h2>
</div>
<p>
metzlerd's avatar
metzlerd committed
56
57
  Because of the attributes we added to the <strong>h2</strong> HTML tag here (any HTML tag will do)  the existing
    "2. Report that filters based on state lookup" title will be ignored.
Pierre.Vriens's avatar
Pierre.Vriens committed
58
59
</p>
<p>
metzlerd's avatar
metzlerd committed
60
  Moreover, because of the <strong>name</strong> token included in this h2 tag, the rendered title will be dynamic.
Pierre.Vriens's avatar
Pierre.Vriens committed
61
62
63
64
65
66
67
68
69
70
71
72
</p>
<p>
  For another illustration of this renderer, checkout the video about <a href="http://www.youtube.com/watch?v=7ruWRngKtXY"
    target="_blank">Dynamic page titles in reports</a>.
</p>
<h2 id="frxmyreports">FrxMyReports</h2>
<p>Displays the user's list of reports (excluding hidden reports), optionally limited to a single category, as in this
  example:</p>
<div class="FrxMyReports">
  <div frx:renderer="FrxMyReports" frx:category="Sample" id="frxmyrpts" />
</div>
<p>
metzlerd's avatar
metzlerd committed
73
74
  The above sample shows a list of all non-hidden reports in category <strong>Sample</strong>, using the category as the header generated 
  by the following code:
Pierre.Vriens's avatar
Pierre.Vriens committed
75
76
77
78
79
80
81
82
</p>
<div frx:renderer="FrxSource">
  <div frx:renderer="FrxMyReports" frx:category="Sample" id="frxmyrpts" />
</div>
<p>The following attributes are supported for the FrxMyReports renderer:</p>
<table>
  <tr>
    <th>frx:category</th>
metzlerd's avatar
metzlerd committed
83
    <td>Limit the list of reports to be shown to a particular category. Multiple categories may be used by specifying category_2 and category_3 attribtues accordingly.</td>
Pierre.Vriens's avatar
Pierre.Vriens committed
84
85
86
87
88
89
  </tr>
</table>
<h2 id="frxsource">FrxSource</h2>
<p>The FrxSource renderer displays 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 {tutorial_reports} to display the source of reports.</p>
<p>
metzlerd's avatar
metzlerd committed
90
  This renderer is used throughout the documentation as follows:
Pierre.Vriens's avatar
Pierre.Vriens committed
91
92
93
94
95
96
97
98
99
100
</p>
<div frx:renderer="FrxSource">
  <div frx:renderer="FrxSource">
    <p>Embedded xhtml that you want displayed as source including {tokens} that you want to display without being replaced</p>
  </div>
</div>
<h2 id="frxxml">FrxXML</h2>
<p>Displays the XML of the current data context, which 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>
metzlerd's avatar
metzlerd committed
101
<p>Here is a sample that is displayed using the FrxXML renderer which shows the data returned by the datablock:</p>
Pierre.Vriens's avatar
Pierre.Vriens committed
102
103
104
105
106

<div class="xml">
  <div frx:renderer="FrxXML" id="frx-frxxml" frx:block="forena_help/reportingwysiwyg_topics"></div>
</div>

metzlerd's avatar
metzlerd committed
107
<p>Be aware however that this FrxXML renderers removes XML comment lines (e.g. those used to specify
Pierre.Vriens's avatar
Pierre.Vriens committed
108
  {datablock_security} in XML format).</p>
metzlerd's avatar
metzlerd committed
109
<p>The above example was generated with the following code:</p>
Pierre.Vriens's avatar
Pierre.Vriens committed
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
<div frx:renderer="FrxSource">
  <div frx:renderer="FrxXML" id="frx-frxxml" frx:block="forena_help/reportingwysiwyg_topics" />
</div>
<h2 id="frxparameterform">FrxParamterForm</h2>
<p>
  Customize the standard report parameters input form. Use it on a div tag anywhere within the <strong>body</strong> part of your
  report to control various aspects of the rendering of the parameter form, as in the {role_detail_report} sample report, for
  which the .frx file includes these lines:
</p>
<html frx:renderer="FrxSource">
<head>
...
<frx:parameters>
  <frx:parm id="role" data_source="drupal/roles" type="select">3</frx:parm>
</frx:parameters>
...
</head>
<body>
  ...
  <div frx:renderer="FrxParameterForm" frx:title="Report Execution Parameters" frx:collapsible="1" frx:collapsed="0"
    frx:submit="Show users and their permissions" id="parmeter-form">
    <p>Role Description: {role}</p>
    <p>Select a role and hit the button to run the report.</p>
    <p>{submit}</p>
  </div>
  ...
</body>
</html>
<p>The above example illustrates the following FRX attributes supported by the FrxParameterForm renderer:</p>
<table>
  <tr>
    <th>frx:title</th>
    <td>The title of the parameters field set.</td>
  </tr>
  <tr>
    <th>frx:collapsible</th>
    <td>Indicate if the form should be collapsible or not:
      <ul>
        <li>set to "1" to make the parameter form collapsible.</li>
        <li>set to "0" for a parameter form that cannot be collapsed.</li>
      </ul>
    </td>
  </tr>
  <tr>
    <th>frx:collapsed</th>
metzlerd's avatar
metzlerd committed
155
    <td>Indicate how a collapsible parameter form should be shown:
Pierre.Vriens's avatar
Pierre.Vriens committed
156
157
158
159
      <ul>
        <li>set to "1" for a collapsed form.</li>
        <li>set to "0" for a not collapsed form.</li>
      </ul>
metzlerd's avatar
metzlerd committed
160
      The default behavior is to expand the form only if no data was returned by the report. 
Pierre.Vriens's avatar
Pierre.Vriens committed
161
162
163
164
    </td>
  </tr>
  <tr>
    <th>frx:submit</th>
metzlerd's avatar
metzlerd committed
165
    <td>The label of the submit button.</td>
Pierre.Vriens's avatar
Pierre.Vriens committed
166
167
168
  </tr>
</table>
<p>The children of the FrxParameterForm div allow you to specify the exact layout of the parameters form using
metzlerd's avatar
metzlerd committed
169
  Forena's token replacement syntax, which is illustrated in the above example via the content of the 3 paragraphs
Pierre.Vriens's avatar
Pierre.Vriens committed
170
171
172
173
174
175
176
  contained in the FrxParameterForm div. The default context is changed to be the rendered parameter form, so that the parameter
  ids will allow replacement of a form control.</p>
<p>
  <strong>Note</strong>: The parameter form is always rendered at the top (even if you would move it after the data blocks to be
  rendered).
</p>
<h2 id="frxsvggraph">FrxSVGGraph</h2>
metzlerd's avatar
metzlerd committed
177
178
<p>Render a graph using the SVG format, using the {setup_svggraph_report}. Make sure to install this library prior
  to using this renderer.</p>
Pierre.Vriens's avatar
Pierre.Vriens committed
179
180
181
182
183
184
185
186
187
188
189
190
191
192
<p>We'll use the {state_summary_report} sample report to illustrate how to use this renderer, for which the .frx file
  includes these lines:</p>
<div frx:renderer="FrxSource">
  <div frx:block="sampledb/users_by_state" id="users_by_state-block" class="FrxSVGGraph">
    <svg id="state-chart" frx:renderer="FrxSVGGraph" frx:type="bargraph" frx:xpath="*[total&gt;10000]" frx:color="{color}"
      frx:link="sample.user_distribution_simple?state={state}" frx:series_1="{total}" frx:label="{state}">
      </svg>
  </div>
</div>
<p>The following attributes are supported for the FrxSVGGraph renderer:</p>
<table>
  <tr>
    <th>frx:type</th>
    <td>The type of graph to be rendered. If omitted, then <strong>BarGraph</strong> is assumed. These are the currently
metzlerd's avatar
metzlerd committed
193
      supported types of graphs:
Pierre.Vriens's avatar
Pierre.Vriens committed
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
      <ul>
        <li>BarGraph</li>
        <li>Bar3DGraph</li>
        <li>StackedBarGraph</li>
        <li>GroupedBarGraph</li>
        <li>GroupedBarGraph</li>
        <li>CylinderGraph</li>
        <li>StackedCylinderGraph</li>
        <li>GroupedCylinderGraph</li>
        <li>PieGraph</li>
        <li>Pie3DGraph</li>
        <li>HorizontalBarGraph</li>
        <li>LineGraph</li>
        <li>MultiLineGraph</li>
        <li>ScatterGrap</li>
        <li>MultiScatterGraph</li>
        <li>RadarGraph</li>
        <li>MultiRadarGraph</li>
      </ul></td>
  </tr>
  <tr>
    <th>frx:xpath</th>
    <td>The XPATH expression for the data to be graphed (e.g. <strong>*[total&gt;10000]</strong>, which is what is used in
      the sample (note that only states are included in the graph that have a total above 10000). If omitted, then an XPATH
metzlerd's avatar
metzlerd committed
218
      expression of <strong>*</strong> is assumed and all data is graphed.
Pierre.Vriens's avatar
Pierre.Vriens committed
219
220
221
222
223
    </td>
  </tr>
  <tr>
    <th>frx:link</th>
    <td>Create a hyperlink for the data to be graphed (e.g. <strong>sample.user_distribution_simple?state={state}</strong>.
metzlerd's avatar
metzlerd committed
224
      Use feild tokens to generate the link dynamically .
Pierre.Vriens's avatar
Pierre.Vriens committed
225
226
227
228
229
230
231
232
233
234
235
    </td>
  </tr>
  <tr>
    <th>frx:series</th>
    <td>The column containing the series of the graph. Multiple series may be specified using an attribute of <strong>frx:series_1</strong>
      for the first series, <strong>frx:series_2</strong> as the second and so on.
    </td>
  </tr>
  <tr>
    <th>frx:label</th>
    <td>The label that should be used for the series. Usually this is specified using tokens (e.g. <strong>{state}</strong>
metzlerd's avatar
metzlerd committed
236
      in our sample).
Pierre.Vriens's avatar
Pierre.Vriens committed
237
238
239
240
241
    </td>
  </tr>
  <tr>
    <th>frx:options</th>
    <td>This legacy attribute is currently still supported, but it is recommended to replace them by the corresponding <strong>frx:xyz</strong>
metzlerd's avatar
metzlerd committed
242
      attributes. Here is a sample of it was used:<br /> <strong>frx:options="series[]={total}&amp;label={state}&amp;colors[]=green&amp;colors[]=yellow"</strong></td>
Pierre.Vriens's avatar
Pierre.Vriens committed
243
244
245
  </tr>
</table>
<p>
metzlerd's avatar
metzlerd committed
246
247
  In addition to the attributes mentioned above, any attribute  supported as PHP SVGGraph options
  may be included as <strong>frx</strong> attributes also. Here are a few examples of some often used attributes:
Pierre.Vriens's avatar
Pierre.Vriens committed
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
</p>

<table>
  <tr>
    <th>frx:color</th>
    <td>Specify a graph color (e.g. <strong>frx:color="{color}"</strong>). To specify multiple graph colors, you can specify
      <strong>frx:color_1="red"</strong> and <strong>frx:color_2="blue"</strong> also.
    </td>
  </tr>
  <tr>
    <th>frx:width</th>
    <td>Width of the graph to be rendered (e.g. <strong>frx:width="720"</strong>). If omitted, then <strong>600</strong> is
      assumed.
    </td>
  </tr>
  <tr>
    <th>frx:height</th>
    <td>Width of the graph to be rendered (e.g. <strong>frx:height="480"</strong>). If omitted, then <strong>400</strong> is
      assumed.
    </td>
  </tr>
</table>
<p>
metzlerd's avatar
metzlerd committed
271
  Here is an example:
Pierre.Vriens's avatar
Pierre.Vriens committed
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
</p>
<div frx:renderer="FrxSource">
  <div frx:block="sampledb/users_by_state" id="users_by_state-block" class="FrxSVGGraph">
    <svg id="state-chart" frx:renderer="FrxSVGGraph" frx:type="bargraph" frx:xpath="*[total&gt;10000]" frx:color="{color}"
      frx:link="sample.user_distribution_simple?state={state}" frx:series_1="{total}" frx:label="{state}" frx:height="300"
      frx:width="450" frx:axis_min_h="12500" frx:grid_division_h="500" frx:division_size_h="10" frx:division_size_v="0"
      frx:show_subdivisions="true" frx:subdivision_size="5" frx:graph_title_colour="red" frx:graph_title="Enhanced State Graph"
      frx:graph_title_position="top" frx:graph_title_font_weight="bold" frx:graph_title_font="georgia"
      frx:graph_title_font_size="18" frx:label_h="Total nr of users" frx:label_v="State" frx:label_font="georgia"
      frx:label_font_size="14" frx:label_colour="blue" frx:axis_text_angle_h="-60" frx:back_colour="white">
      </svg>
  </div>
</div>
<p>
  <strong>Note</strong>: checkout the {svggraph_library} documentation to fully understand those options.
</p>
<h2 id="frxinclude">FrxInclude</h2>
  <p>This renderer includes another report as an asset with the appropriate 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 {state_summary_ie8_report} report uses this renderer, for which
    the .frx file includes these lines:
  </p>
  
  <div frx:renderer="FrxSource">
    <div frx:src="reports/sample.state_graph.svg?height=400&amp;width=600" frx:renderer="FrxInclude" frx:height="480"
      frx:width="640">...</div>
  </div>
  <p>
  The above example illustrates the following FRX attributes supported by the FrxInclude renderer:
  </p>
  <table>
    <tr>
      <th>frx:src</th>
      <td>The relative URL to the report asset that is to be rendered.</td>
    </tr>
    <tr>
      <th>frx:height</th>
      <td>The height of the report asset that is to be rendered.</td>
    </tr>
    <tr>
      <th>frx:width</th>
      <td>The width of the report asset that is to be rendered.</td>
    </tr>
  </table>
  <p>Some extra details about how this renderer processes various types of assets:
  </p>
  
  <ul>
metzlerd's avatar
metzlerd committed
320
    <li>The markup used to include the specified asset depends on the file extension of the asset as referenced.</li>
Pierre.Vriens's avatar
Pierre.Vriens committed
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
    <li>These are the main groups of supported extensions for the assets:</li>
    <ol>
      <li><strong>svg</strong>: wrapped in an <strong>embed</strong> tag (using a <strong>src</strong> tag as specified in the
        frx:src attribute), using <strong>height</strong> and <strong>width</strong> as specified in the frx attributes, and with an
        <strong>image/svg+xml</strong> MIME type (which is assumed to be supported by the web server).</li>
      <li><strong>png, gif, jpg or jpeg</strong>: wrapped in an <strong>img</strong> tag (using a <strong>src</strong> tag as
        specified in the frx:src attribute), using <strong>height</strong> and <strong>width</strong> as specified in the frx
        attributes.</li>
      <li><strong>other extensions</strong>: wrapped in an <strong>a</strong> tag (anchor), using an the anchor text like <strong>abcd
          document</strong> (abcd = the file extension), and with its <strong>href</strong> as specified in the frx:src attribute.</li>
    </ol>
    <li>Any lowercase / uppercases variations in the file extension of the asset are supported.</li>
  </ul>

<h2 id="frxcrosstab">FrxCrosstab</h2>
<p>
metzlerd's avatar
metzlerd committed
337
338
339
  A <strong>crosstab</strong> table is designed to pivot data, that is to creat a table whose columns are determined by the values in 
  a select statement/data block.  The number of columns in a crosstab query is not constant but rather determined by the data returned by the 
  block.  It is typically used to conver data of this form:
Pierre.Vriens's avatar
Pierre.Vriens committed
340
</p>
metzlerd's avatar
metzlerd committed
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
<table>
  <tr><td>WA</td><td>Female</td><td>100</td></tr>
  <tr><td>WA</td><td>Male</td><td>50</td></tr>
  <tr><td>ID</td><td>Female</td><td>25</td></tr>
  <tr><td>ID</td><td>Male</td><td>30</td></tr>
</table>
<p>Into a table that looks like:</p>
<table>
  <tr><td></td><td>Female</td><td>Male</td></tr>
  <tr><td>WA</td><td>100</td><td>50</td></tr>
  <tr><td>ID</td><td>25</td><td>30</td></tr>
</table>
<p>In order to do this you will need to specify a grouping attribute and a dimension attribute.  The grouping attribute determines how to group the rows of data while
the dimension attribute speicifies which field will be used to create the columns out of.</p>
<p>The layout of the cross tab is follows:</p>
Pierre.Vriens's avatar
Pierre.Vriens committed
356
357
358

<div frx:renderer="FrxSource">
  <div id="watchdog_stats_block" class="FrxCrosstab" frx:block="drupal/watchdog_stats">
metzlerd's avatar
metzlerd committed
359
    <table watchdog_stats="watchdog_stats-renderer" frx:renderer="FrxCrosstab" frx:group="{severity}{name}"
Pierre.Vriens's avatar
Pierre.Vriens committed
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
      frx:dim="Msg Type: {type}">
      <thead>
        <tr>
          <th>Message</th>
          <th>Severity</th>
          <th>User Name</th>
          <td>Nr of msgs</td>
        </tr>
      </thead>
      <tbody>
        <tr id="watchdog_stats" frx:watchdog_stats="watchdog_stats-renderer">
          <th>{message}</th>
          <th>{severity}</th>
          <th>{name}</th>
          <td>{typecount}</td>
        </tr>
      </tbody>
    </table>
  </div>

</div>

</body>
</html>