Charts and Graphs - Arbitrary XML Settings in Charts and Graphs 7
Same filename and directory in other branches
Charting libraries that use XML files to define charts use a array based structure to enable users settings arbitrary parameters. The expected array structure is described here.
Parameters
To allow the definition of any XML structure the array supports the following parameters:
- #attributes
- optional parameter for attribute setting. When present it's an array where each key is the attribute name and each value is the attribute value.
- #cdata
- sets the CDATA content of the tag. Each tag can have one #cdata or one #value or none of the both but can't have both.
- #children
- it holds the tags nested inside the current tag. If present must be an array with the tags that go inside the current tag. It's optional and, when present, it's always an array of arrays as it must support several tags inside it.
- #id
- sets the tag ID. This is the only mandatory parameter.
- #value
- sets the text content of the tag. For tags without content is can be ommited. For nested tags see #children.
To remove a tag defined by the charting library the user must pass a tag with the id to be removed and the #value parameter with the NULL value.
Examples
Here is a rather complete example. Remember that the only mandatory parameter is #id. Observe that the main array and each #children array is an array of arrays.
<?php $canvas->settings = array( array( '#id' => 'value', '#value' => $this->encode_for_xml($val), '#attributes' => array( 'xid' => 13, ), array('#id' => 'js_enabled', '#value' => 'false'), array( '#id' => 'axes', '#children' => array( array( '#id' => 'y_left', '#children' => array(array( '#id' => 'logarithmic', '#value' => 'true')), ), array('#id' => 'show', '#cdata' => '{title}: {value}%'), ), )), );
The above code results in the following settings file:
<?xml version="1.0" encoding="utf-8"?>
<settings>
<value xid="13">STRING_REPRESENTATION_OF_ENCODED_VALUE_OF$val</value>
<js_enabled>false</js_enabled>
<axes>
<y_left>
<logarithmic>true</logarithmic>
</y_left>
<show><![CDATA[{title}: {value}%]]></show>
</axes>
</settings>
Observations
To guarantee complete flexibility no treatment is made in the contents of any paramters: #id, #value etc. Any enconding, case transformation or else must be done by the user before passing the data to each charting library.
#cdata content receive CDATA's prefix and suffix:
<![CDATA[and
]]>This can be seen as an exception for the above rule.
File
help/arbitrary_xml.htmlView source
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Charts and Graphs - Arbitrary XML Settings</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<p>Charting libraries that use XML files to define charts use a array based
structure to enable users settings arbitrary parameters. The expected
array structure is described here.</p>
<h3>Parameters</h3>
<p>To allow the definition of any XML structure the array supports the following parameters:</p>
<dl>
<dt>#attributes</dt>
<dd>optional parameter for attribute setting. When present it's an array
where each key is the attribute name and each value is the attribute
value.</dd>
<dt>#cdata</dt>
<dd>sets the CDATA content of the tag. Each tag can have one <b>#cdata</b>
or one <b>#value</b> or none of the both but can't have both.</dd>
<dt>#children</dt>
<dd>it holds the tags nested inside the current tag. If present must be an
array with the tags that go inside the current tag. It's optional and,
when present, it's always an array of arrays as it must support several
tags inside it.</dd>
<dt>#id</dt>
<dd>sets the tag ID. This is the only mandatory parameter.</dd>
<dt>#value</dt>
<dd>sets the text content of the tag. For tags without content is can be
ommited. For nested tags see <b>#children</b>.</dd>
</dl>
<p>To remove a tag defined by the charting library the user must pass a tag
with the id to be removed and the <b>#value</b> parameter with the NULL
value.</p>
<h3>Examples</h3>
<p>Here is a rather complete example. Remember that the only mandatory
parameter is <b>#id</b>. Observe that the main array and each
<b>#children</b> array is an array of arrays.</p>
<pre>
<?php
$canvas->settings = array(
array(
'#id' => 'value',
'#value' => $this->encode_for_xml($val),
'#attributes' => array(
'xid' => 13,
),
array('#id' => 'js_enabled', '#value' => 'false'),
array(
'#id' => 'axes',
'#children' => array(
array(
'#id' => 'y_left',
'#children' => array(array(
'#id' => 'logarithmic',
'#value' => 'true')),
),
array('#id' => 'show', '#cdata' => '{title}: {value}%'),
),
)),
);
</pre>
<p>The above code results in the following <i>settings</i> file:</p>
<pre>
<?xml version="1.0" encoding="utf-8"?>
<settings>
<value xid="13">STRING_REPRESENTATION_OF_ENCODED_VALUE_OF$val</value>
<js_enabled>false</js_enabled>
<axes>
<y_left>
<logarithmic>true</logarithmic>
</y_left>
<show><![CDATA[{title}: {value}%]]></show>
</axes>
</settings>
</pre>
<h3>Observations</h3>
<p>To guarantee complete flexibility no treatment is made in the contents
of any paramters: <b>#id</b>, <b>#value</b> etc. Any enconding, case
transformation or else must be done by the user before passing the data
to each charting library.</p>
<p><b>#cdata</b> content receive CDATA's prefix and suffix:
<pre><![CDATA[</pre> and <pre>]]></pre> This can be seen as an exception
for the above rule.</p>
</body>
</html>