Fork me on GitHub

Graph

Entry class of jsGraph that creates a new graph.

Constructor

new Graph( HTMLElement, String wrapper [ , GraphOptions options ] [ , Object axis ] )

Graph constructor
Parameters:
Name Type Attributes Description
wrapper HTMLElement | String The DOM Wrapper element or the element ```id``` where it can be found
options GraphOptions <optional>
The options of the graph
axis Object <optional>
The list of axes
Properties
Name Type Description
left Array The list of left axes
bottom Array The list of bottom axes
top Array The list of top axes
right Array The list of right axes
Tutorials:
  • Tutorial: basic

Extends

  • EventEmitter

Members

(static) GraphOptions

Default graph parameters
Properties:
Name Type Description
title String Title of the graph
paddingTop Number The top padding
paddingLeft Number The left padding
paddingRight Number The right padding
paddingBottom Number The bottom padding
padding Number | Boolean A common padding value for top, bottom, left and right
fontSize Number The basic text size of the graphs
fontFamily Number The basic font family. Should be installed on the computer of the user
plugins Object.<String, Object> A list of plugins to import with their options
pluginAction Object.<String, Object> The default key combination to access those actions
mouseActions Object.<String, Object> Alias of pluginActions
wheel Object Define the mouse wheel action
dblclick Object Define the double click action
shapesUniqueSelection Boolean true to allow only one shape to be selected at the time
shapesUnselectOnClick Boolean true to unselect all shapes on click

options :GraphOptions

Type:
  • GraphOptions
Default Value:
  • GraphOptionsDefault Access directly the options of the graph using this public object.
Example
graph.options.mouseActions.push( {  } );

Methods

(static) {Graph} fromSchema( Object schema , HTMLElement wrapper )

