Fork me on GitHub

Zoom plugin

The Zoom plugin allows the use to zoom on the graph using the mouse. When the use clicks on the graph, holds the mouse down and moves it around, a red rectangle is formed, which defined the new zooming boundaries that the graph will take when the mouse is released.

Enabling the zoom plugin

The zoom plugin, like any other plugin, needs to be enabled upon graph creation:

new Graph( "domID", {  
  plugins: {
     'zoom': {
        // ... zoom options
      }
  }
});

Features

Here are a few features that the zoom plugin can provide you:

  • Zooming in x and y direction or forced in the x or y-direction
  • Zooming on one axis only
  • Double click to unzoom
  • Mouse wheel to zoom gradually
  • Smooth transition (animated zooming)
  • Event calls and cancellation possible

Basics

We will now cover the basics of the zoom plugin. The zoom plugin is intimate with the option mouseActions of the graph, which can be accessed in the constructor options or via direct settings. The mouse actions define what jsGraph should do upon various mouse events. We will cover the mouse actions in details somewhere else, but for now, let’s take the following code as it is:

new Graph( "domID", {  
  plugins: {
     'zoom': {
        // ... zoom options
        zoomMode: 'xy'
      }
  },

  mouseActions: [
    { plugin: 'zoom', shift: false, ctrl: false }
  ]
});

The following code enables the zoom plugin only when the Shift and Ctrl key are not pressed. If one of these were true, the use would need to have the key pressed to enable zooming.

Example

Using the previous code, we create the zoom plugin and enable it using the mouse action. The buttons below the graph trigger the following code.

// Enabling button
graph.options.mouseActions[ 0 ].shift = true;

// Disabling button
graph.options.mouseActions[ 0 ].shift = false;

Forcing the x or y direction

The zoomMode options passed in the plugin creation or after its initialization defined the behaviour of the zoom and takes the following possible values:

  • xy lets the use zoom in both directions
  • x forces zooming in the x direction only
  • y forces zooming in the y direction only

Unzoom on double click

So far, the only way to unzoom on a graph is to active the double click. The double click behavior is also defined through mouse actions, in the following way:

// Enabling button
{ type: 'dblclick', plugin: 'zoom', shift: false, options: { mode: 'total' } }

Where the type defines the mouse action (dblclick in this case), upon which the plugin zoom is called with the options { mode: 'total' }.

The only available option in the double click mouse events is the mode options, which takes the following values:

  • total (default): Unzooms the axes to fit the natural boundaries of the axes (defined by the data or by the forcedMin/forcedMax options)
  • xtotal. Only unzooms the x axis
  • ytotal. Only unzooms the y axis
  • gradualXY. Unzooms the axes by a factor 2 only. The unzooming is centered on the position where the mouse is clicked
  • gradualX. Same as gradualXY but in the x direction only
  • gradualY. Same as gradualY but in the y direction only

Zooming on one axis only

The default behaviour of jsGraph is to unzoom all present axes on the graph. The mouse coordinates are transformed into respective axes coordinates and used accordingly. However jsGraph also allows you to select which axis should be zoomed.

Changing the zooming axis(es) can be done through the axes options of the zoom plugin and can take the following values:

  • all (default): Zooms and unzooms on all axes.
  • serieSelected: Zooms and unzooms on the axes belonging to the selected series
  • [ axis0, axis1, ..., axisN ]. Provide a user-defined list of axes

Reminder: line series can be made selectable on click using the selectableOnClick: (bool) option and all series can be programmatically selected or unselected using the .select() or .unselect() API.

Note: In this example, the x axis is shared between the two series. Hence the serie that is not selected will also be scaled in the x direction when the option serieSelected is set

Smooth zooming

Smooth zooming and unzooming using animations is possible with jsGraph, by setting the smooth flag to true in the plugin constructor or after its creation

graph.getPlugin('zoom').options.smooth = true; // Enables smoothing

This option will apply to zooming and unzooming indepedently

Mouse wheel

The mousewheel behavior is set in the mouseActions array of the graph instance. Options include:

  • baseline sets the zero of the scaling
  • direction (y or x) sets the direction of the zooming
{ plugin: 'zoom', shift: true, type: 'mousewheel', options: { baseline: 0, direction: 'y' } },