Commit 04db4541 authored by Tino Dietel's avatar Tino Dietel Committed by Clemens John

updating flot to 0.8.3

parent 97c4ea91
## Contributing to Flot ##
We welcome all contributions, but following these guidelines results in less
work for us, and a faster and better response.
### Issues ###
Issues are not a way to ask general questions about Flot. If you see unexpected
behavior but are not 100% certain that it is a bug, please try posting to the
[forum](http://groups.google.com/group/flot-graphs) first, and confirm that
what you see is really a Flot problem before creating a new issue for it. When
reporting a bug, please include a working demonstration of the problem, if
possible, or at least a clear description of the options you're using and the
environment (browser and version, jQuery version, other libraries) that you're
running under.
If you have suggestions for new features, or changes to existing ones, we'd
love to hear them! Please submit each suggestion as a separate new issue.
If you would like to work on an existing issue, please make sure it is not
already assigned to someone else. If an issue is assigned to someone, that
person has already started working on it. So, pick unassigned issues to prevent
duplicated effort.
### Pull Requests ###
To make merging as easy as possible, please keep these rules in mind:
1. Submit new features or architectural changes to the *<version>-work*
branch for the next major release. Submit bug fixes to the master branch.
2. Divide larger changes into a series of small, logical commits with
descriptive messages.
3. Rebase, if necessary, before submitting your pull request, to reduce the
work we need to do to merge it.
4. Format your code according to the style guidelines below.
### Flot Style Guidelines ###
Flot follows the [jQuery Core Style Guidelines](http://docs.jquery.com/JQuery_Core_Style_Guidelines),
with the following updates and exceptions:
#### Spacing ####
Use four-space indents, no tabs. Do not add horizontal space around parameter
lists, loop definitions, or array/object indices. For example:
```js
for ( var i = 0; i < data.length; i++ ) { // This block is wrong!
if ( data[ i ] > 1 ) {
data[ i ] = 2;
}
}
for (var i = 0; i < data.length; i++) { // This block is correct!
if (data[i] > 1) {
data[i] = 2;
}
}
```
#### Comments ####
Use [jsDoc](http://usejsdoc.org) comments for all file and function headers.
Use // for all inline and block comments, regardless of length.
All // comment blocks should have an empty line above *and* below them. For
example:
```js
var a = 5;
// We're going to loop here
// TODO: Make this loop faster, better, stronger!
for (var x = 0; x < 10; x++) {}
```
#### Wrapping ####
Block comments should be wrapped at 80 characters.
Code should attempt to wrap at 80 characters, but may run longer if wrapping
would hurt readability more than having to scroll horizontally. This is a
judgement call made on a situational basis.
Statements containing complex logic should not be wrapped arbitrarily if they
do not exceed 80 characters. For example:
```js
if (a == 1 && // This block is wrong!
b == 2 &&
c == 3) {}
if (a == 1 && b == 2 && c == 3) {} // This block is correct!
```
Frequently asked questions
--------------------------
## Frequently asked questions ##
Q: How much data can Flot cope with?
#### How much data can Flot cope with? ####
A: Flot will happily draw everything you send to it so the answer
Flot will happily draw everything you send to it so the answer
depends on the browser. The excanvas emulation used for IE (built with
VML) makes IE by far the slowest browser so be sure to test with that
if IE users are in your target group.
if IE users are in your target group (for large plots in IE, you can
also check out Flashcanvas which may be faster).
1000 points is not a problem, but as soon as you start having more
points than the pixel width, you should probably start thinking about
......@@ -14,35 +14,36 @@ downsampling/aggregation as this is near the resolution limit of the
chart anyway. If you downsample server-side, you also save bandwidth.
Q: Flot isn't working when I'm using JSON data as source!
#### Flot isn't working when I'm using JSON data as source! ####
A: Actually, Flot loves JSON data, you just got the format wrong.
Actually, Flot loves JSON data, you just got the format wrong.
Double check that you're not inputting strings instead of numbers,
like [["0", "-2.13"], ["5", "4.3"]]. This is most common mistake, and
the error might not show up immediately because Javascript can do some
conversion automatically.
Q: Can I export the graph?
#### Can I export the graph? ####
A: This is a limitation of the canvas technology. There's a hook in
the canvas object for getting an image out, but you won't get the tick
labels. And it's not likely to be supported by IE. At this point, your
best bet is probably taking a screenshot, e.g. with PrtScn.
You can grab the image rendered by the canvas element used by Flot
as a PNG or JPEG (remember to set a background). Note that it won't
include anything not drawn in the canvas (such as the legend). And it
doesn't work with excanvas which uses VML, but you could try
Flashcanvas.
Q: The bars are all tiny in time mode?
#### The bars are all tiny in time mode? ####
A: It's not really possible to determine the bar width automatically.
It's not really possible to determine the bar width automatically.
So you have to set the width with the barWidth option which is NOT in
pixels, but in the units of the x axis (or the y axis for horizontal
bars). For time mode that's milliseconds so the default value of 1
makes the bars 1 millisecond wide.
Q: Can I use Flot with libraries like Mootools or Prototype?
#### Can I use Flot with libraries like Mootools or Prototype? ####
A: Yes, Flot supports it out of the box and it's easy! Just use jQuery
Yes, Flot supports it out of the box and it's easy! Just use jQuery
instead of $, e.g. call jQuery.plot instead of $.plot and use
jQuery(something) instead of $(something). As a convenience, you can
put in a DOM element for the graph placeholder where the examples and
......@@ -54,13 +55,11 @@ libraries, see the documentation in jQuery ("Using jQuery with other
libraries") for details.
Q: Flot doesn't work with [insert name of Javascript UI framework]!
#### Flot doesn't work with [insert name of Javascript UI framework]! ####
A: The only non-standard thing used by Flot is the canvas tag;
otherwise it is simply a series of absolute positioned divs within the
placeholder tag you put in. If this is not working, it's probably
because the framework you're using is doing something weird with the
DOM, or you're using it the wrong way.
Flot is using standard HTML to make charts. If this is not working,
it's probably because the framework you're using is doing something
weird with the DOM or with the CSS that is interfering with Flot.
A common problem is that there's display:none on a container until the
user does something. Many tab widgets work this way, and there's
......
Copyright (c) 2007-2009 IOLA and Ole Laursen
Copyright (c) 2007-2014 IOLA and Ole Laursen
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
......
......@@ -7,3 +7,6 @@ all: $(patsubst %.js,%.min.js,$(filter-out %.min.js,$(wildcard *.js)))
%.min.js: %.js
yui-compressor $< -o $@
test:
./node_modules/.bin/jshint *jquery.flot.js
This diff is collapsed.
This diff is collapsed.
Writing plugins
---------------
## Writing plugins ##
All you need to do to make a new plugin is creating an init function
and a set of options (if needed), stuffing it into an object and
putting it in the $.plot.plugins array. For example:
function myCoolPluginInit(plot) {
```js
function myCoolPluginInit(plot) {
plot.coolstring = "Hello!";
};
};
$.plot.plugins.push({ init: myCoolPluginInit, options: { ... } });
$.plot.plugins.push({ init: myCoolPluginInit, options: { ... } });
// if $.plot is called, it will return a plot object with the
// attribute "coolstring"
// if $.plot is called, it will return a plot object with the
// attribute "coolstring"
```
Now, given that the plugin might run in many different places, it's
a good idea to avoid leaking names. The usual trick here is wrap the
......@@ -21,53 +22,56 @@ this: (function () { inner code ... })(). To make it even more robust
in case $ is not bound to jQuery but some other Javascript library, we
can write it as
(function ($) {
```js
(function ($) {
// plugin definition
// ...
})(jQuery);
})(jQuery);
```
There's a complete example below, but you should also check out the
plugins bundled with Flot.
Complete example
----------------
## Complete example ##
Here is a simple debug plugin which alerts each of the series in the
plot. It has a single option that control whether it is enabled and
how much info to output:
(function ($) {
```js
(function ($) {
function init(plot) {
var debugLevel = 1;
function checkDebugEnabled(plot, options) {
if (options.debug) {
debugLevel = options.debug;
plot.hooks.processDatapoints.push(alertSeries);
var debugLevel = 1;
function checkDebugEnabled(plot, options) {
if (options.debug) {
debugLevel = options.debug;
plot.hooks.processDatapoints.push(alertSeries);
}
}
function alertSeries(plot, series, datapoints) {
var msg = "series " + series.label;
if (debugLevel > 1) {
msg += " with " + series.data.length + " points";
alert(msg);
}
}
}
function alertSeries(plot, series, datapoints) {
var msg = "series " + series.label;
if (debugLevel > 1)
msg += " with " + series.data.length + " points";
alert(msg);
}
plot.hooks.processOptions.push(checkDebugEnabled);
plot.hooks.processOptions.push(checkDebugEnabled);
}
var options = { debug: 0 };
$.plot.plugins.push({
init: init,
options: options,
name: "simpledebug",
version: "0.1"
});
})(jQuery);
})(jQuery);
```
We also define "name" and "version". It's not used by Flot, but might
be helpful for other plugins in resolving dependencies.
......@@ -75,7 +79,9 @@ be helpful for other plugins in resolving dependencies.
Put the above in a file named "jquery.flot.debug.js", include it in an
HTML page and then it can be used with:
$.plot($("#placeholder"), [...], { debug: 2 });
```js
$.plot($("#placeholder"), [...], { debug: 2 });
```
This simple plugin illustrates a couple of points:
......@@ -88,8 +94,7 @@ The two last points are important because there may be multiple plots
on the same page, and you'd want to make sure they are not mixed up.
Shutting down a plugin
----------------------
## Shutting down a plugin ##
Each plot object has a shutdown hook which is run when plot.shutdown()
is called. This usually mostly happens in case another plot is made on
......@@ -107,8 +112,7 @@ garbage collected yet, and worse, if your handler eventually runs, it
may overwrite stuff on a completely different plot.
Some hints on the options
-------------------------
## Some hints on the options ##
Plugins should always support appropriate options to enable/disable
them because the plugin user may have several plots on the same page
......@@ -120,14 +124,16 @@ If the plugin needs options that are specific to each series, like the
points or lines options in core Flot, you can put them in "series" in
the options object, e.g.
var options = {
```js
var options = {
series: {
downsample: {
algorithm: null,
maxpoints: 1000
}
downsample: {
algorithm: null,
maxpoints: 1000
}
}
}
}
```
Then they will be copied by Flot into each series, providing default
values in case none are specified.
......
About
-----
# Flot [![Build status](https://travis-ci.org/flot/flot.png)](https://travis-ci.org/flot/flot)
Flot is a Javascript plotting library for jQuery. Read more at the
website:
## About ##
http://code.google.com/p/flot/
Flot is a Javascript plotting library for jQuery.
Read more at the website: <http://www.flotcharts.org/>
Take a look at the examples linked from above, they should give a good
impression of what Flot can do and the source code of the examples is
probably the fastest way to learn how to use Flot.
Take a look at the the examples in examples/index.html; they should give a good
impression of what Flot can do, and the source code of the examples is probably
the fastest way to learn how to use Flot.
Installation
------------
## Installation ##
Just include the Javascript file after you've included jQuery.
Generally, all browsers that support the HTML5 canvas tag are
supported.
For support for Internet Explorer < 9, you can use Excanvas, a canvas
emulator; this is used in the examples bundled with Flot. You just
include the excanvas script like this:
For support for Internet Explorer < 9, you can use [Excanvas]
[excanvas], a canvas emulator; this is used in the examples bundled
with Flot. You just include the excanvas script like this:
<!--[if lte IE 8]><script language="javascript" type="text/javascript" src="excanvas.min.js"></script><![endif]-->
```html
<!--[if lte IE 8]><script language="javascript" type="text/javascript" src="excanvas.min.js"></script><![endif]-->
```
If it's not working on your development IE 6.0, check that it has
support for VML which Excanvas is relying on. It appears that some
stripped down versions used for test environments on virtual machines
lack the VML support.
You can also try using Flashcanvas (see
http://code.google.com/p/flashcanvas/), which uses Flash to do the
emulation. Although Flash can be a bit slower to load than VML, if
you've got a lot of points, the Flash version can be much faster
You can also try using [Flashcanvas][flashcanvas], which uses Flash to
do the emulation. Although Flash can be a bit slower to load than VML,
if you've got a lot of points, the Flash version can be much faster
overall. Flot contains some wrapper code for activating Excanvas which
Flashcanvas is compatible with.
......@@ -41,18 +40,21 @@ You need at least jQuery 1.2.6, but try at least 1.3.2 for interactive
charts because of performance improvements in event handling.
Basic usage
-----------
## Basic usage ##
Create a placeholder div to put the graph in:
<div id="placeholder"></div>
```html
<div id="placeholder"></div>
```
You need to set the width and height of this div, otherwise the plot
library doesn't know how to scale the graph. You can do it inline like
this:
<div id="placeholder" style="width:600px;height:300px"></div>
```html
<div id="placeholder" style="width:600px;height:300px"></div>
```
You can also do it with an external stylesheet. Make sure that the
placeholder isn't within something with a display:none CSS property -
......@@ -63,28 +65,46 @@ placeholder dimensions which is fatal (it'll throw an exception).
Then when the div is ready in the DOM, which is usually on document
ready, run the plot function:
$.plot($("#placeholder"), data, options);
```js
$.plot($("#placeholder"), data, options);
```
Here, data is an array of data series and options is an object with
settings if you want to customize the plot. Take a look at the
examples for some ideas of what to put in or look at the reference
in the file "API.txt". Here's a quick example that'll draw a line from
(0, 0) to (1, 1):
examples for some ideas of what to put in or look at the
[API reference](API.md). Here's a quick example that'll draw a line
from (0, 0) to (1, 1):
$.plot($("#placeholder"), [ [[0, 0], [1, 1]] ], { yaxis: { max: 1 } });
```js
$.plot($("#placeholder"), [ [[0, 0], [1, 1]] ], { yaxis: { max: 1 } });
```
The plot function immediately draws the chart and then returns a plot
object with a couple of methods.
What's with the name?
---------------------
## What's with the name? ##
First: it's pronounced with a short o, like "plot". Not like "flawed".
So "Flot" rhymes with "plot".
And if you look up "flot" in a Danish-to-English dictionary, some up
And if you look up "flot" in a Danish-to-English dictionary, some of
the words that come up are "good-looking", "attractive", "stylish",
"smart", "impressive", "extravagant". One of the main goals with Flot
is pretty looks.
## Notes about the examples ##
In order to have a useful, functional example of time-series plots using time
zones, date.js from [timezone-js][timezone-js] (released under the Apache 2.0
license) and the [Olson][olson] time zone database (released to the public
domain) have been included in the examples directory. They are used in
examples/axes-time-zones/index.html.
[excanvas]: http://code.google.com/p/explorercanvas/
[flashcanvas]: http://code.google.com/p/flashcanvas/
[timezone-js]: https://github.com/mde/timezone-js
[olson]: http://ftp.iana.org/time-zones
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Flot Examples</title>
<link href="layout.css" rel="stylesheet" type="text/css">
<!--[if lte IE 8]><script language="javascript" type="text/javascript" src="../excanvas.min.js"></script><![endif]-->
<script language="javascript" type="text/javascript" src="../jquery.js"></script>
<script language="javascript" type="text/javascript" src="../jquery.flot.js"></script>
</head>
<body>
<h1>Flot Examples</h1>
<div id="placeholder" style="width:600px;height:300px;"></div>
<p>Example of loading data dynamically with AJAX. Percentage change in GDP (source: <a href="http://epp.eurostat.ec.europa.eu/tgm/table.do?tab=table&init=1&plugin=1&language=en&pcode=tsieb020">Eurostat</a>). Click the buttons below.</p>
<p>The data is fetched over HTTP, in this case directly from text
files. Usually the URL would point to some web server handler
(e.g. a PHP page or Java/.NET/Python/Ruby on Rails handler) that
extracts it from a database and serializes it to JSON.</p>
<p>
<input class="fetchSeries" type="button" value="First dataset"> -
<a href="data-eu-gdp-growth.json">data</a> -
<span></span>
</p>
<p>
<input class="fetchSeries" type="button" value="Second dataset"> -
<a href="data-japan-gdp-growth.json">data</a> -
<span></span>
</p>
<p>
<input class="fetchSeries" type="button" value="Third dataset"> -
<a href="data-usa-gdp-growth.json">data</a> -
<span></span>
</p>
<p>If you combine AJAX with setTimeout, you can poll the server
for new data.</p>
<p>
<input class="dataUpdate" type="button" value="Poll for data">
</p>
<script type="text/javascript">
$(function () {
var options = {
lines: { show: true },
points: { show: true },
xaxis: { tickDecimals: 0, tickSize: 1 }
};
var data = [];
var placeholder = $("#placeholder");
$.plot(placeholder, data, options);
// fetch one series, adding to what we got
var alreadyFetched = {};
$("input.fetchSeries").click(function () {
var button = $(this);
// find the URL in the link right next to us
var dataurl = button.siblings('a').attr('href');
// then fetch the data with jQuery
function onDataReceived(series) {
// extract the first coordinate pair so you can see that
// data is now an ordinary Javascript object
var firstcoordinate = '(' + series.data[0][0] + ', ' + series.data[0][1] + ')';
button.siblings('span').text('Fetched ' + series.label + ', first point: ' + firstcoordinate);
// let's add it to our current data
if (!alreadyFetched[series.label]) {
alreadyFetched[series.label] = true;
data.push(series);
}
// and plot all we got
$.plot(placeholder, data, options);
}
$.ajax({
url: dataurl,
method: 'GET',
dataType: 'json',
success: onDataReceived
});
});
// initiate a recurring data update
$("input.dataUpdate").click(function () {
// reset data
data = [];
alreadyFetched = {};
$.plot(placeholder, data, options);
var iteration = 0;
function fetchData() {
++iteration;
function onDataReceived(series) {
// we get all the data in one go, if we only got partial
// data, we could merge it with what we already got
data = [ series ];
$.plot($("#placeholder"), data, options);
}
$.ajax({
// usually, we'll just call the same URL, a script
// connected to a database, but in this case we only
// have static example files so we need to modify the
// URL
url: "data-eu-gdp-growth-" + iteration + ".json",
method: 'GET',
dataType: 'json',
success: onDataReceived
});
if (iteration < 5)
setTimeout(fetchData, 1000);
else {
data = [];
alreadyFetched = {};
}
}
setTimeout(fetchData, 1000);
});
});
</script>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Flot Examples</title>
<link href="layout.css" rel="stylesheet" type="text/css">
<!--[if lte IE 8]><script language="javascript" type="text/javascript" src="../excanvas.min.js"></script><![endif]-->
<script language="javascript" type="text/javascript" src="../jquery.js"></script>
<script language="javascript" type="text/javascript" src="../jquery.flot.js"></script>
</head>
<body>
<h1>Flot Examples</h1>
<div id="placeholder" style="width:600px;height:300px;"></div>
<p>Flot has support for simple background decorations such as
lines and rectangles. They can be useful for marking up certain
areas. You can easily add any HTML you need with standard DOM
manipulation, e.g. for labels. For drawing custom shapes there is
also direct access to the canvas.</p>
<script type="text/javascript">
$(function () {
// generate a dataset
var d1 = [];
for (var i = 0; i < 20; ++i)
d1.push([i, Math.sin(i)]);
var data = [{ data: d1, label: "Pressure", color: "#333" }];
// setup background areas
var markings = [
{ color: '#f6f6f6', yaxis: { from: 1 } },
{ color: '#f6f6f6', yaxis: { to: -1 } },
{ color: '#000', lineWidth: 1, xaxis: { from: 2, to: 2 } },
{ color: '#000', lineWidth: 1, xaxis: { from: 8, to: 8 } }
];
var placeholder = $("#placeholder");
// plot it
var plot = $.plot(placeholder, data, {
bars: { show: true, barWidth: 0.5, fill: 0.9 },
xaxis: { ticks: [], autoscaleMargin: 0.02 },
yaxis: { min: -2, max: 2 },
grid: { markings: markings }
});
// add labels
var o;
o = plot.pointOffset({ x: 2, y: -1.2});
// we just append it to the placeholder which Flot already uses
// for positioning
placeholder.append('<div style="position:absolute;left:' + (o.left + 4) + 'px;top:' + o.top + 'px;color:#666;font-size:smaller">Warming up</div>');
o = plot.pointOffset({ x: 8, y: -1.2});
placeholder.append('<div style="position:absolute;left:' + (o.left + 4) + 'px;top:' + o.top + 'px;color:#666;font-size:smaller">Actual measurements</div>');
// draw a little arrow on top of the last label to demonstrate
// canvas drawing
var ctx = plot.getCanvas().getContext("2d");
ctx.beginPath();
o.left += 4;
ctx.moveTo(o.left, o.top);
ctx.lineTo(o.left, o.top - 10);
ctx.lineTo(o.left + 10, o.top - 5);
ctx.lineTo(o.left, o.top);
ctx.fillStyle = "#000";
ctx.fill();
});