Issue #2247551 by eneko1907: Clean examples.
[project/charts.git] / README.txt
1 Charts
2 ======
3
4 Charts module provides a unified format to build any kind of chart with any
5 chart provider.
6
7 Each chart solution found on internet, like Google Charts and Highcharts,
8 have a specific data scheme. Its very hard and even impossible to build a unique
9 chart data that would be used in more that one chart provider. Or users get
10 binded to a solution forever or they have to rewrite all exported data again.
11
12 Thats why Charts is so great. It uses a standard data scheme do describe charts
13 data and thru filters, it converts automatically to each solution. You might
14 change to another solution at anytime.
15
16 The Chart schema is very similiar to Drupal's Form API schema.
17
18 Chart Providers
19 ---------------
20
21 Out of the Box, you will be able to use 2 chart solutions. Which one of them
22 has particular advantages and disadvantages.
23
24 * Google Charts: This library does not require any external downloads. It
25   generates interactive charts using SVG and VML.
26
27 * Highcharts: This library is one of the premier solutions for generating
28   charts. Although it is very powerful and aesthetically pleasing with smooth
29   animations, it requires a commercial license. It's free for non-commercial
30   use. See http://www.highcharts.com
31
32 Installing Highcharts
33 ---------------------
34
35 If you decide to use the Highcharts library, you'll need to first install the
36 Libraries module for Drupal: https://drupal.org/project/libraries
37
38 Then you'll need to download Highcharts and place it in sites/all/libraries
39 directory. The highcharts.js file should be located at:
40 sites/all/libraries/highcharts/js/highcharts.js. You will also need to remove a
41 directory called "exporting-server" within the Highcharts download. This
42 directory contains sample code for exporting charts that may compromise the
43 security of your site. The module will throw an error if this directory is left
44 in place.
45
46 Creating Charts in the UI
47 -------------------------
48
49 This module provides a configuration page at admin/config/content/charts. You
50 may set site-wide defaults on this page (for example set the default color
51 scheme).
52
53 In order to actuall create a chart through the UI, you'll need to use Views
54 module.
55
56 - Create a new view:
57   Visit admin/structure/views/add and select the display format of "Chart" for
58   your new page or block.
59
60 - Enable aggregation on the view:
61   In order to display data, most of the time you'll need enable aggregation on
62   the view. Under the right column of settings, there is a section for
63   "Use aggregation". Enable this setting.
64
65 - Add a label field:
66   Under the "Fields" section, add a field you would like to be used as labels
67   along one axis of the chart (or slices of the pie). In the "Aggregation type"
68   setting, set it to "Group results together".
69
70 - Add data fields:
71   Now a second field which will be used to determine the data values. Usually
72   this will be an ID field, such as NID or CID. The label you give this field
73   will be used in the chart's legend to represent this series. After adding the
74   field, set the "Aggregation type" for this field to "Count". Do this again for
75   each different quantity you would like to chart. Note that some charts
76   (e.g. Pie) only support a single data column.
77
78 - Configure the chart display:
79   Click on the "Settings" link in the Format section to configure the chart.
80   Select your chart type. Some options may not be available to all chart types
81   and will be adjusted based on the type selected. Because no live preview is
82   available in Charts, you may need to open a saved version of the view in a
83   different window to see the impact of your changes.
84
85 - Save your view.
86
87 Tip: You may find it easier to start with a "Table" display and convert it to a
88 chart display after setting up the data. It can be easier to visualize what
89 the result of the chart will be if it's been laid out in a table first.
90
91 Creating Multiple Series and Combo Charts in the UI
92 ---------------------------------------------------
93
94 When using Views to build your charts, you may find it difficult to retrieve
95 more than a single set of data generated by a COUNT() query. For example if you
96 wanted to retrieve the age of all your site users, but display "Male" and
97 "Female" values in a column chart at the same time, constructing the underlying
98 table of data is quite difficult.
99
100 To solve this problem, you can combine multiple charts on top of each other. The
101 "parent" chart provides the global information, such as the height, width,
102 title, and other properties. Charts that are "children" provide only data and
103 (optionally) a secondary axis. After you've assembled the first series of data
104 in your chart according to the instructions in the "Creating Charts in the UI"
105 section, add a new display to the same view of the type "Chart Add-on". The
106 "Chart Add-on" type is added the same way you would add a new Page or Block
107 display, from the "+ Add" menu at the top of the view configuration.
108
109 After this new display has been added, find the setting for "Combine with parent
110 chart" and change this value to point at the parent chart you have already
111 assembled. Then adjust the settings for the child chart to pull in different
112 data (often by overriding the filter settings). Now you can go back to your
113 parent display, and see that the results from the child chart have been
114 merged into the results from the parent chart. You can even use this approach
115 to combine different types of charts, such as a line chart over the top of
116 a column chart. Note that not all chart types can be combined together and
117 invalid combinations may cause your chart to throw errors.
118
119 Create Charts through the API
120 -----------------------------
121
122 Charts module includes an extensive API for creating charts through code. See
123 the charts.api.php file included with this module for documentation.
124
125 Support
126 -------
127
128 For bug reports and feature requests please use the Drupal.org issue tracker:
129 http://drupal.org/project/issues/charts.