JSPlot API reference: The plotting canvas
API reference
- The plotting canvas
- Plotting graphs
- Graph axis options
- Graph plotting styles
- Plotting functions
- Vector graphics objects
Page structure
JSPlot_Canvas class: API reference
Instances of the JSPlot_Canvas class are used to create a new drawing canvas onto which to add charts and other vector graphics objects. Once a new canvas has been populated, call the renderToCanvas method to render its contents into an HTML element on the page, such as a <div>. Alternatively, the renderToPNG and renderToSVG methods render the canvas to PNG and SVG files respectively.
my_canvas = new JSPlot_Canvas(list_of_objects, settings);
| Argument | Allowed values | Description |
| list_of_objects | Associative array |
An associative array of items to put on the canvas. These should be instances of the JSPlot_Graph , JSPlot_Arrow , JSPlot_Circle , JSPlot_Ellipse , JSPlot_Rectangle or JSPlot_Text classes. The key associated with each member of the associated array may subsequently be used to remove that item from the canvas, using the JSPlot_Canvas instance's removeItem method. Additional items can be added to the canvas using the addItem method. |
| settings | Associative array | An associative array of configuration options. Allowed key values are listed below. |
Allowed configuration parameters within the settings array are as follows:
| Field | Allowed values | Description |
| allow_export_png | boolean | Choose whether a button should appear beneath the plot, inviting the user to download a PNG copy of the canvas. |
| allow_export_svg | boolean | Choose whether a button should appear beneath the plot, inviting the user to download a SVG copy of the canvas. |
| allow_export_csv | boolean | Choose whether a button should appear beneath the plot, inviting the user to download a copy of the data plotted on all of the graphs on the canvas, in CSV format. |
Once instantiated, a JSPlot_Canvas instance offers the following methods:
| Method | Arguments | Description |
| configure | settings (associative array) | Update the settings for this canvas. settings should be an associative array, with the same keys as listed above. |
| renderToCanvas | target_element (HTML container element, e.g. a <div>) | Render the drawing canvas into the target element. The existing contents of the target element are replaced with a new HTML5 <canvas> element, followed by any export buttons enabled in the settings. The width of the target element sets the page width used to lay out the graphs, and the HTML5 canvas is resized to accommodate the objects on the JSPlot canvas. The plot is re-rendered automatically whenever the browser window is resized. |
| addItem |
name (string)
item (canvas object) |
Add an object to the drawing canvas. The name should be a unique string which can be used to subsequently remove the item by calling the removeItem method on the JSPlot_Canvas instance. The item argument should be an instance of the JSPlot_Graph , JSPlot_Arrow , JSPlot_Circle , JSPlot_Ellipse , JSPlot_Rectangle or JSPlot_Text classes. |
| removeItem | name (string) | Remove a named object from the drawing canvas. |
| renderToPNG | page_width (number) | Render the contents of the canvas to a PNG file, and open a new browser window showing that PNG image. (In Internet Explorer, the PNG file is downloaded instead.) If specified, the argument page_width should indicate the width of the PNG file in pixels. |
| renderToSVG | page_width (number) | Render the contents of the canvas to a SVG file, and return the contents of the SVG file as a string. If specified, the argument page_width should indicate the width of the SVG file in pixels. |
| renderToCSV | None | Render the data shown on all of the graphs on the canvas into CSV, and return the contents of that CSV file as a string. Each graph's title, and each dataset's title, is written on its own line above the data it labels. |