1     Notes on using the gnuplot canvas terminal driver to create web pages
2     =====================================================================
3
4
51) Using UTF-8 characters in your plots
6
7I expect that eventually web browsers will learn to draw text onto the HTML
8canvas element using their native font-handling code.  But until then we
9have to refer to an external character drawing library.
10
11The gnuplot package includes two versions of a script to draw characters on
12the canvas.  The first one, canvastext.js, was written by Jim Studt. It only
13knows about the 7-bit ascii characters.  The second one, canvasmath.js, is
14an expanded version of Jim Studt's script that I wrote to handle UTF8.
15It contains glyphs for the first two unicode code pages (latin-1), the greek
16alphabet, and select math and physics symbols. You can use this to replace
17canvastext.js if you like, or refer to it explicitly in plots that need
18non-ascii characters.
19
20
212) Browser dependencies
22
23As of this time (May 2009) the HTML canvas element is supported by the
24latest versions of Opera, Safari, Firefox, and Konqueror.  However, each
25of these has quirks.
26
27For instance, only Firefox makes it easy to click and drag with the middle
28or right mouse buttons;  the other browsers try to pop up various menus instead.
29We try to override this, but it doesn't always work.
30
31Conversely, Opera and Safari make it easy to use hot keys ('e' for refresh,
32'r' to toggle the ruler, etc), but I have not managed to get this to work
33in Firefox.
34
35If you run into problems, please try several browsers before concluding that it
36is a gnuplot problem.  If you figure out a work-around for one of these browser
37quirks, please tell me so that we can try to incorporate into gnuplot output.
38
39
403) Creating a basic web page with a single mouseable plot
41
42The canvas terminal driver itself will create a basic html document containing
43a mousable plot.  The command options to do this are
44	set term canvas standalone mousing jsdir "http://myserver"
45	set output 'myplot.html'
46This document contains
47	- a reference to style sheet gnuplot_mouse.css
48	- a reference to support script gnuplot_mouse.js
49	- a javascript function named 'gnuplot_canvas'
50	- a canvas element named 'gnuplot_canvas' that will be drawn in by the
51	  javascript function of the same name
52	- an html table containing the readout for mouse coordinates, as well
53	  as clickable icons for additional mousing operations
54The *.css and *.js references point back to whatever source URL you specified
55in the jsdir option to the 'set term' command.  For example:
56<link type="text/css" href="http://myserver/gnuplot_mouse.css" rel="stylesheet">
57In order for viewers to use your plot document, they must be able to access the
58*.css and *.js files via the URL embedded in the document.
59
60
614) Creating a web page with multiple mouseable plots
62
63In order to embed multiple plots in a single document, you must
64provide your own html framework.  You can use the one created by the canvas
65driver in standalone mode as a starting point, including the references to
66gnuplot_mouse.css and gnuplot_mouse.js.  However, instead of a single
67javascript routine named gnuplot_canvas() that always draws the same plot,
68you must provide a wrapper routine with the same name that connects the
69mousing code to whichever plot is currently active.  Here is an example:
70- create the individual plots as separate javascript files
71	set term canvas name 'plot1'
72	set output 'plot1.js'
73	plot something
74	set term canvas name 'plot2'
75	set output 'plot2.js'
76	plot something_else
77- create your html wrapper, including a script block such as the one below.
78  You must use these specific variable names, as they are referenced by the
79  javascript code produced by the canvas terminal.
80	<script type="text/javascript">
81	var canvas, ctx;
82	var grid_lines = true;
83	var zoomed = false;
84	var active_plot_name = "gnuplot_canvas";
85	var active_plot = dummyplot;
86	function dummyplot() {};
87	function gnuplot_canvas( plot ) { active_plot(); };
88	</script>
89- add one or more mousing output tables.  As a model, you can use either the one
90  in a standalone plot or the file .../demo/html/mousebox.template.
91  The table id and text span ids in the "mousebox" table must match the ones
92  by your individual plots in order for mousing readout to work.
93- each of the individual plots in the document should be explicitly called when
94  the document is loaded.  For example, for each plot there could be a block
95  of html similar to the following:
96	<canvas id="plot1" width="600" height="400" tabindex="0"></canvas>
97	<script src="plot1.js"></script>
98	<script>
99	    if (window.attachEvent) {window.attachEvent('onload', plot1);}
100	    else if (window.addEventListener) {window.addEventListener('load', plot1, false);}
101	</script>
102  Alternatively, the onload attributes could be set in the html <BODY> element
103
104
105
106	- Ethan A Merritt (sfeam@users.sourceforge.net)
107	  May 2009
108
109