| ===================== |
| eZ Components - Graph |
| ===================== |
| |
| .. contents:: Table of Contents |
| :depth: 2 |
| |
| Introduction |
| ============ |
| |
| The Graph component 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 customizable from |
| simple two-dimensional charts to beautiful three-dimensional data |
| projections. |
| |
| ezcGraph separates different parts of the graph into chart elements, each |
| representing one part of a graph. Elements include the title, the legend or an |
| axis, and are all independently configurable. This design not only allows you to use |
| different colors or fonts for each chart element, but also to define their |
| position and size. The main chart elements are the same for all chart types. |
| To define overall layouts for graphs, you can use palettes, |
| which specify default colors, symbols, fonts and spacings. |
| |
| Data is provided through ezcGraphDataSet objects, which are normally created |
| from simple arrays. You also can perform statistical operations on data, as you |
| will see later. |
| |
| Class overview |
| ============== |
| |
| This section gives you an overview of the most important classes. |
| |
| ezcGraphChart |
| Line, bar and pie charts extend this abstract class, which represents the |
| chart to be rendered. ezcGraphChart 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 datasets extend this abstract class to provide the data in a general |
| form accessible by the chart. |
| |
| ezcGraphChartElement |
| All chart elements store configuration values that define their layout. An |
| element's layout definition contains background, border, margin, padding and |
| font configuration. ezcGraphChartElement is extended by other classes for the |
| legend, text, background and different axis types. |
| |
| ezcGraphChartElementAxis |
| This class extends ezcGraphChartElement and is the base class for all axes. |
| There are different axis types for different data to be displayed, such as |
| numeric axis, string labeled axis or date axis. |
| |
| ezcGraphAxisLabelRenderer |
| This class defines the rendering algorithm for labels and grids on an axis. |
| The distinction between algorithms is necessary, because bar charts have |
| labels placed directly below the data point, but numerical data in line |
| charts should be placed next to the grid. |
| |
| ezcGraphPalette |
| ezcGraphPalette contains color, font, symbol and spacing definitions to be |
| applied to the entire graph. |
| |
| ezcGraphRenderer |
| This renderer transforms chart primitives, like pie chart segments, legend |
| or data lines, to image primitives. You have the choice between a two- and |
| three-dimensional renderer. |
| |
| ezcGraphDriver |
| This driver renders image primitives to an image. The default driver |
| will output as SVG, but you can also render JPEGs or PNGs using ext/gd. |
| |
| Chart types |
| =========== |
| |
| Pie charts |
| ---------- |
| |
| The following is a simple example of how to create a pie chart using the |
| default driver, palette and renderer. |
| |
| .. include:: tutorial/tutorial_simple_pie.php |
| :literal: |
| |
| Simply create a new chart object, optionally set a title for the chart, |
| assign the data and render it. To assign data, the dataset container |
| is accessed like an array to define an identifier for the 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 identifiers are used to |
| create the legend. To generate the output, the default SVG renderer is used |
| with the default 2D renderer. By default, the colors are applied from the Tango |
| palette, from the Tango Desktop Project: http://tango.freedesktop.org/Tango_Desktop_Project |
| |
| Several dataset and data point presentation styles will be mentioned in this |
| tutorial. One possibility is to highlight a special dataset or point. In line |
| 15, the data point Opera is highlighted; in the case of pie charts, this |
| segment is pulled away from the center. See the renderer options class |
| ezcGraphRendererOptions for more details. |
| |
| .. image:: img/tutorial_simple_pie.svg.png |
| :alt: Sample pie chart |
| |
| Pie chart options |
| ~~~~~~~~~~~~~~~~~ |
| |
| There are several pie chart specific configuration options available. In |
| eZ Components, options are always accessed via public properties. For a full |
| list of all available options, see the documentation for the |
| ezcGraphPieChartOptions class. |
| |
| .. include:: tutorial/tutorial_pie_options.php |
| :literal: |
| |
| In line 16, a sprintf format string is set, which defines how the labels are |
| formatted. Instead of a sprintf format string, you could also set a callback |
| function to do label formatting. |
| |
| In this example, we set a custom sum to force the pie chart to show the |
| complete 100%. The percentThreshold lets the chart collect all data points that |
| have less than the specified percentage to be aggregated in one data point. We |
| also could define an absolute threshold, so that all data below a certain value |
| would be aggregated in one data point. summarizeCaption defines the caption for |
| this aggregated dataset. |
| |
| .. image:: img/tutorial_pie_options.svg.png |
| :alt: Pie chart configuration options |
| |
| Line charts |
| ----------- |
| |
| Line charts are created in the same way as pie charts, but they |
| accept more than one dataset. We are using the default driver, palette and |
| renderer in this example. |
| |
| .. include:: tutorial/tutorial_line_chart.php |
| :literal: |
| |
| There are only two differences compared to the last example. In line 6, we |
| instantiate a ezcGraphLineChart object instead of ezcGraphPieChart and beginning in |
| line 10, we assign multiple datasets from an array we included earlier in the |
| script. The array in the file tutorial_wikipedia_data.php is built like this:: |
| |
| <?php |
| return array( |
| 'English' => array( |
| 'Jan 2006' => 965, |
| 'Feb 2006' => 1000, |
| ... |
| ), |
| ... |
| ); |
| ?> |
| |
| The result is a simple, default line chart. |
| |
| .. image:: img/tutorial_line_chart.svg.png |
| :alt: Simple line chart |
| |
| Bar charts |
| ---------- |
| |
| Bar charts are very similar to line charts. They accept the same datasets and |
| only define another default dataset display type and axis label renderer. |
| |
| .. include:: tutorial/tutorial_bar_chart.php |
| :literal: |
| |
| As you can see in line 6, we only change the chart constructor, and the |
| other default values are applied. |
| |
| .. image:: img/tutorial_bar_chart.svg.png |
| :alt: Simple bar chart |
| |
| Lots of bars |
| ~~~~~~~~~~~~ |
| |
| By default, ezcGraph reduces the amount of steps shown on an axis to about 10 |
| steps. This may cause unexpected results when trying to draw a bar chart |
| with more than 10 bars in one dataset. You may override the behaviour by |
| manually setting the amount of steps on the x axis:: |
| |
| <?php |
| // Initialize graph ... |
| $graph->xAxis->labelCount = count( $chart->data['name'] ); |
| // Output graph ... |
| ?> |
| |
| This works because all datasets implement the Countable interface. If you want |
| to use it for more than one dataset, you could do the following:: |
| |
| <?php |
| // Initialize graph ... |
| $chart->xAxis->labelCount = max( |
| count( $chart->data['name 1'] ), |
| count( $chart->data['name 2'] ) |
| ); |
| // Output graph ... |
| ?> |
| |
| Combining bar and line charts |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| The only difference between bar and line charts is the display type of the |
| dataset and the axis label renderer of the x-axis. You can use one of those |
| constructors and modify your chart to display one or more datasets in |
| either display type. The axis label renderer is described later in this |
| tutorial. |
| |
| .. include:: tutorial/tutorial_bar_line_chart.php |
| :literal: |
| |
| After creating the datasets we modify one of the datasets in line 14 to change |
| the default display type to ezcGraph::LINE. To more prominently display the |
| line, we set one graph option in line 16. Options are accessed like public |
| properties and in this case we set an option for the graph called "fillLines", |
| which indicates what transparency value is used to fill the space underneath |
| the line. |
| |
| .. image:: img/tutorial_bar_line_chart.svg.png |
| :alt: Combined bar and line chart |
| |
| More bar chart options |
| ~~~~~~~~~~~~~~~~~~~~~~ |
| |
| There are some more options available for line and bar charts, which configure |
| the highlighting of datasets. |
| |
| .. include:: tutorial/tutorial_bar_options.php |
| :literal: |
| |
| In line 20, the size of the highlight boxes is specified and lines 22 to |
| 24 change the font configuration for the highlight boxes. Highlighting |
| works in much the same way as for pie charts, but in line and bar charts it |
| makes sense to highlight a complete dataset instead of only one single data |
| point. This is because there is usually more than one dataset in |
| line and bar charts. |
| |
| .. image:: img/tutorial_bar_options.svg.png |
| :alt: Configured highlight in combined line and bar chart |
| |
| Stacked bar charts |
| ~~~~~~~~~~~~~~~~~~ |
| |
| In stacked bar charts, the bars are not drawn next to each other, but |
| aggregated in one bar, and the overall bar consumes the space of the sum of all |
| single bars. |
| |
| .. include:: tutorial/tutorial_stacked_bar_chart.php |
| :literal: |
| |
| To use stacked bar charts, you only need to set the option $stackBars to "true". |
| In the 3D renderer this will cause all bars to be rendered with the symbol |
| ezcGraph::NO_SYMBOL. |
| |
| .. image:: img/tutorial_stacked_bar_chart.svg.png |
| :alt: Bar chart with stacked bars |
| |
| Radar charts |
| ------------ |
| |
| Radar charts are very similar to line charts, but only with one axis, which |
| will be drawn multiple times, rotated around the center point of the chart. |
| |
| .. include:: tutorial/tutorial_radar_chart.php |
| :literal: |
| |
| This again is one of the simplest ways to create a radar chart. Nearly all |
| options described later are also available in radar charts. The basic |
| difference is that an ezcGraphRadarChart object is created in line 6. |
| Radar charts accept multiple datasets, like bar and line charts. In line 14 |
| the first element of the dataset is reassigned as the last element to close |
| the circle. By not reassigning this value, you can get a radar chart where |
| the tails do not join. |
| |
| .. image:: img/tutorial_radar_chart.svg.png |
| :alt: Simple radar chart |
| |
| Controlling radar axis |
| ~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Instead of having an x and a y axis, the radar chart has a main axis, which is |
| the equivalent to the y axis in the other charts, and a rotation axis, the |
| equivalent of the x axis. The steps on the rotation axis define the positions |
| of the rotated main axis. This way you may use all available datasets and |
| axes. |
| |
| .. include:: tutorial/tutorial_complex_radar_chart.php |
| :literal: |
| |
| The settings on the graph will be explained later in the tutorial in detail. |
| In line 11 the type of the rotation axis is set to a numeric axis, which is |
| explained in `Chart elements`_ -> `Axis`_. |
| |
| For line 15 to 23, a dataset is added with some random data. Using this |
| data as a base, a new dataset is built, which calculates a polynomial |
| interpolation function. This is described in more detail in the |
| section `Datasets`_ -> `Average polynomial dataset`_. Lastly, the default colors |
| and symbols from the palette are modified. |
| |
| .. image:: img/tutorial_complex_radar_chart.svg.png |
| :alt: Complex radar chart |
| |
| The resulting radar chart shows how minor steps on the rotation axis are drawn |
| as a grayed out axis and major steps as a regular axis. Note that all |
| types of datasets can be drawn using radar charts. |
| |
| Odometer charts |
| --------------- |
| |
| Odometer charts can display values on one bar with a gradient and markers, |
| providing a nice way for the viewer to detect where a value is in a defined |
| bounding. |
| |
| .. include:: tutorial/tutorial_odometer_chart.php |
| :literal: |
| |
| As you can see from the example, the odometer basically behaves like other |
| chart types. First we create an object of the class ezcGraphOdometerChart, then |
| a title and a dataset is assigned, as per usual. Similar to pie charts, an |
| odometer only accepts one dataset. A legend does not exist for odometers - and |
| you may of course assign an array dataset, containing only one element. |
| |
| .. image:: img/tutorial_odometer_chart.svg.png |
| :alt: Simple odometer |
| |
| The result is a bar, filled with the default gradient, with markers as |
| indicators for the values on the bar. The axis span is automatically calculated |
| for the provided values - you can modify them as usual, but take a look at the |
| next example for this. |
| |
| Custom odometer chart |
| ~~~~~~~~~~~~~~~~~~~~~ |
| |
| When using only one value on an odometer chart, you may wish to manually |
| configure the span on the axis. You can do this as you normally would with |
| any other axis. |
| |
| .. include:: tutorial/tutorial_custom_odometer_chart.php |
| :literal: |
| |
| In this example we only assign one value, so we get one marker on the |
| odometer. The we start using the configuration options for odometers, defined in |
| the ezcGraphOdometerChartOptions class. |
| |
| The start and end color define the colors used for the background gradient. The |
| border options define the border, which is drawn around the chart gradient. |
| After this you can configure the width of the markers, and the space |
| used for the actual odometer. |
| |
| We then configure the minimum and maximum values for the axis and a label for |
| the axis. |
| |
| .. image:: img/tutorial_custom_odometer_chart.svg.png |
| :alt: Custom configured odometer |
| |
| Palettes |
| ======== |
| |
| ezcGraph offers graph palettes to define the overall style properties of |
| chart elements. The style properties are similar to those from CSS: |
| |
| - color |
| - background color |
| - border color |
| - border width |
| - padding |
| - margin |
| - dataset symbols |
| |
| There are several predefined palettes in ezcGraph, but you can |
| easily modify them or create your own palettes. |
| |
| Using a predefined palette |
| -------------------------- |
| |
| You can assign each class extending ezcGraphPalette to the palette |
| property of your graph. You should do this before adding datasets, because the |
| datasets request colors from the palette. If you set the palette after |
| creating the datasets, the datasets will still use the colors from the |
| default palette. |
| |
| .. include:: tutorial/tutorial_user_palette.php |
| :literal: |
| |
| The generated output differs quite a lot from the output using the default |
| Tango palette. The colors for the background, datasets and fonts have been |
| changed. Additionally, the palette sets a color for the major and minor grid, and |
| defines a border width and color for the chart elements. The palette defaults |
| to a sans-serif font and increases the margin between the chart elements. |
| |
| .. image:: img/tutorial_user_palette.svg.png |
| :alt: Combined bar / line chart with non default palette |
| |
| You can find a complete list of the available palettes in the class tree. |
| |
| Modifying a palette |
| ------------------- |
| |
| In the last example, we assigned a palette object to the palette property of |
| the graph. You can of course create and modify the object before assigning it. |
| |
| .. include:: tutorial/tutorial_modified_palette.php |
| :literal: |
| |
| The palette object is created in line 6 and we overwrite some of its |
| properties. An overview on all available properties can be found in the class |
| documentation for the abstract class ezcGraphPalette. In this example we just |
| set two colors for the automatic colorization of the datasets and three |
| symbols for datasets. |
| |
| Since we assign more than two datasets, the first assigned color will be reused |
| for the third dataset. You can see the usage of the symbols in the legend and |
| on the line chart. The line chart displays a symbol for each data point if the |
| symbol is set to something other than ezcGraph::NO_SYMBOL. |
| |
| .. image:: img/tutorial_modified_palette.svg.png |
| :alt: Combined bar / line chart with modified palette |
| |
| Creating a custom palette |
| ------------------------- |
| |
| To style the graphs to fit a custom look, such as a corporate identity, the |
| easiest way is to create your own palette. |
| To create a custom palette you can either extend one of the predefined palettes and |
| overwrite their properties or extend the abstract palette class. |
| |
| .. include:: tutorial/tutorial_custom_palette_palette.php |
| :literal: |
| |
| Each undefined color will default to a transparent white. As you |
| can see in the example definition, you can define alpha values beside the |
| normal RGB values for the colors. After creating a custom palette, you can use |
| it like any predefined palette, as previously explained. |
| |
| .. include:: tutorial/tutorial_custom_palette.php |
| :literal: |
| |
| The example now uses the custom palette to format the output. You can include |
| palettes using your application's autoload mechanism or require them as |
| shown in the example above. |
| |
| .. image:: img/tutorial_custom_palette.svg.png |
| :alt: Combined bar / line chart with custom palette |
| |
| Chart elements |
| ============== |
| |
| The chart elements all extend ezcGraphChartElement. Each of the elements can be |
| configured independently. A default chart consists of the following elements: |
| |
| - title |
| - background |
| - legend |
| - xAxis |
| - yAxis |
| |
| The palette defines the default formatting of the elements. Not only can you set |
| foreground and background colors for all the elements, but you can also |
| define their position in the chart or prevent them from being rendered at |
| all. |
| |
| Font configuration |
| ------------------ |
| |
| We try to fulfill two goals regarding font configuration. First, there should |
| be a single point to configure the fonts used for the text areas in the chart. |
| On the other hand, it should be possible to configure the fonts independently |
| for each chart element. |
| |
| The solution is that you can modify the global font configuration by |
| accessing $graph->options->font. This takes effect on all chart elements |
| unless you intentionally access the font configuration of an individual chart |
| element. The following example shows how this works. |
| |
| .. include:: tutorial/tutorial_chart_font_configuration.php |
| :literal: |
| |
| The output of the example shows, that all texts are using a serif font, while |
| the title still stays with the default sans-serif font. |
| |
| .. image:: img/tutorial_chart_font_configuration.svg.png |
| :alt: Font configuration in pie chart |
| |
| The chart title |
| --------------- |
| |
| The chart title element will only be rendered if you manually assign a title. |
| It can be placed on top or at the bottom of the chart. |
| |
| .. include:: tutorial/tutorial_chart_title.php |
| :literal: |
| |
| The chart title is the simplest element. In line 9, we change the global font |
| configuration to use a serif font. In the SVG renderer, only the font name is |
| relevant, because it is up to the client to actually render the bitmap from the |
| defined vector definitions. |
| |
| In line 11, we access the font configuration of the title element and change it |
| back to use a sans-serif font. From now on, no change on the global font |
| configuration will affect the title's font configuration. In line 14, we set a |
| maximum font size, which now only affects the legend and the pie chart |
| captions. |
| |
| Aside from the font configuration, we set an option for all chart |
| elements in line 11 - the background color of the current element. This |
| results in a gray background for the title element only. |
| |
| .. image:: img/tutorial_chart_title.svg.png |
| :alt: Font and title configuration in pie chart |
| |
| The background element |
| ---------------------- |
| |
| With all drivers except the Ming (Flash) driver, you can set background images |
| with the option to repeat them in the same way as in CSS definitions. |
| |
| .. include:: tutorial/tutorial_chart_background.php |
| :literal: |
| |
| In line 17, we set a background image, and define its position in line 18. You |
| can use every combination of bottom / center / top with left / middle / right |
| here, and it defaults to center | middle. In line 19, you 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. |
| |
| With the SVG driver, the image is inlined using a data URL with the base64 |
| encoded content of the binary image file. Using this driver, you do not need to |
| worry about the locations of your referenced images. |
| |
| With the GD driver, super sampling is not applied to the images, as this would |
| make them blurry. |
| |
| .. image:: img/tutorial_chart_background.svg.png |
| :alt: Pie chart with logo in background |
| |
| Of course, you could also apply the following settings to the background |
| element: background color, borders, margins and padding. |
| |
| The legend |
| ---------- |
| |
| The legend is shown by default and is automatically generated from the assigned |
| data. If you want to disable the legend, you can do this by setting |
| it to "false" (line 9). |
| |
| .. include:: tutorial/tutorial_chart_legend.php |
| :literal: |
| |
| .. image:: img/tutorial_chart_legend.svg.png |
| :alt: Pie chart without legend |
| |
| Legend configuration options |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Other than hiding the legend, you can also place it at the bottom, left or top |
| in the chart; you can assign a title for the legend and change the symbol |
| sizes; you can additionally set the legend size. |
| |
| .. include:: tutorial/tutorial_legend_options.php |
| :literal: |
| |
| To place the legend at another position on the graph, set the position |
| property of the legend, as shown in line 17. If the legend is placed at the top or |
| bottom, it will automatically use a landscape format. The space consumed by the |
| legend is configured by the landscapeSize setting for landscape-oriented legends |
| and the portraitSize setting otherwise. The assigned value is the percent |
| portion of space taken up by the legend, relative to the size of the chart. The |
| legend only displays a title if you manually set it, as shown in line 19. |
| |
| .. image:: img/tutorial_legend_options.svg.png |
| :alt: Legend configuration example |
| |
| Axis |
| ---- |
| |
| The axis defines the unit scale in line and bar charts. There are always two |
| axes - the x-axis and the y-axis, whose ranges are automatically |
| received from the datasets and scaled to display appropriate values. |
| |
| There are different types of values to display for both the x-axis and the |
| y-axis. ezcGraph supports different axis types for different types of data. For |
| normal string keys, the standard labeled axis is usually the right choice. The |
| numeric axis is predestined to display numeric data, and the date time axis is |
| for data associated with dates or times. All of the axis types can be assigned |
| to either axis. |
| |
| Labeled axes |
| ~~~~~~~~~~~~ |
| |
| The labeled axis is default for the x-axis in both bar and line charts. It |
| is intended to display string labels of datasets and uses the centered label |
| renderer by default. You saw it in all the earlier examples with bar |
| and line charts, but it can be used for both axes as well. |
| |
| .. include:: tutorial/tutorial_axis_labeled.php |
| :literal: |
| |
| You could argue whether such a chart is really useful - but it works. Instead of |
| using numeric values, colors are assigned when creating the dataset. The |
| labeled axis uses the values in the order they are assigned. Line 11 is |
| the first time we actually configure the axis label renderer. The axis label |
| renderer describes how the labels are placed on the axis - the labeled axis |
| uses the centered axis label renderer by default, which places the labels |
| centered next to the steps on the axis. The setting in line 11 forces the |
| renderer to show the zero value, even though it interferes with the axis. |
| |
| .. image:: img/tutorial_axis_labeled.svg.png |
| :alt: Two labeled axes |
| |
| Numeric axis |
| ~~~~~~~~~~~~ |
| |
| The numeric axis is the default for the y-axis. It displays |
| numeric data and automatically determines appropriate scaling for the assigned |
| values. However, you can also configure all scaling parameters manually. |
| |
| .. include:: tutorial/tutorial_axis_numeric.php |
| :literal: |
| |
| In this example, we force both axes to be numeric axes in line 10. In lines |
| 12 to 15, we manually set the scaling options for the x-axis. We do not set a |
| minorStep size here, so it will be automatically calculated from the other |
| values, as will the settings for the y-axis. Then, we create some random data |
| and create two datasets from it as usual. |
| |
| .. image:: img/tutorial_axis_numeric.svg.png |
| :alt: Two numeric axes with random data |
| |
| The example shows one advantage of a numeric axis over a labeled axis for numeric |
| data. The axes are moved away from the chart's border to display the negative |
| values below and left of the axis. |
| |
| Date time axis |
| ~~~~~~~~~~~~~~ |
| |
| Previously in this tutorial, we used a labeled axis for date time data on the |
| x-axis in the Wikipedia examples. This works fine for evenly-distributed |
| time spans. For other data, you should use the date time axis. |
| |
| .. include:: tutorial/tutorial_axis_datetime.php |
| :literal: |
| |
| You can use timestamps or date time strings as dataset keys. The strings will |
| be converted using PHP's strtotime() function. |
| |
| .. image:: img/tutorial_axis_datetime.svg.png |
| :alt: Date axis example |
| |
| Axis label renderer |
| ~~~~~~~~~~~~~~~~~~~ |
| |
| As mentioned earlier in this tutorial, the axis label renderer defines where a |
| label is drawn relative to the step on the axis. You already saw examples |
| for all available axis label renderers, but here is an overview: |
| |
| - ezcGraphAxisExactLabelRenderer |
| |
| This is the default renderer for the numeric axis. The labels are drawn |
| directly below the axis step. This may look strange sometimes, because it |
| is not always possible to draw all labels of one axis on one side |
| of the step; the last or first label would exceed the available |
| space for the axis, and be rendered on the other side. |
| |
| - ezcGraphAxisCenteredLabelRenderer |
| |
| This renderer is the default for the labeled axis in line charts and draws the |
| label centered next to the step. Therefore, this renderer omits the label for |
| the initial step on the axis (0, 0) by default. However, this can be forced |
| as shown in the example in `Axis`_ -> `Labeled axes`_. The label is omitted |
| because it would interfere with the axis or the labels of the other axis, and |
| thus be difficult to read. |
| |
| - ezcGraphAxisBoxedLabelRenderer |
| |
| This is the default renderer for the labeled axis in bar charts. The steps |
| on the axis and the grid are not drawn at the position of the label, but |
| between two labels. This helps to recognize which bars belong together. |
| Labels are rendered centered between two steps on the axis. |
| |
| Rotated labels on axis |
| ~~~~~~~~~~~~~~~~~~~~~~ |
| |
| There is one more new axis label renderer since version 1.1 of ezcGraph - |
| ezcGraphAxisRotatedLabelRenderer, which enables you to render rotated labels on |
| an axis. |
| |
| .. include:: tutorial/tutorial_rotated_labels.php |
| :literal: |
| |
| In line 9, a custom renderer is defined for the labeled x axis. You can |
| assign custom axis label renderers on the property $axisLabelRenderer for |
| ezcGraphChartElementAxis objects. |
| |
| The renderer used in this example has custom properties like the rotation of |
| the labels, which is set in degrees, while the rotation direction depends on |
| the direction of the axis. |
| |
| It makes sense to define more vertical space below the axis for the |
| rotated labels as done in line 11 of the above example. |
| |
| .. image:: img/tutorial_rotated_labels.svg.png |
| :alt: Date axis example |
| |
| The results conatins rotated labels, which enables you to pack a lot more |
| labels on one axis. |
| |
| Additional axis & markers |
| ------------------------- |
| |
| Aside from the x axis and the y axis, you can add additional axes and markers to one |
| chart. You can also assign these additional axes to datasets, so that some |
| datasets use different axes than others. |
| |
| Add markers to chart |
| ~~~~~~~~~~~~~~~~~~~~ |
| |
| First, add some markers, which only get a label and reside at some |
| user defined position, to a chart. You may use them to display data boundings |
| on the y axis, or important values on the x axis. |
| |
| .. include:: tutorial/tutorial_line_chart_markers.php |
| :literal: |
| |
| You can see a standard line chart, like in the examples before, using the |
| Wikipedia datasets. In line 15 we add another axis, and configure this one in |
| the following lines. The position of an axis defines its origin. The |
| position ezcGraph::LEFT means that the axis starts at the left side of the |
| graph. You can also use ezcGraph::RIGHT to make the axis start on the right. |
| |
| The position of the axis may be defined by a float value, which defines the |
| fractional position in the chart, calculated from the top left position. After |
| this we also define a label for the axis. |
| |
| .. image:: img/tutorial_line_chart_markers.svg.png |
| :alt: Line chart with marker |
| |
| Additional axes |
| ~~~~~~~~~~~~~~~ |
| |
| As previously noted, you can not only add additional axis to one chart, but you can |
| also assign datasets to use one of these new axes. This will cause the |
| axis to calculate its values depending on the assigned datasets and the data to |
| orientate at the new axis. |
| |
| The new axis may also be of a completely different type than the original chart |
| axis. |
| |
| .. include:: tutorial/tutorial_line_chart_additional_axis.php |
| :literal: |
| |
| In this chart we use a different axis, positioned at the very end of the chart, |
| for the Norwegian Wikipedia data. Due to the different scaling for the English |
| and Norwegian data, you can easily see that the development of articles is very |
| similar, on a completely different level. |
| |
| To use the axis with some dataset, you need to assign the newly created axis to |
| one of the existing axis properties and to the dataset. In this case we use the $yAxis |
| property. |
| |
| .. image:: img/tutorial_line_chart_additional_axis.svg.png |
| :alt: Line chart with additional axis |
| |
| Datasets |
| ======== |
| |
| Datasets receive user data and provide an interface for |
| ezcGraph to access this data. |
| |
| Array data |
| ---------- |
| |
| The array dataset was used for all examples until now, because it is the |
| simplest way to provide data for ezcGraph. |
| |
| Average polynomial dataset |
| -------------------------- |
| |
| The average polynomial dataset uses an existing dataset with numeric keys and |
| builds a polynomial that interpolates the data points in the given dataset using the |
| least squares algorithm. |
| |
| .. include:: tutorial/tutorial_dataset_average.php |
| :literal: |
| |
| Here we use two numeric axes, because we only display numeric data in this |
| example. First, we create a normal array dataset from some randomly generated |
| data in line 14. We assign this dataset to the chart to see how well the |
| polynomial fits the random data points. |
| |
| In line 20, we create a ezcGraphDataSetAveragePolynom dataset from the random |
| data with a maximum polynomial degree of 3 (which is also the default |
| value). You can directly access the polynomial when we add the dataset to the |
| graph. The string representation of the polynomial itself is also used as the |
| name of the dataset. |
| |
| .. image:: img/tutorial_dataset_average.svg.png |
| :alt: Average polynomial example |
| |
| For the computation of the polynomial, an equation has to be solved where the |
| size of the matrix is equal to the point count of the used dataset. Be |
| careful with datasets with large point counts. This could mean that |
| ezcGraph will consume a lot of memory and processing power. |
| |
| Numeric dataset |
| --------------- |
| |
| Numeric datasets are used to represent mathematical functions in your chart. |
| You can use callbacks to PHP functions, or your own functions or methods to |
| define the mathematical function used to create the dataset. |
| |
| .. include:: tutorial/tutorial_dataset_numeric.php |
| :literal: |
| |
| The numeric dataset constructor receives the start and end values for |
| the function's input and the function itself using PHP's `callback datatype`__. In |
| this example we create a function on runtime using create_function(), which |
| returns the name of the created function (which is a valid callback). The |
| code of the created function in line 16 returns sine values for the input in |
| degrees. |
| |
| __ http://php.net/manual/en/language.pseudo-types.php |
| |
| The resolution set in line 20 defines the number of steps used to interpolate |
| the function in your graph. You should not use a number bigger than the width |
| of your chart. |
| |
| .. image:: img/tutorial_dataset_numeric.svg.png |
| :alt: Example numeric dataset |
| |
| Renderer |
| ======== |
| |
| The renderer transforms chart primitives into image primitives. For example, a |
| pie segment including labels, highlighting and so on will be transformed |
| into some text strings, circle sectors and symbols to link the text to the |
| corresponding circle sector. |
| |
| ezcGraph comes with the default 2D renderer used in all of the above examples |
| and a 3D renderer that renders the chart elements in a pseudo 3D isometric |
| manner. |
| |
| 2D renderer |
| ----------- |
| |
| All examples until now used the default 2D renderer. There are several |
| renderer-specific options that have not yet been shown. |
| |
| Bar chart rendering options |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| All the options specific to bar charts are available for all |
| current renderers. |
| |
| .. include:: tutorial/tutorial_bar_chart_options.php |
| :literal: |
| |
| As the 2D renderer is the default renderer, we do not need to specify it. In |
| lines 28 and 29, we configure the width used for the bars. The |
| option barMargin defines the distance between the sets of bars associated to |
| one value. The barPadding setting in line 29 defines the distance between bars in one |
| block. |
| |
| The option dataBorder in line 31 is available for all chart types in all |
| renderers and defines the transparency used to draw darkened borders around |
| bars or pie segments. In this case, we do not draw any borders. |
| |
| .. image:: img/tutorial_bar_chart_options.svg.png |
| :alt: Bar chart rendering options |
| |
| Pie chart rendering options |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| .. include:: tutorial/tutorial_pie_chart_options.php |
| :literal: |
| |
| One of the pie chart specific options is moveOut in line 21, which defines how |
| much space in the pie chart is used to move the pie chart segments out from the |
| center when highlighted. The pieChartOffset setting in line 23 defines the |
| initial angle for the pie chart segments, which enables you to rotate the pie chart. |
| |
| In lines 25 to 27, a gleam on the pie chart is defined, with a transparency |
| value in line 25 (which disables the gleam when set to 0), a color in line 26 |
| and the distance from the outer border of the pie chart in line 27. |
| |
| In line 29 and 30, a shadow with custom offset and color is added to the pie |
| chart. |
| |
| .. image:: img/tutorial_pie_chart_options.svg.png |
| :alt: Pie chart rendering options |
| |
| Pimp my chart |
| ~~~~~~~~~~~~~ |
| |
| .. include:: tutorial/tutorial_pie_chart_pimped.php |
| :literal: |
| |
| Aside from the gleam added in the last example, you can define a |
| gleam for the legend symbols. In line 32, the transparency of the gleam is |
| defined, followed by the size of the gleam. The gleam works for all symbol |
| types except the circle, where a gleam is not appropriate. The size setting |
| defines the size of the gleam as a percentage of the symbol size. In the last step in |
| line 34, the gleam color is defined. |
| |
| .. image:: img/tutorial_pie_chart_pimped.svg.png |
| :alt: Pimped 2D pie chart |
| |
| 3D renderer |
| ----------- |
| |
| The three-dimensional renderer can render all charts that the 2D |
| renderer can do, and uses all the drivers that the 2D renderer uses. The only |
| difference is that it generates isometric three-dimensional views on the data |
| instead of simple two-dimensional views. |
| |
| .. include:: tutorial/tutorial_renderer_3d.php |
| :literal: |
| |
| This examples uses the same code as the first example, except for the renderer |
| in line 17. You can use the 3D renderer with all of the above examples by |
| adding this single line. |
| |
| .. image:: img/tutorial_renderer_3d.svg.png |
| :alt: Simple 3d pie chart |
| |
| 3D pie charts |
| ~~~~~~~~~~~~~ |
| |
| The options in the 2D renderer example still work, and we extend the example |
| with some 3D renderer-specific options. |
| |
| .. include:: tutorial/tutorial_pie_chart_3d.php |
| :literal: |
| |
| The pieChartGleamBorder option was removed, because it looks a bit strange on |
| 3D pie charts, although it would still work. In lines 37 and 38, there are |
| two new options, which configure the 3D effect of the pie chart. The first one |
| defines the height of the pie and the second one defines the percent shrinkage |
| compared to the maximum possible vertical size of the pie chart. |
| |
| .. image:: img/tutorial_pie_chart_3d.svg.png |
| :alt: Pimped 3D pie chart |
| |
| 3D bar charts |
| ~~~~~~~~~~~~~ |
| |
| 3D bar charts use the symbol of the dataset as the basic shape for the |
| rendered bar, so that you can render cylinders or cuboids in your charts. |
| |
| .. include:: tutorial/tutorial_bar_chart_3d.php |
| :literal: |
| |
| The symbols for these examples are set as described earlier in this tutorial. |
| Two single options are set to improve the displayed image. legendSymbolGleam is |
| activated with the default color, and barChartGleam is activated to get more |
| beautiful bars. You could optionally darken the tops and sides of the bars using the |
| options barDarkenSide and barDarkenTop. |
| |
| .. image:: img/tutorial_bar_chart_3d.svg.png |
| :alt: Pimped 3D bar chart |
| |
| 3D line charts |
| ~~~~~~~~~~~~~~ |
| |
| The line chart example with the 3D renderer is again quite simple. It reuses the |
| example with the statistical data and the approximated polygon. |
| |
| .. include:: tutorial/tutorial_line_chart_3d.php |
| :literal: |
| |
| Again, the only thing that has changed is the use of the 3D renderer and the |
| fillLines option (to show that it works for 3D charts as well). |
| |
| .. image:: img/tutorial_line_chart_3d.svg.png |
| :alt: 3D line chart example |
| |
| Drivers |
| ======= |
| |
| The driver gets the image primitives from the renderer and creates the final |
| image. Different drivers can be used depending on |
| the available extensions and the desired output format. |
| |
| There are some driver-specific options described below. You can also learn |
| about them in the API documentation for each driver. |
| |
| SVG driver |
| ---------- |
| |
| The default driver generates an SVG_ image, a standardized XML vector graphic |
| format, which most of the modern browsers can display natively, except for |
| Internet Explorer. Even with Internet Explorer, there are several |
| plugins available from Corel [1]_, or Adobe [2]_, which enable the browser to |
| render SVGs. There are several advantages in 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 can |
| define templates, using an existing SVG document, where the generated chart is |
| added to a dedicated group; you can then configure all rendering options of the SVG |
| document. The example below shows such a template created with Inkscape_ and a |
| simple pie chart rendered using this template. |
| |
| .. include:: tutorial/tutorial_driver_svg.php |
| :literal: |
| |
| .. image:: img/tutorial_driver_svg.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. As a result, the driver can only estimate the size of |
| text in the resulting image, which will sometimes fail slightly. Since the |
| 1.3 (2008.1) release you can work around this issue, by using the `Glyph support`_. |
| |
| .. [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 |
| |
| Glyph support |
| ~~~~~~~~~~~~~ |
| |
| Since version 1.3 (2008.1) you may set a SVG font to be used by the SVG driver, |
| which will result in exact text width estimation using glyphs for the chracters |
| in texts. SVG fonts may be created from TTF fonts using the ttf2svg command |
| available in the `apache batik`__ package. |
| |
| __ http://xml.apache.org/batik/ |
| |
| Embedding SVG in HTML |
| ~~~~~~~~~~~~~~~~~~~~~ |
| |
| If you want to embed SVGs in HTML there are several ways to do so. With XHTML |
| you may inline the content of the SVG in your HTML, as both are just XML. You |
| need to keep correct namespacing in mind here. Opera and Firefox will support |
| this technique. |
| |
| Another way to reference SVGs in your HTML markup, is to use the object |
| element like following example shows. |
| |
| :: |
| |
| <object data="path/to/image.svg" type="image/svg+xml"> |
| You need a browser capeable of SVG to display this image. |
| </object> |
| |
| You can optionally specify the width and height as attributes in the options |
| element. With this standards-conforming method, the drawback is that |
| Microsoft Internet Explorer does not support this. With browsers from the |
| Internet Explorer series, you can use the proprietary embed element. |
| |
| :: |
| |
| <embed src="path/to/image.svg"></embed> |
| |
| You cannot specify an alternative text here, and this will not work with |
| Opera and Firefox. If you need to support all browsers, you can use one of the |
| common switches to distinguish between browsers. |
| |
| :: |
| |
| <!--[if IE]> |
| <embed ... /> |
| <![endif]--> |
| <![if !IE]--> |
| <object ... /> |
| <![endif]--> |
| |
| Another alternative for embedding SVGs in your HTML would be to use iframes. |
| |
| GD driver |
| --------- |
| |
| The GD driver is one of the choices for generating bitmap images. It supports |
| different font types, if available in your PHP installation, like True Type |
| Fonts (using the FreeType 2 library or native TTF support) and PostScript Type |
| 1 fonts. We use super sampling to enable basic anti aliasing in the GD driver, |
| where the image is rendered twice as big and resized back to the requested |
| size. This is used for all image primitives except text and images. |
| |
| There are some drawbacks in the GD library that we have not been able to |
| overcome: |
| |
| - Transparent pie segments look very strange with GD |
| - There is no native support for gradients in GD |
| - Font anti aliasing depends on the font extension. Use the FreeType 2 |
| library if available, which is the default behavior. |
| |
| There are some special configuration options for the GD driver. You can |
| specify the super sampling rate used, and use different output formats (if |
| available with your bundled GD extension) as shown in lines 13 to 15 in the |
| following example. |
| |
| .. include:: tutorial/tutorial_driver_gd.php |
| :literal: |
| |
| .. image:: img/tutorial_driver_gd.jpg |
| :alt: GD driver example jpeg |
| |
| Cairo driver |
| ------------ |
| |
| Cairo is a software library used to provide a vector graphics-based, |
| device-independent API for software developers. It is designed to provide |
| primitives for 2-dimensional drawing across a number of different |
| backends. Cairo is designed to use hardware acceleration when available. |
| |
| .. Wikipedia |
| |
| Using the PHP extension `pecl/cairo_wrapper`__ and the driver class |
| ezcGraphCairoDriver you can also create bitmaps with a far better quality then |
| the GD driver, supporting all features required by the graph components with |
| high quality anti aliasing. |
| |
| .. include:: tutorial/tutorial_driver_cairo.php |
| :literal: |
| |
| .. image:: img/tutorial_driver_cairo.jpg |
| :alt: Cairo driver example jpeg |
| |
| __ http://pecl.php.net/package/cairo_wrapper |
| |
| 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, so the images are rather small and can be compressed |
| effectively. The font size estimation is exact and it support gradients and |
| all of the used shapes. Ming does not support the generation of swf files using |
| transparent backgrounds. |
| |
| .. include:: tutorial/tutorial_driver_flash.php |
| :literal: |
| |
| The Ming driver does not have a lot of available options. You need to use a |
| valid font file, as in line 10, and you can set the |
| compression rate used by the Ming driver to compress the resulting swf. The |
| result is a `beautiful Flash image`__. |
| |
| __ img/tutorial_driver_flash.swf |
| |
| Element references |
| ================== |
| |
| Description |
| ----------- |
| |
| Element references describe a mechanism to 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 |
| charts. 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 |
| XML elements. |
| |
| Element references are created in the renderer. This way it is also possible to |
| reference legend symbols and text, data labels and of course the actual data |
| elements. |
| |
| In ezcGraph version 1.1 and later, you can define URLs for datasets and data |
| points that will be used when linking the elements. You now can use the function |
| provided in ezcGraphTools to create the image maps and add links into SVG |
| images. |
| |
| SVG example |
| ----------- |
| |
| .. include:: tutorial/tutorial_reference_svg.php |
| :literal: |
| |
| In ezcGraph version 1.1 and later, you can optionally set a custom cursor type used by the |
| browser to indicate that you can click on a surface. The cursor defaults to a |
| pointer normally used for links. You also need to assign |
| URLs to the datasets or data points, as in the lines 17 and 18, and then |
| call ezcGraphTools::linkSvgElements (line 23) to modify your SVG. The |
| result will be a clickable `SVG image`__. |
| |
| __ img/tutorial_reference_svg.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/tutorial_reference_gd.php |
| :literal: |
| |
| In line 20 we associate a URL to the complete dataset and in line 21 another |
| URL for the Mozilla data point only. Those URLs will be used to create the |
| image map in line 31. In the second parameter on line 31 we can |
| provide a name for the image map, which should be used to associate the image |
| map to the image in line 37. The result is a `linked legend and linked |
| pie chart in your generated bitmap`__. |
| |
| __ img/tutorial_reference_gd.html |
| |
| SVG to bitmap conversion |
| ------------------------ |
| |
| If you want to benefit from the more beautiful SVG output you can convert the |
| vector graphics to a bitmap format, like PNG or JPEG, on the server side. |
| There are several tools than can do this, but for each you need to be able |
| to execute commands using the exec() function family. |
| |
| - librsvg |
| Small memory footprint and advanced SVG support, including filters (which |
| are not used by ezcGraph, though). Example command to convert an image: |
| |
| :: |
| |
| rsvg input.svg output.png |
| |
| - ImageMagick |
| Installed on most servers, but has some issues with transparent |
| backgrounds in SVG documents. Example command with ImageMagick: |
| |
| :: |
| |
| convert -background none input.svg output.png |
| |
| - Inkscape |
| Not available on most servers, but perfect for modifying SVG documents on |
| Unix and Windows. Requires X to install, but can be run on CLI, too: |
| |
| :: |
| |
| inkscape input.svg -e output.png |
| |
| All three converters can also export to PDF or postscript, and resize the |
| document if desired. For further details, please read the documentation of the |
| respective tool. |
| |
| Direct output |
| ============= |
| |
| By default, a graph is rendered to a file, as you normally want to cache |
| generated images. ezcGraph also provides a method for the direct output of |
| generated charts. Use this with caution. |
| |
| The ezcGraph::renderToOutput() method sends the correct Content-Type header |
| for the selected output driver and writes the chart's image data directly to |
| output. Do not output anything before using this method. |
| |
| .. include:: tutorial/tutorial_output.php |
| :literal: |
| |
| This example renders the first graph of this tutorial. |
| |
| More information |
| ================ |
| |
| For more information, see the ezcGraph API documentation. |
| |
| |
| .. |
| Local Variables: |
| mode: rst |
| fill-column: 79 |
| End: |
| vim: et syn=rst tw=79 |