e2pdf / vendors / svggraph / README.txt

README.txt in E2Pdf – Export Pdf Tool for WordPress 1.32.53, at vendors/svggraph/README.txt

335 lines 11.2 KB

Raw Download Zip

1	SVGGraph Library version 3.20
2	=============================
3
4	This library provides PHP classes and functions for easily creating SVG
5	graphs from data. Version 3.0 of SVGGraph requires at least PHP 5.4 - if
6	you must use an earlier version of PHP then use the SVGGraph 2.x version.
7
8	Here is a basic example:
9	$graph = new Goat1000\SVGGraph\SVGGraph(640, 480);
10	$graph->colours(['red', 'green', 'blue']);
11	$graph->values(['Tom' => 100, 'Dick' => 200, 'Harry' => 150]);
12	$graph->render('BarGraph');
13
14	Full documentation is available at http://www.goat1000.com/
15
16	Graph types
17	===========
18	At the moment these types of graph are supported by SVGGraph:
19
20	EmptyGraph - en empty document that can be used to add shapes or labels;
21
22	BarGraph - vertical bars, optionally hyperlinked;
23
24	LineGraph - a line joining the data points, with optionally hyperlinked
25	markers at the data points;
26
27	PieGraph - a pie chart, with optionally hyperlinked slices and option
28	to fade labels in/out when the pointer enters/leaves a
29	slice;
30
31	Bar3DGraph - a 3D-looking version of the BarGraph type;
32
33	Pie3DGraph - a 3D-looking version of the PieGraph type;
34
35	ScatterGraph - markers drawn at arbitrary horizontal and vertical points;
36
37	MultiLineGraph - multiple data sets drawn as lines on one graph;
38
39	SteppedLineGraph - a line graph with its lines drawin in horizonal and vertical
40	steps;
41
42	MultiSteppedLineGraph - a MultiLineGraph, but using stepped lines;
43
44	StackedBarGraph - multiple data sets drawn as bars, stacked one on top of
45	another;
46
47	GroupedBarGraph - multiple data sets drawn as bars, side-by-side;
48
49	StackedLineGraph - multiple data sets, their values added together;
50
51	StackedGroupedBarGraph - multiple data sets, their values added together and
52	split into groups;
53
54	BarAndLineGraph - a grouped bar graph and multi-line graph on the same graph;
55
56	StackedBarAndLineGraph - a stacked bar graph and multi-line graph on the same
57	graph;
58
59	Histogram - a bar graph that shows the range of values;
60
61	ParetoChart - a bar and line graph showing sorted and summed values;
62
63	MultiScatterGraph - scatter graph supporting multiple data sets;
64
65	HorizontalBarGraph - a bar graph with the axes swapped;
66
67	HorizontalStackedBarGraph - a stacked bar graph drawn horizontally;
68
69	HorizontalGroupedBarGraph - a grouped bar graph drawn horizontally;
70
71	HorizontalBar3DGraph - a 3D bar graph with the axes swapped;
72
73	HorizontalStackedBar3DGraph - a stacked 3D bar graph drawn horizontally;
74
75	HorizontalGroupedBar3DGraph - a grouped 3D bar graph drawn horizontally;
76
77	RadarGraph - a radar or star graph with values drawn as lines;
78
79	MultiRadarGraph - a radar graph supporting multiple data sets;
80
81	CylinderGraph - a 3D bar graph with the bars cylinder shaped;
82
83	StackedBar3DGraph - a 3D bar graph version of the stacked bar graph;
84
85	GroupedBar3DGraph - a 3D bar graph version of the grouped bar graph;
86
87	StackedGroupedBar3DGraph - a 3D bar graph version of the stacked grouped bar
88	graph;
89
90	StackedCylinderGraph - a cylinder-bar version of the stacked bar graph;
91
92	GroupedCylinderGraph - a cylinder-bar version of the grouped bar graph;
93
94	StackedGroupedCylinderGraph - a cylinder-bar version of the stacked grouped
95	bar graph;
96
97	DonutGraph - a pie graph with a hole in the middle;
98
99	SemiDonutGraph - half of a donut graph;
100
101	Donut3DGraph - a 3D version of the donut graph;
102
103	SemiDonut3DGraph - a 3D version of the semi-donut graph;
104
105	PolarAreaGraph - a pie graph where the area of the slice varies instead of
106	its angle;
107
108	PolarArea3DGraph - a 3D version of the polar area graph.
109
110	ExplodedPieGraph - a pie graph with slices exploded out from the centre.
111
112	ExplodedPie3DGraph - a 3D version of the exploded pie graph.
113
114	ExplodedDonutGraph - a donut graph with its slices exploded;
115
116	ExplodedSemiDonutGraph - a semi-donut graph with its slices exploded;
117
118	ExplodedDonut3DGraph - a 3D version of the exploded donut graph;
119
120	ExplodedSemiDonut3DGraph - a 3D version of the exploded semi-donut graph;
121
122	ArrayGraph - a graph containing other graphs.
123
124	There are also these graphs that are really hard to describe:
125
126	FloatingBarGraph; HorizontalFloatingBarGraph; BubbleGraph;
127	BoxAndWhiskerGraph; PopulationPyramid; CandlestickGraph; GanttChart.
128
129	Using SVGGraph
130	==============
131	The library consists of a directory of class files and a subdirectory of font
132	metrics. An autoloader will load classes on demand when they are required.
133	SVGGraph includes an autoloader script if you don't have one - include the
134	"autoloader.php" file to use it.
135
136	Embedding SVG in a page
137	=======================
138	There are several ways to insert SVG graphics into a page. At time of writing,
139	all modern browsers support SVG natively, so the Adobe plugin is not required.
140
141	For options 1-3, I'll assume you have a PHP script called "graph.php" which
142	contains the SVGGraph code to generate the SVG document.
143
144	Option 1: the embed tag
145	<embed src="graph.php" type="image/svg+xml" width="600" height="400"
146	pluginspage="http://www.adobe.com/svg/viewer/install/" />
147
148	This method works in all browsers, though the embed tag is not part of the HTML
149	standard.
150
151	Option 2: the iframe tag
152	<iframe src="graph.php" type="image/svg+xml" width="600" height="400"></iframe>
153
154	This method also works in all browsers, and the iframe tag is standard.
155
156	Option 3: the object tag
157	<object data="graph.php" width="600" height="100" type="image/svg+xml" />
158
159	The object tag is standard, but this doesn't work in old versions of IE.
160
161	Option 4a: using the svg namespace within an xhtml document
162
163	This option is more complicated, as it requires changing the doctype and
164	content type of the page being served. The SVG is generated as part of the
165	same page.
166	<?php
167	header('content-type: application/xhtml+xml; charset=UTF-8');
168	// $graph = new Goat1000\SVGGraph\SVGGraph(...);
169	// $graph setup here!
170	?>
171	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN"
172	"http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd">
173	<html xmlns="http://www.w3.org/1999/xhtml"
174	xmlns:svg="http://www.w3.org/2000/svg"
175	xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en">
176	<head>
177	<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
178	<title>SVGGraph example</title>
179	</head>
180	<body>
181	<h1>Example of SVG in XHTML</h1>
182	<div>
183	<?php echo $graph->Fetch('BarGraph', false); ?>
184	</div>
185	</body>
186	</html>
187
188	This method allows you more control over how you use the SVG, though again it
189	doesn't work in older IE.
190
191	Option 4b: using SVG in HTML5
192
193	HTML5 is much more relaxed about containing non-HTML code, so you can insert
194	the SVG code without too much hassle.
195	<?php
196	// $graph = new Goat1000\SVGGraph\SVGGraph(...);
197	// $graph setup here!
198	?>
199	<!DOCTYPE html>
200	<html>
201	<head>
202	<title>SVGGraph in HTML5</title>
203	</head>
204	<body>
205	<h1>Example of SVG in HTMLi5</h1>
206	<div>
207	<?php echo $graph->Fetch('BarGraph', false); ?>
208	</div>
209	</body>
210	</html>
211
212	This works in all modern browsers.
213
214	Option 5: using the img tag
215
216	I don't recommend this method, since it prevents tooltips and other graph
217	options from working. Browser support can be patchy too.
218
219	Class Constructor
220	=================
221	The SVGGraph class constructor takes three arguments, the width and height
222	of the SVG image in pixels and an optional array of settings to be passed to
223	the rendering class. The full namespace is required to create the instance.
224	$graph = new Goat1000\SVGGraph\SVGGraph($width, $height, $settings);
225
226	For more information on the $settings array, see the section below.
227
228	Data Values
229	===========
230	For simple graphs you may set the data to use by passing it into the Values
231	function:
232	$graph->values(1, 2, 3);
233
234	For more control over the data, and to assign labels, pass the values in as an
235	array:
236	$data = array('first' => 1, 'second' => 2, 'third' => 3);
237	$graph->values($data);
238
239	For graphs supporting multiple datasets, pass each dataset as an array within
240	an outer array:
241	$data = array(
242	array('first' => 1, 'second' => 2, 'third' => 3),
243	array('first' => 3, 'second' => 4, 'third' => 2)
244	);
245	$graph->values($data);
246
247	Scatter graphs draw markers at x,y coordinates, given as the key and value in
248	the data array:
249	$data = array(5 => 20, 6 => 30, 10 => 90, 20 => 50);
250	$graph->values($data);
251
252	This will draw the markers at (5,20), (6,30), (10,90) and (20,50). To draw
253	markers using the same X value you must use structured data - please visit the
254	website for details and examples.
255
256	Note: data in this format are not supported by any of the non-scatter graph
257	types.
258
259	Hyperlinks
260	==========
261	The graph bars and markers may be assigned hyperlinks - each value that requires
262	a link should have a URL assigned to it using the Links function:
263	$graph->links('/page1.html', NULL, '/page3.html');
264
265	The NULL is used here to specify that the second bar will not be linked to
266	anywhere.
267
268	As with the Values function, the list of links may be passed in as an array:
269	$links = array('/page1.html', NULL, '/page3.html');
270
271	Using an associative array means that NULL values may be skipped.
272	$links = array('first' => '/page1.html', 'third' => '/page3.html');
273	$graphs->links($links);
274
275	Rendering
276	=========
277	To generate and display the graph, call the Render function passing in the
278	type of graph to be rendered:
279	$graph->render('BarGraph');
280
281	This will send the correct content type header to the browser and output the
282	SVG graph.
283
284	The Render function takes two optional parameters in addition to the graph
285	type:
286	$graph->render($type, $header, $content_type);
287
288	Passing in FALSE for $header will prevent output of the XML declaration and
289	doctype. Passing in FALSE for $content_type will prevent the 'image/svg+xml'
290	content type being set in the response header.
291
292	To generate the graph without outputting it to the browser you may use the
293	Fetch function instead:
294	$output = $graph->fetch('BarGraph');
295
296	This function also takes an optional $header parameter:
297	$output = $graph->fetch($type, $header);
298
299	Passing in FALSE as $header will prevent the returned output from containing
300	the XML declaration and doctype. The Fetch function never outputs the content
301	type to the response header.
302
303	Colours
304	=======
305	SVGGraph has several functions for setting the functions to use. The simplest
306	assigns an array of colours to be used in turn.
307	$colours = array('red', 'green', '#00ffff', 'rgb(100,200,100)',
308	array('red','green'));
309	$graph->colours($colours);
310
311	You may use any of the standard named colours, or hex notation, or RGB notation.
312
313	SVGGraph also supports gradients and patterns, described in detail on the
314	website.
315
316	Settings
317	========
318	Many of the ways that things are displayed may be changed by passing in an array
319	of settings to the SVGGraph constructor:
320	$settings = array('back_colour' => 'white');
321	$graph = new Graph($w, $h, $settings);
322
323	There are literally hundreds of options available, though not all of them are
324	relevant for all graph types. For the full list of options, examples and
325	descriptions, please visit the website: http://www.goat1000.com/svggraph.php
326
327
328	Contact details
329	===============
330	For more information about this software please contact the author,
331	graham(at)goat1000.com or visit the website: http://www.goat1000.com/
332
333
334	Copyright (C) 2009-2023 Graham Breach
335