Rest-HtmlVis

 view release on metacpan or  search on metacpan

share/flot/API.md  view on Meta::CPAN

set it to 0 to prevent a line or outline from being drawn; this will
also hide the shadow.

"fill" is whether the shape should be filled. For lines, this produces
area graphs. You can use "fillColor" to specify the color of the fill.
If "fillColor" evaluates to false (default for everything except
points which are filled with white), the fill color is auto-set to the
color of the data series. You can adjust the opacity of the fill by
setting fill to a number between 0 (fully transparent) and 1 (fully
opaque).

For bars, fillColor can be a gradient, see the gradient documentation
below. "barWidth" is the width of the bars in units of the x axis (or
the y axis if "horizontal" is true), contrary to most other measures
that are specified in pixels. For instance, for time series the unit
is milliseconds so 24 * 60 * 60 * 1000 produces bars with the width of
a day. "align" specifies whether a bar should be left-aligned
(default), right-aligned or centered on top of the value it represents. 
When "horizontal" is on, the bars are drawn horizontally, i.e. from the 
y axis instead of the x axis; note that the bar end points are still
defined in the same way so you'll probably want to swap the
coordinates if you've been plotting vertical bars first.

Area and bar charts normally start from zero, regardless of the data's range.
This is because they convey information through size, and starting from a
different value would distort their meaning. In cases where the fill is purely
for decorative purposes, however, "zero" allows you to override this behavior.
It defaults to true for filled lines and bars; setting it to false tells the
series to use the same automatic scaling as an un-filled line.

For lines, "steps" specifies whether two adjacent data points are
connected with a straight (possibly diagonal) line or with first a
horizontal and then a vertical line. Note that this transforms the
data by adding extra points.

For points, you can specify the radius and the symbol. The only
built-in symbol type is circles, for other types you can use a plugin
or define them yourself by specifying a callback:

```js
function cross(ctx, x, y, radius, shadow) {
    var size = radius * Math.sqrt(Math.PI) / 2;
    ctx.moveTo(x - size, y - size);
    ctx.lineTo(x + size, y + size);
    ctx.moveTo(x - size, y + size);
    ctx.lineTo(x + size, y - size);
}
```

The parameters are the drawing context, x and y coordinates of the
center of the point, a radius which corresponds to what the circle
would have used and whether the call is to draw a shadow (due to
limited canvas support, shadows are currently faked through extra
draws). It's good practice to ensure that the area covered by the
symbol is the same as for the circle with the given radius, this
ensures that all symbols have approximately the same visual weight.

"shadowSize" is the default size of shadows in pixels. Set it to 0 to
remove shadows.

"highlightColor" is the default color of the translucent overlay used
to highlight the series when the mouse hovers over it.

The "colors" array specifies a default color theme to get colors for
the data series from. You can specify as many colors as you like, like
this:

```js
colors: ["#d18b2c", "#dba255", "#919733"]
```

If there are more data series than colors, Flot will try to generate
extra colors by lightening and darkening colors in the theme.


## Customizing the grid ##

```js
grid: {
    show: boolean
    aboveData: boolean
    color: color
    backgroundColor: color/gradient or null
    margin: number or margin object
    labelMargin: number
    axisMargin: number
    markings: array of markings or (fn: axes -> array of markings)
    borderWidth: number or object with "top", "right", "bottom" and "left" properties with different widths
    borderColor: color or null or object with "top", "right", "bottom" and "left" properties with different colors
    minBorderMargin: number or null
    clickable: boolean
    hoverable: boolean
    autoHighlight: boolean
    mouseActiveRadius: number
}

interaction: {
    redrawOverlayInterval: number or -1
}
```

The grid is the thing with the axes and a number of ticks. Many of the
things in the grid are configured under the individual axes, but not
all. "color" is the color of the grid itself whereas "backgroundColor"
specifies the background color inside the grid area, here null means
that the background is transparent. You can also set a gradient, see
the gradient documentation below.

You can turn off the whole grid including tick labels by setting
"show" to false. "aboveData" determines whether the grid is drawn
above the data or below (below is default).

