flot-axishandle-plugin

    2.0.4 • Public • Published

    flot-axishandle-plugin Build Status

    This is a plugin for flot to create axis handles. The user can drag an axis handle to offset the associated axis. Multiple axis handles are supported.

    Options

    The plugin supports these options:

        axisHandles: [
            {
                position: number between 0 and 1,
                absolutePosition: number,
                show: true or false,
                location: 'near' or 'far',
                handleLabel: string,
                orientation: 'horizontal' or 'vertical',
                axisIndex: 0-based number,
                radius: number,
                handleClassList: [string],
                fill: color,
                horizontalHandleConstrain: function,
                verticalHandleConstrain: function
            },
            <more axis handles if needed>
        ]

    position position of the axis handle. It can be specified relative to the axis as a number between 0 and 1. Default value is 0.5.

    absolutePosition the axis handle position defined by the value on the axis. It has higher priority than position. Default value: undefined.

    show if false the axis handle won't be visible and the mouse interactions for it will be disabled. Default value: true.

    orientation is one of "horizontal" and "vertical". This value is context-independent. The same property can be used to position the axis handle in a Cartesian, Polar, or other coordinate system (currently we only have Cartesian). By convention, the values follow the geometric definition of the space (matching the natural layout of graphs): for Cartesian, the origin is in the lower-left corner, with horizontal (x) values increasing to the right and vertical (y) values increasing to the top. For Polar, the origin is at the center, with horizontal (θ) values increasing counter-clockwise and vertical (r) values increasing outward. Take the Cartesian as an example. If we set mode as "horizontal", we can move the handle horizontally. When this property is changed, the handle will be repositioned accordingly. For example if the handle's orientation is 'horizontal' and the handlePosition is 'far', when switching the orientation from 'horizontal' to 'vertical' the handle is repositioned from the top of the graph to the right side. Default value is 'vertical'.

    axisIndex indicates the axis index on the requested orientation. This value is 0-based. If the current index is unavailable for the requested orientation, an error message is logged in the console and the first index of the requested orientation is used. Default value is 0.

    location is one of "near" and "far". It controls the location of the axis handle. "near" means the position that is close to the axis. "far" means the position far away from the axis. Take the cartesian coordinate system as an example. If the orientation property is 'vertical', the near handle is at the left side of the coordinate system. The far handle is at the right side of the coordinate system. Default value is 'far'.

    handleLabel allows you to provide a label to a handle. The label will be displayed over the handle icon. Default value: n where n is handle's index.

    radius allows you to specify the radius of the handle. Default value is 17.

    handleClassList sets the classList of the handle(thumb). Default value is ['draggable'].

    fill is the color of the axis handle thumb. Default value: undefined (use fill color from CSS class .thumbIcon).

    horizontalHandleConstrain describes constrain for the horizontal handle movement. Default value is undefined.

    verticalHandleConstrain describes constrain for the vertical handle movement. Default value is undefined. Both the horizontalHandleConstrain and verticalHandleConstrain have the same input arguments and returned value type as the constrain property of the thumb plugin. The constrain function should be like:

        axisHandle.horizontalHandleConstrain = (mouseX, mouseY, previousX, previousY) => {
            // new X and Y
            return [mouseX, previousY];
        }

    Public Methods

    The plugin adds some public methods to the plot:

    • plot.getAxisHandles()

      Returns a list containing all the axis handles

    • plot.addAxisHandle(options)

      Creates a new axis handle with the parameters specified in options.

    • plot.removeAxisHandle(handleToRemove)

      Remove the specified axis handle from the plot. handleToRemove is an axis handle reference to one of the axis handles obtained with getAxisHandles()

    • plot.setAxisHandle(axisHandle, options)

      Changes one handle properties. Do not modify a property of the axis handle directly. For example, this will not re-render an axis handle:

          // Wrong
          axisHandle.orientation = 'horizontal';
    • plot.setAxisHandlePlotPositionConstrain(constrain)

      Changes the constrain of the position relative to the graph area. By default an axis handle is constrained inside the graph. The constrain is a function like:

      (mouseX, mouseY) => {  
          const offset = plot.offset();
          return [
              Math.max(0, Math.min(mouseX - offset.left, plot.width())),
              Math.max(0, Math.min(mouseX - offset.top, plot.height()))
          ];
      }

    Events

    axisHandleUpdates

    Every time one or more axis handles changes state an axisHandleUpdates event is emitted on the chart container. These events are emitted in one of these situations:

    • axis handle added
    • axis handle removed
    • axis handle changed
    • axis handle moved

    thumbIntoRange

    The thumbIntoRange event is fired on the plot's event holder when moving a thumb into the graph area. The thumbIntoRange event object is the instance of CustomEvent.

    data in the detail properties

    Property Type Description
    target SVG element the selected thumb/handle
    edge string one of 'topleft', 'topright', 'bottomleft', 'bottomright'
    orientation string 'horizontal' or 'vertical'
    position(option) float position relative to the thumb layer

    thumbOutOfRange

    The thumbOutOfRange event is fired on the plot's event holder when moving a thumb off the graph area. The thumbOutOfRange event object is the instance of CustomEvent.

    data in the detail properties

    Property Type Description
    target SVG element the selected thumb/handle
    edge string one of 'topleft', 'topright', 'bottomleft', 'bottomright'
    orientation string 'horizontal' or 'vertical'
    position(option) float position relative to the thumb layer

    thumbCreated

    The thumbCreated event is fired on the graph's placeholder whenever a new thumb is created. The event instance is the instance of CustomEvent.

    data in the detail property

    Property Type Description
    current SVG element the thumb/handle

    thumbWillBeRemoved

    The thumbWillBeRemoved event is fired on the graph's placeholder whenever a thumb will be removed. The event instance is the instance of CustomEvent.

    data in the detail property

    Property Type Description
    current SVG element the thumb/handle

    thumbVisibilityChanged

    The thumbVisibilityChanged event is fired when a thumb's visibility changes due to the change of the show property. The event instance is the instance of CustomEvent.

    data in the detail property

    Property Type Description
    current SVG element the thumb/handle
    visible boolean the value indicating the visibility of thumb

    How to use

    Installation

    npm install flot-thumb-plugin flot-axishandle-plugin

    Usage

    Import JavaScript files in your page.

    <!-- import the thumb plugin -->
    <script type="text/javascript" src="../node_modules/flot-thumb-plugin/dist/es5/jquery.thumb.js"></script>
    <!-- import the axis handle plugin -->
    <script type="text/javascript" src="../node_modules/flot-axishandle-plugin/dist/es5/jquery.flot.axishandle.js"></script>

    Run the plot function and pass axis handle options.

    var myFlot = $.plot( $("#graph"), ...,
    {
        ...
        axisHandles: [
            // the handle is shown at the right of the chart. we can move it vertically.
            { orientation: 'vertical', location: 'far' }
        ]
        ...
    });
     

    Thumb plugin

    API Documentation for thumb plugin is available here: Thumb plugin documentation

    Install

    npm i flot-axishandle-plugin

    DownloadsWeekly Downloads

    81

    Version

    2.0.4

    License

    MIT

    Unpacked Size

    24.3 kB

    Total Files

    5

    Last publish

    Collaborators

    • ni-webapps-ops