Returns a graph created from a schema
Parameters:
Name Type Description
schema Object The schema (see https://github.com/cheminfo/json-chart/blob/master/chart-schema.json)
wrapper HTMLElement The wrapping element
Returns:
{ Graph } Newly created graph

(static) {function} getConstructor( String constructorName )

Returns a registered constructor
Parameters:
Name Type Description
constructorName String The constructor name to look for
See:
Throws:
Error
Returns:
{ function } The registered constructor

(static) registerConstructor( String constructorName , function constructor )

Registers a constructor to jsGraph. Constructors are used on a later basis by jsGraph to create series, shapes or plugins
Parameters:
Name Type Description
constructorName String The name of the constructor
constructor function The constructor method
See:

_applyToAxes( AxisCallbackFunction, String func , params , Boolean topbottom , Boolean leftright )

Applies a function to axes. The function will be executed once for every axis. If func is a string, the internal function belonging to the axis will be called, with the params array flattened out (in this case, params must be an array). If func is a function, the function will be called with the axis, its type and params as parameters. See AxisCallbackFunction for more details.
Parameters:
Name Type Default Description
func AxisCallbackFunction | String The function or function name to execute
params Extra parameters to pass to the function
topbottom Boolean false True to apply to function to top and bottom axes
leftright Boolean false True to apply to function to left and right axes

autoscaleAxes( )

Autoscales the x and y axes of the graph
Repains the canvas

cacheOffset( )

Caches the wrapper offset in the page.
The position of the wrapper is used when processing most of mouse events and it is fetched via the jQuery function .offset(). If performance becomes a critical issue in your application, cacheOffset() should be used to store the offset position. It should be ensured that the graph doesn't move in the page. If one can know when the graph has moved, cacheOffset() should be called again to update the offset position.

{Graph} delayUpdate( )

Prevents the graph, the series and the legend from redrawing automatically. Valid until Graph#resumeUpdate is called
Since:
  • 1.16.19
See:
Returns:
{ Graph } The current graph instance

displayTitle( )

Shows the title of the graph

{Graph} doUpdate( )

Forces legend and graph update, even is Graph#delayUpdate has been called before.
Since:
  • 1.16.19
See:
Returns:
{ Graph } The current graph instance

draw( )

Draw the graph and the series. This method will only redraw what is necessary. You may trust its use when you have set new data to series, changed serie styles or called for a zoom on an axis.

drawSerie( Serie serie , Boolean force )

Draws a specific serie
Parameters:
Name Type Description
serie Serie The serie to redraw
force Boolean Forces redraw even if no data has changed

drawSeries( Boolean force )

Redraws all visible series
Parameters:
Name Type Description
force Boolean Forces redraw even if no data has changed

{Array.<Axis>} findAxesLinkedTo( Axis axis )

Axes can be dependant of one another (for instance for unit conversions) Finds and returns all the axes that are linked to a specific axis. Mostly used internally.
Parameters:
Name Type Description
axis Axis The axis that links one or multiple other dependant axes
Returns:
{ Array.<Axis> } The list of axes linked to the axis passed as parameter

getBottomAxis( [ , Number index ] [ , Object options ] )

Returns the bottom axis at a certain index. Creates it if non-existant
Parameters:
Name Type Attributes Default Description
index Number <optional>
0 The index of the axis
options Object <optional>
{} The options to pass to the axis constructor

getBoundaryAxis( )

Calculates the minimal or maximal value of the axis. Currently, alias of getBoudaryAxisFromSeries

{SVGElement} getDom( )

Returns the graph SVG wrapper element
Returns:
{ SVGElement } The DOM element wrapping the graph

{Number} getDrawingHeight( Boolean useCache )

Returns the height of the drawable zone, including the space used by the axes
Parameters:
Name Type Description
useCache Boolean Use cached value. Useful if one is sure the graph hasn't changed dimension. Automatically called after a Graph.resize();
Returns:
{ Number } Height of the graph

{Number} getDrawingWidth( Boolean useCache )

Returns the width of the drawable zone, including the space used by the axes
Parameters:
Name Type Description
useCache Boolean Use cached value. Useful if one is sure the graph hasn't changed dimension. Automatically called after a Graph.resize();
Returns:
{ Number } Width of the graph

{Number} getHeight( )

Returns the height of the graph (set by setSize, setHeight or resize methods)
Returns:
{ Number } Height of the graph

{String} getId( )

Returns the unique id representing the graph
Returns:
{ String } The unique ID of the graph

getLeftAxis( [ , Number index ] [ , Object options ] )

Returns the left axis at a certain index. Creates it if non-existant
Parameters:
Name Type Attributes Default Description
index Number <optional>
0 The index of the axis
options Object <optional>
{} The options to pass to the axis constructor

{Legend} getLegend( )

Returns:
{ Legend } The legend item

{Number} getPaddingBottom( )

Returns the bottom padding of the graph (space between the bottom of the svg container and the bottommost axis)
Returns:
{ Number } paddingTop

{Number} getPaddingLeft( )

Returns the left padding of the graph (space between the left of the svg container and the leftmost axis)
Returns:
{ Number } paddingTop

{Number} getPaddingRight( )

Returns the right padding of the graph (space between the right of the svg container and the rightmost axis)
Returns:
{ Number } paddingRight

{Number} getPaddingTop( )

Returns the top padding of the graph (space between the top of the svg container and the topmost axis)
Returns:
{ Number } paddingTop

{Plugin} getPlugin( String pluginName )

Returns an initialized plugin
Parameters:
Name Type Description
pluginName String
Returns:
{ Plugin } The plugin which name is

getRightAxis( [ , Number index ] [ , Object options ] )

Returns the right axis at a certain index. Creates it if non-existant
Parameters:
Name Type Attributes Default Description
index Number <optional>
0 The index of the axis
options Object <optional>
{} The options to pass to the axis constructor

{Serie|undefined} getSelectedSerie( )

Returns the selected serie
Returns:
{ Serie | undefined } The selected serie

{Serie} getSerie( String, Number name )

Looks for an existing serie by name or by index and returns it. The index of the serie follows the creation sequence (0 for the first one, 1 for the second one, ...)
Parameters:
Name Type Description
name String | Number The name or the index of the serie
Returns:

{Array.<Serie>} getSeries( )

Returns all the series
Returns:
{ Array.<Serie> } An array of all the series

{Array.<Serie>} getSeriesFromAxis( Axis axis )

Returns all the series associated to an axis
Parameters:
Name Type Description
axis Axis The axis to which the series belong
Returns:
{ Array.<Serie> } An array containing the list of series that belong to the axis

getShapes( )

Returns all shapes from the graph

{Array.<Shape>} getShapesOfSerie( Serie serie )

Returns all the shapes associated to a serie. Shapes can (but don't have to) be associated to a serie. The position of the shape can then be relative to the same axes as the serie.
Parameters:
Name Type Description
serie Serie The serie containing the shapes
Returns:
{ Array.<Shape> } An array containing a list of shapes associated to the serie

getTopAxis( [ , Number index ] [ , Object options ] )

Returns the top axis at a certain index. Creates it if non-existant
Parameters:
Name Type Attributes Default Description
index Number <optional>
0 The index of the axis
options Object <optional>
{} The options to pass to the axis constructor

{Number} getWidth( )

Returns the width of the graph (set by setSize, setWidth or resize methods)
Returns:
{ Number } Width of the graph

{HTMLElement} getWrapper( )

Returns the graph wrapper element passed during the graph creation
Returns:
{ HTMLElement } The DOM element wrapping the graph

getXAxis( [ , Number index ] [ , Object options ] )

Returns the x axis at a certain index. If any top axis exists and no bottom axis exists, returns or creates a top axis. Otherwise, creates or returns a bottom axis Caution ! The options parameter will only be effective if an axis is created
Parameters:
Name Type Attributes Default Description
index Number <optional>
0 The index of the axis
options Object <optional>
{} The options to pass to the axis constructor

getYAxis( [ , Number index ] [ , Object options ] )

Returns the y axis at a certain index. If any right axis exists and no left axis exists, returns or creates a right axis. Otherwise, creates or returns a left axis Caution ! The options parameter will only be effective if an axis is created
Parameters:
Name Type Attributes Default Description
index Number <optional>
0 The index of the axis
options Object <optional>
{} The options to pass to the axis constructor

hasBottomAxis( Axis axis )

Determines if an x axis belongs to bottom axes list of the graph
Parameters:
Name Type Description
axis Axis The axis instance to check

hasLeftAxis( Axis axis )

Determines if a y axis belongs to left axes list of the graph
Parameters:
Name Type Description
axis Axis The axis instance to check

hasRightAxis( Axis axis )

Determines if a y axis belongs to right axes list of the graph
Parameters:
Name Type Description
axis Axis The axis instance to check

hasTopAxis( Axis axis )

Determines if an x axis belongs to top axes list of the graph
Parameters:
Name Type Description
axis Axis The axis instance to check

hasXAxis( Axis axis )

Determines if an x axis belongs to the graph
Parameters:
Name Type Description
axis Axis The axis instance to check

hasYAxis( Axis axis )

Determines if an x axis belongs to the graph
Parameters:
Name Type Description
axis Axis The axis instance to check

hideTitle( )

Hides the title of the graph

kill( )

Kills the graph

makeLegend( Object options )

Creates a legend. Only one legend is allowed per graph
Parameters:
Name Type Description
options Object The legend options

newPosition( * …var_args )

Creates a new position. Arguments are passed to the position constructor
Parameters:
Name Type Attributes Description
var_args * <repeatable>
See:

{Serie} newSerie( String name , Object options , Type type )

Creates a new serie. If the a serie with the same name exists, returns this serie with update options. The type of the serie is used to fetch the corresponding registered constructor registered with the name "graph.serie.", e.g "line" will fetch the "graph.serie.line" prototype (built-in)
Built-in series types are "line", "contour", "zone" and "scatter".
Parameters:
Name Type Description
name String The name of the serie (unique)
options Object The serie options
type Type The type of the serie.
Returns:
{ Serie } The newly created serie

{Shape} newShape( String shapeType [ , Object shapeData ] [ , Boolean mute ] [ , Object shapeProperties ] )

Creates a new shape. jsGraph will look for the registered constructor "graph.shape.".
Parameters:
Name Type Attributes Default Description
shapeType String The type of the shape
shapeData Object <optional>
The options passed to the shape creator
mute Boolean <optional>
false true to create the shape quietly
shapeProperties Object <optional>
The native object containing the shape properties in the jsGraph format (caution when using it)
See:
  • Graph#getConstructor
Returns:
{ Shape } The created shape

{Boolean} redraw( Boolean onlyIfAxesHaveChanged )

Calls a repaint of the container. Used internally when zooming on the graph, or when .autoscaleAxes() is called (see Graph#autoscaleAxes).
To be called after axes min/max are expected to have changed (e.g. after an axis.zoom( from, to )) has been called
Parameters:
Name Type Description
onlyIfAxesHaveChanged Boolean Triggers a redraw only if min/max values of the axes have changed.
Returns:
{ Boolean } if the redraw has been successful

redrawShapes( )

Redraws all shapes. To be called if their definitions have changed

removeSeries( )

removeSeries( )

removeSeries( )

Removes all series from the graph

removeShapes( )

Removes all shapes from the graph

{Graph} resize( [ , Number width ] [ , Number height ] )

Sets the new dimension of the graph and repaints it. If width and height are omitted, a simple refresh is done.
Parameters:
Name Type Attributes Description
width Number <optional>
The new width of the graph
height Number <optional>
The new height of the graph
See:
Returns:
{ Graph } The current graph

{Graph} resumeUpdate( )

Cancels the effect of Graph#delayUpdate, but does not redraw the graph automatically
Since:
  • 1.16.19
See:
Returns:
{ Graph } The current graph instance

selectSerie( Serie serie , String selectName )

Selects a serie. Only one serie per graph can be selected.
Parameters:
Name Type Default Description
serie Serie The serie to select
selectName String "selected" The name of the selection

selectShape( Shape shape , Boolean mute )

Selects a shape
Parameters:
Name Type Description
shape Shape The shape to select
mute Boolean Select the shape quietly

{Graph} setBackgroundColor( String color )

Sets the background color
Parameters:
Name Type Description
color String An SVG accepted color for the background
Returns:
{ Graph } The current graph instance

setBottomAxis( Axis axis [ , Number index ] )

Sets a bottom axis
Parameters:
Name Type Attributes Default Description
axis Axis The axis instance to set
index Number <optional>
0 The index of the axis
See:

setHeight( Number height , Boolean skipResize )

Sets the total height of the graph
Parameters:
Name Type Description
height Number The new height of the graph
skipResize Boolean true to defer graph repaint. Use Graph#resize to force repain later on. (Useful if many graph sizing operations are done successively)
See:

setLeftAxis( Axis axis [ , Number index ] )

Sets a left axis
Parameters:
Name Type Attributes Default Description
axis Axis The axis instance to set
index Number <optional>
0 The index of the axis
See:

{Graph} setOption( String name , value )

Sets an option of the graph
Parameters:
Name Type Description
name String Option name
value New option value
Returns:
{ Graph } - Graph instance

setRightAxis( Axis axis [ , Number index ] )

Sets a right axis
Parameters:
Name Type Attributes Default Description
axis Axis The axis instance to set
index Number <optional>
0 The index of the axis
See:

setSize( [ , Number width ] [ , Number height ] )

Sets the new dimension of the graph without repainting it. Use Graph#resize to perform the actual resizing of the graph.
Parameters:
Name Type Attributes Description
width Number <optional>
The new width of the graph
height Number <optional>
The new height of the graph
See:

setTitle( )

Sets the title of the graph

setTopAxis( Axis axis [ , Number index ] )

Sets a top axis
Parameters:
Name Type Attributes Default Description
axis Axis The axis instance to set
index Number <optional>
0 The index of the axis
See:

setWidth( Number width , Boolean skipResize )

Sets the total width of the graph
Parameters:
Name Type Description
width Number The new width of the graph
skipResize Boolean true to defer graph repaint. Use Graph#resize to force repain later on. (Useful if many graph sizing operations are done successively)
See:

setXAxis( Axis axis [ , Number index ] )

Sets a bottom axis
Parameters:
Name Type Attributes Default Description
axis Axis The axis instance to set
index Number <optional>
0 The index of the axis

setYAxis( Axis axis [ , Number index ] )

Sets a left axis
Parameters:
Name Type Attributes Default Description
axis Axis The axis instance to set
index Number <optional>
0 The index of the axis

uncacheOffset( )

Un-caches the wrapper offset value

unselectSerie( Serie serie )

Unselects a serie
Parameters:
Name Type Description
serie Serie The serie to unselect

unselectShape( Shape shape , Boolean mute )

Unselects a shape
Parameters:
Name Type Description
shape Shape The shape to unselect
mute Boolean Unselect the shape quietly

{Graph} unselectShapes( [ , Boolean mute ] )

Unselects all shapes
Parameters:
Name Type Attributes Default Description
mute Boolean <optional>
false Mutes all unselection events
Returns:
{ Graph } The current graph instance

updateDataMinMaxAxes( )

Determines the maximum and minimum of each axes, based on Graph#getBoundaryAxis. It is usually called internally, but if the data of series has changed, called this function to make sure that minimum / maximum of the axes are properly updated.

{Graph} updateLegend( [ , Boolean onlyIfRequired ] )

Redraws the legend if it exists
Parameters:
Name Type Attributes Default Description
onlyIfRequired Boolean <optional>
false ```true``` to redraw the legend only when it actually needs to be updated
Returns:
{ Graph } The graph instance