"margin" is the space in pixels between the canvas edge and the grid,
which can be either a number or an object with individual margins for
each side, in the form:

```js
margin: {
    top: top margin in pixels
    left: left margin in pixels
    bottom: bottom margin in pixels

share/flot/API.md  view on Meta::CPAN

    show: true,
    lineWidth: 0,
    fill: true,
    fillColor: { colors: [ { opacity: 0.8 }, { opacity: 0.1 } ] }
}
```

Flot currently only supports vertical gradients drawn from top to
bottom because that's what works with IE.


## Plot Methods ##

The Plot object returned from the plot function has some methods you
can call:

 - highlight(series, datapoint)

    Highlight a specific datapoint in the data series. You can either
    specify the actual objects, e.g. if you got them from a
    "plotclick" event, or you can specify the indices, e.g.
    highlight(1, 3) to highlight the fourth point in the second series
    (remember, zero-based indexing).

 - unhighlight(series, datapoint) or unhighlight()

    Remove the highlighting of the point, same parameters as
    highlight.

    If you call unhighlight with no parameters, e.g. as
    plot.unhighlight(), all current highlights are removed.

 - setData(data)

    You can use this to reset the data used. Note that axis scaling,
    ticks, legend etc. will not be recomputed (use setupGrid() to do
    that). You'll probably want to call draw() afterwards.

    You can use this function to speed up redrawing a small plot if
    you know that the axes won't change. Put in the new data with
    setData(newdata), call draw(), and you're good to go. Note that
    for large datasets, almost all the time is consumed in draw()
    plotting the data so in this case don't bother.

 - setupGrid()

    Recalculate and set axis scaling, ticks, legend etc.

    Note that because of the drawing model of the canvas, this
    function will immediately redraw (actually reinsert in the DOM)
    the labels and the legend, but not the actual tick lines because
    they're drawn on the canvas. You need to call draw() to get the
    canvas redrawn.

 - draw()

    Redraws the plot canvas.

 - triggerRedrawOverlay()

    Schedules an update of an overlay canvas used for drawing
    interactive things like a selection and point highlights. This
    is mostly useful for writing plugins. The redraw doesn't happen
    immediately, instead a timer is set to catch multiple successive
    redraws (e.g. from a mousemove). You can get to the overlay by
    setting up a drawOverlay hook.

 - width()/height()

    Gets the width and height of the plotting area inside the grid.
    This is smaller than the canvas or placeholder dimensions as some
    extra space is needed (e.g. for labels).

 - offset()

    Returns the offset of the plotting area inside the grid relative
    to the document, useful for instance for calculating mouse
    positions (event.pageX/Y minus this offset is the pixel position
    inside the plot).

 - pointOffset({ x: xpos, y: ypos })

    Returns the calculated offset of the data point at (x, y) in data
    space within the placeholder div. If you are working with multiple
    axes, you can specify the x and y axis references, e.g. 

    ```js
      o = pointOffset({ x: xpos, y: ypos, xaxis: 2, yaxis: 3 })
      // o.left and o.top now contains the offset within the div
    ````

 - resize()

    Tells Flot to resize the drawing canvas to the size of the
    placeholder. You need to run setupGrid() and draw() afterwards as
    canvas resizing is a destructive operation. This is used
    internally by the resize plugin.

 - shutdown()

    Cleans up any event handlers Flot has currently registered. This
    is used internally.

There are also some members that let you peek inside the internal
workings of Flot which is useful in some cases. Note that if you change
something in the objects returned, you're changing the objects used by
Flot to keep track of its state, so be careful.

  - getData()

    Returns an array of the data series currently used in normalized
    form with missing settings filled in according to the global
    options. So for instance to find out what color Flot has assigned
    to the data series, you could do this:

    ```js
    var series = plot.getData();
    for (var i = 0; i < series.length; ++i)
        alert(series[i].color);
    ```

    A notable other interesting field besides color is datapoints
    which has a field "points" with the normalized data points in a
    flat array (the field "pointsize" is the increment in the flat
    array to get to the next point so for a dataset consisting only of

share/flot/API.md  view on Meta::CPAN

    Note that you must leave datapoints in a good condition as Flot
    doesn't check it or do any normalization on it afterwards.

 - processOffset  [phase 4]

    ```function(plot, offset)```

    Called after Flot has initialized the plot's offset, but before it
    draws any axes or plot elements. This hook is useful for customizing
    the margins between the grid and the edge of the canvas. "offset" is
    an object with attributes "top", "bottom", "left" and "right",
    corresponding to the margins on the four sides of the plot.

 - drawBackground [phase 5]

    ```function(plot, canvascontext)```

    Called before all other drawing operations. Used to draw backgrounds
    or other custom elements before the plot or axes have been drawn.

 - drawSeries  [phase 5]

    ```function(plot, canvascontext, series)```

    Hook for custom drawing of a single series. Called just before the
    standard drawing routine has been called in the loop that draws
    each series.

 - draw  [phase 5]

    ```function(plot, canvascontext)```

    Hook for drawing on the canvas. Called after the grid is drawn
    (unless it's disabled or grid.aboveData is set) and the series have
    been plotted (in case any points, lines or bars have been turned
    on). For examples of how to draw things, look at the source code.

 - bindEvents  [phase 6]

    ```function(plot, eventHolder)```

    Called after Flot has setup its event handlers. Should set any
    necessary event handlers on eventHolder, a jQuery object with the
    canvas, e.g.

    ```js
    function (plot, eventHolder) {
        eventHolder.mousedown(function (e) {
            alert("You pressed the mouse at " + e.pageX + " " + e.pageY);
        });
    }
    ```

    Interesting events include click, mousemove, mouseup/down. You can
    use all jQuery events. Usually, the event handlers will update the
    state by drawing something (add a drawOverlay hook and call
    triggerRedrawOverlay) or firing an externally visible event for
    user code. See the crosshair plugin for an example.
     
    Currently, eventHolder actually contains both the static canvas
    used for the plot itself and the overlay canvas used for
    interactive features because some versions of IE get the stacking
    order wrong. The hook only gets one event, though (either for the
    overlay or for the static canvas).

    Note that custom plot events generated by Flot are not generated on
    eventHolder, but on the div placeholder supplied as the first
    argument to the plot call. You can get that with
    plot.getPlaceholder() - that's probably also the one you should use
    if you need to fire a custom event.

 - drawOverlay  [phase 7]

    ```function (plot, canvascontext)```

    The drawOverlay hook is used for interactive things that need a
    canvas to draw on. The model currently used by Flot works the way
    that an extra overlay canvas is positioned on top of the static
    canvas. This overlay is cleared and then completely redrawn
    whenever something interesting happens. This hook is called when
    the overlay canvas is to be redrawn.

    "canvascontext" is the 2D context of the overlay canvas. You can
    use this to draw things. You'll most likely need some of the
    metrics computed by Flot, e.g. plot.width()/plot.height(). See the
    crosshair plugin for an example.

 - shutdown  [phase 8]

    ```function (plot, eventHolder)```

    Run when plot.shutdown() is called, which usually only happens in
    case a plot is overwritten by a new plot. If you're writing a
    plugin that adds extra DOM elements or event handlers, you should
    add a callback to clean up after you. Take a look at the section in
    the [PLUGINS](PLUGINS.md) document for more info.

   
## Plugins ##

Plugins extend the functionality of Flot. To use a plugin, simply
include its Javascript file after Flot in the HTML page.

If you're worried about download size/latency, you can concatenate all
the plugins you use, and Flot itself for that matter, into one big file
(make sure you get the order right), then optionally run it through a
Javascript minifier such as YUI Compressor.

Here's a brief explanation of how the plugin plumbings work:

Each plugin registers itself in the global array $.plot.plugins. When
you make a new plot object with $.plot, Flot goes through this array
calling the "init" function of each plugin and merging default options
from the "option" attribute of the plugin. The init function gets a
reference to the plot object created and uses this to register hooks
and add new public methods if needed.

See the [PLUGINS](PLUGINS.md) document for details on how to write a plugin. As the
above description hints, it's actually pretty easy.


## Version number ##

The version number of Flot is available in ```$.plot.version```.