eZ components - Graph ~~~~~~~~~~~~~~~~~~~~~ .. contents:: Table of Contents :depth: 2 Introduction ============ The graph components enables you to create line, pie and bar charts. The output driver mechanism allows you to create different image types from each chart, and the available renderers make the chart output customizeable from simple two dimensional charts up to beautiful three dimensional data projections. ezcGraph separates different parts of the graph in chart elements, which display one part of a graph, like the title, the legend or one axis, which are all independently configurable. This design not only allows you to use different colors or fonts for each chart element, but also define their position and size. The main chart elements are the same for all chart types. For easy definition of a overall layout for your graph you can use palettes, which define colors, symbols, fonts and spacings. The data is provided through ezcGraphDataSets which are normally create from simple arrays, but also can perform statistical operations on the data, as you will see later. Class overview ============== This section gives you an overview on all classes, that are intended to be used directly. ezcGraphChart Line, bar and pie chart extend this abstract class, that represents the chart to be rendered. It collects the data and chart elements, gives you access to all configuration settings and calls the driver and renderer for creating the final output. ezcGraphDataSet All data sets extend this abstract class to provide the data in a general form, accessible by the chart. ezcGraphChartElement All chart element store configuration values defining their layout. A elements layout definition contains background, border, margin, padding and font configuration. This class is extended by classes for Legend, Text, Background and the different axis types. ezcGraphChartElementAxis Extends ezcGraphChartElement and is the base class for all axis. There are different axis types for different data to be displayed, like numeric axis, string labeled axis or the date axis. ezcGraphAxisLabelRenderer Defines the rendering algorithm for labels and grid on axis. The distinction is necessary, because bar charts expect their labels placed directly below the data point, but numerical data in line charts should be placed next to grid. ezcGraphPalette Contains color, font, symbol and spacing definitions, that are applied to the complete graph. ezcGraphRenderer The renderer transforms chart primitives, like pie chart segments, legend or data lines, to image primitives. You have the choice between a two and a three dimensional renderer. ezcGraphDriver The driver actually renders image primitives to an image. The default driver will output a SVG, but you can also render JPEGs or PNGs using ext/gd. Chart types =========== Creating pie charts ------------------- The following graph is a simple example how to create a pie chart using the default driver, palette and renderer. .. include:: tutorial_example_01.php :literal: You just create a new chart object, optionally set a title for the chart assign the data and render it. To assign data you access the dataset container like an array to define an identifier for your new created dataset. The dataset in this example is created from an array, where the keys are used as the identifiers for the data points. Pie charts accept only one dataset, and the data point identifier are used to create the legend. To generate the output the default SVG renderer is used with the default 2d renderer. For the automatic colorization colors are applied from the default Tango palette, which uses colors defined by the Tango Desktop Project: http://tango.freedesktop.org/Tango_Desktop_Project .. image:: img/tutorial_example_01.svg.png :alt: Created pie chart Let's enhance the pie chart and do some custom configuration. .. include:: tutorial_example_02.php :literal: The first step in line 8 is to select another palette, for custom colorization. ezcGraph includes some palettes, in this case we use one with light blue colors. To gain more space for the actual pie chart you can move the legend around, perhaps to the bottom like in line 9. Additionally we use another driver in this example to directly render bitmaps - the GD renderer. For the GD renderer we need to set the path to a font which can be used by this driver. We first set a font for the global font configuration, which is then applied to all font configurations of elements. *Important:* The first time you access a elements font configuration, like in line 16, it will be cloned and won't be affected by changes on the global font configuration anymore. As you can see here, the title element uses it own font, a Post Script Type 1 font in this case, which can be used with ezcGraph, if ext/gd was compiled with --with-t1lib. In line 25 and 26 we change properties of the dataset, which influence how the data will be displayed. You can set properties on single data points, like the highlighted data point in line 25, or for complete datasets, like the changed symbol in line 26. Furthermore we change the label, used for the pie chart, because with the legend we don't need to display the data points name again in the pie chart. Finally advice the renderer to add some shadow and render the image. .. image:: img/tutorial_example_02.png :alt: Improved pie chart So let's try the 3D renderer now. Everything works exactly like before, only that the 3D renderer has some more options. .. include:: tutorial_example_03.php :literal: The result now looks really nice. .. image:: img/tutorial_example_03.svg.png :alt: Three dimensional pie chart There are far more options for the renderer and even for the driver, you can read about in the online documentation. Line charts ----------- Besides pie charts the graph component is able to draw line and bar charts. The process is very similar to creating pie charts, just replace the used chart class with ezcGraphLineChart and you are able to add multiple datasets instead of only one, as for pie charts. .. include:: tutorial_example_04.php :literal: The example again uses another palette, which defines colors for grids and borders for chart elements, so that the legend and the title are surrounded by gray lines. In this example several datasets are added, with their data defined in an array like this:: array( 'Jan 2006' => 965, 'Feb 2006' => 1000, ... ), ... ); ?> Both axis are chart elements like the legend is and have their own configurations options. In this case we set a description label for the axis in line 19. .. image:: img/tutorial_example_04.png :alt: Simple line chart Bar charts ---------- Bar charts work exactly the same way as line charts, they just have another default display type for the datasets and use another default axis label renderer for the x axis. Because of this you can always combine line and bar charts like in the following example: .. include:: tutorial_example_05.php :literal: .. image:: img/tutorial_example_05.png :alt: Combined line and bar chart Mathematical data ----------------- Until now the x axis always was a labeled axis used to display strings in the order the dataset received them. To display statistical or mathematical data it sometimes makes sense to use the date or numeric axis for both, x and y, axis. .. include:: tutorial_example_06.php :literal: From the random data generated in the lines 10 to 13 a polynomials generated in line 17 which interpolates the existing data. The second parameter in the ezcGraphDataSetAveragePolynom constructor defines the maximum order of the used polygon. The interpolation uses the least squares method. In line 20 the x axis is defined as a numeric axis, too, so that the negative values display nicely and the output is like expected for mathematical data. .. image:: img/tutorial_example_06.svg.png :alt: Some random statistical data Background images ----------------- With all drivers except the ming (flash) driver you can set background images with the option to repeat them in some way, like you cando in CSS. .. include:: tutorial_example_09.php :literal: In line 18 we set a background image, and define it's position in line 19. You can use every combination of bottom / center / top with left / middle / right here, and it defaults to center | middle. In line 20 you finally set the type of repetition of the background image. This can be ezcGraph::NO_REPEAT or a combination of ezcGraph::HORIZONTAL and ezcGraph::VERTICAL. In this case we just want a logo to be placed at the bottom right corner of the image. In the SVG the image is in lined using a data URL with the base64 encoded content of the binary image file, so that you do not need to worry about the locations of your referenced images, when you are using the SVG output driver. In the GD driver supersampling is not applied to the images, because the would look blurred, what you certainly do not want for included bitmap images. .. image:: img/tutorial_example_09.svg.png :alt: Pie chart with logo in background Element references ================== Description ----------- Element references describe a mechanism to later modify and reference certain chart elements to add links, menus or other interactive features in your application. The type of the references depend on the driver you use to render chart. The GD driver will return points describing polygons, so that you can generate image maps from the data, while the SVG driver will return the IDs of the according XML elements. The element references are created in the renderer, where the renderer known about the context of the chart element and the driver returns the data the renderer should reference. This way it is also possible to reference legend symbols and text, data labels and of course the actual data elements. SVG example ----------- .. include:: tutorial_example_07.php :literal: After creating a very simple chart like in the first example we start modifying the document using PHPs DOM extension. First we load the document and create a xpath query object on it. The array returned by ezcGraphRenderer::getElementReferences() contains two arrays, one for the legend elements and one for the datasets. The data array itself contains all datasets with all data points, which contain all valid references depending on driver and chart type. In a svg document with a 2d renderer you will receive one ezcGraphCircleSector_[0-9]+ and one ezcGraphTextBox_[0-9]+ element, but this may change with other rendering options. In the loop we now receive the element for the id using xpath, to modify its attributes. $dom->getElementByID() does not work here, because these elements are not indexed by default for non HTML documents. We only modify the style attribute a bit, to change the cursor to a pointer, like expected for links and add a JavaScript onclick event handler to link to specified address. You get a resulting `SVG image`__ where you can click on the chart and legend elements. __ img/tutorial_example_07.svg GD example ---------- In the case of GD we want to generate an image map instead of modifying the generated image. The driver returns polygons described by their edge coordinates, which you can use to generate an image map. .. include:: tutorial_example_08.php :literal: For the sake of a short example we only link the legend elements here. After generating the basic image, we request the element references from the renderer and use the to create the image map starting in line 30. we just iterate over the legend elements, which all may contain more then one polygon. In this case we receive one polygon for the symbol in the legend and another one for the legend text. In the lines 35 to 39 we build the coordinate string image map expects from the coordinate pairs we receive from the gd driver. The coordinate array consists of ezcGraphCoordinate objects, which are a simple structure containing two public properties, the x and the y coordinate as float values. We use this coordinate string create the polygon area elements in line 41. After assigning the image map to the image you got a `linked legend in your generated bitmap`__. __ img/tutorial_example_08.html Drivers ======= There are some driver specific options, you can learn about in the API documentation of each driver, and which are described in this section of the tutorial. SVG driver ---------- The default driver generates SVG_ images, a standardized XML vector graphic format, which most of the modern browsers can display natively, except the Internet Explorer. But even for the Internet Explorer there are several plugins available, from Corel [1]_, or Adobe [2]_, which enable the browser to render SVGs. There are several advantages using the SVG driver. The XML documents can easily be modified later, and compressed effectively. The driver is very fast, and all shapes are displayed exactly and anti aliased. You may define templates, an existing VSG document, where the generated chart is added into a dedicated group, and configure all rendering options of the SVG document. The example below shows such a template created with Inkscape_ and a simple pie chart rendered into this template. .. include:: tutorial_example_10.php :literal: .. image:: img/tutorial_example_10.svg.png :alt: SVG driver example with template .. _SVG: http://www.w3.org/TR/SVG/ .. _Inkscape: http://inkscape.org The only drawback of SVG is, that it is impossible to determine or define the exact width of text strings, so that the driver can only estimate the size of text in the resulting image, which will sometimes fail slightly. .. [1] Abobe SVG plugin: http://www.adobe.com/svg/viewer/install/main.html .. [2] Corel SVG plugin: http://www.corel.com/servlet/Satellite?pagename=CorelCom/Layout&c=Content_C1&cid=1152796555406&lc=en GD driver --------- The GD driver is for now the choice to generate bitmap images. It does support different font types, if available on your PHP installation, like True Type Fonts, using the FreeType 2 library or the native TTF support, and PostScript Type 1 fonts. We use supersampling to enable basic antialiasing in the gd driver, what means, that the image is rendered twice as big with default settings and resized later back to requested size. This is used for all image primitives except texts and images. But there are some drawbacks in the GD library we cannot work around with reasonable effort: - Transparent pie segments look very strange with GD - There is no native support for gradients in GD - Font antialiasing depends on the used font extension. Use the FreeType 2 library if available, what also is the default behavior. There are some special configuration options for the GD driver. You can specify the supersampling rate used, and use different output formats if available with your bundled GD extension, like in the lines 13 to 15 in the following example. .. include:: tutorial_example_11.php :literal: .. image:: img/tutorial_example_11.jpg :alt: GD driver example jpeg Ming/Flash driver ----------------- ezcGraph can use ext/ming to generate flash swf files. This driver only supports Palm Format Fonts (.fdb) and can only handle a very small subset of JPEGs as images for the chart background. On the other hand Flash is a vector graphic format too, so that the images are pretty small and can be compressed effectively. The font size estimation is exact and it support gradients and all types of used shapes. Since ming only supports flash in version 4, it is not possible to use transparent backgrounds. .. include:: tutorial_example_12.php :literal: The ming driver does not have a lot of available options. You need to take care of a valid font file, like you can see in line 10, and you can set the compression rate used by the ming driver to compress the resulting swf. As a result you get a `beautiful flash image`__. __ img/tutorial_example_12.swf More Information ================ For more information, see the ezcGraph API reference. .. Local Variables: mode: rst fill-column: 79 End: vim: et syn=rst tw=79