gitphp 0.2.9.1 :: bus.git/blame

2011-02-22 02:49:20

maxious

Flot Reference

--------------

Consider a call to the plot function:

5

6

var plot = $.plot(placeholder, data, options)

7

8

The placeholder is a jQuery object or DOM element or jQuery expression

9

that the plot will be put into. This placeholder needs to have its

10

width and height set as explained in the README (go read that now if

11

you haven't, it's short). The plot will modify some properties of the

12

placeholder so it's recommended you simply pass in a div that you

13

don't use for anything else. Make sure you check any fancy styling

14

you apply to the div, e.g. background images have been reported to be a

15

problem on IE 7.

16

17

The format of the data is documented below, as is the available

18

options. The "plot" object returned has some methods you can call.

19

These are documented separately below.

20

21

Note that in general Flot gives no guarantees if you change any of the

22

objects you pass in to the plot function or get out of it since

23

they're not necessarily deep-copied.

Data Format

-----------

The data is an array of data series:

30

31

[ series1, series2, ... ]

32

33

A series can either be raw data or an object with properties. The raw

34

data format is an array of points:

35

36

[ [x1, y1], [x2, y2], ... ]

E.g.

[ [1, 3], [2, 14.01], [3.5, 3.14] ]

41

42

Note that to simplify the internal logic in Flot both the x and y

43

values must be numbers (even if specifying time series, see below for

44

how to do this). This is a common problem because you might retrieve

45

data from the database and serialize them directly to JSON without

46

noticing the wrong type. If you're getting mysterious errors, double

47

check that you're inputting numbers and not strings.

48

49

If a null is specified as a point or if one of the coordinates is null

50

or couldn't be converted to a number, the point is ignored when

51

drawing. As a special case, a null value for lines is interpreted as a

52

line segment end, i.e. the points before and after the null value are

53

not connected.

54

55

Lines and points take two coordinates. For bars, you can specify a

56

third coordinate which is the bottom of the bar (defaults to 0).

57

58

The format of a single series object is as follows:

59

60

{

61

color: color or number

62

data: rawdata

63

label: string

64

lines: specific lines options

65

bars: specific bars options

66

points: specific points options

xaxis: 1 or 2

yaxis: 1 or 2

clickable: boolean

hoverable: boolean

shadowSize: number

}

You don't have to specify any of them except the data, the rest are

75

options that will get default values. Typically you'd only specify

76

label and data, like this:

{

label: "y = 3",

data: [[0, 3], [10, 3]]

81

}

82

83

The label is used for the legend, if you don't specify one, the series

84

will not show up in the legend.

85

86

If you don't specify color, the series will get a color from the

87

auto-generated colors. The color is either a CSS color specification

88

(like "rgb(255, 100, 123)") or an integer that specifies which of

89

auto-generated colors to select, e.g. 0 will get color no. 0, etc.

90

91

The latter is mostly useful if you let the user add and remove series,

92

in which case you can hard-code the color index to prevent the colors

93

from jumping around between the series.

94

95

The "xaxis" and "yaxis" options specify which axis to use, specify 2

96

to get the secondary axis (x axis at top or y axis to the right).

97

E.g., you can use this to make a dual axis plot by specifying

98

{ yaxis: 2 } for one data series.

99

100

"clickable" and "hoverable" can be set to false to disable

101

interactivity for specific series if interactivity is turned on in

102

the plot, see below.

103

104

The rest of the options are all documented below as they are the same

105

as the default options passed in via the options parameter in the plot

106

commmand. When you specify them for a specific data series, they will

107

override the default options for the plot for that data series.

108

109

Here's a complete example of a simple data specification:

110

111

[ { label: "Foo", data: [ [10, 1], [17, -14], [30, 5] ] },

112

{ label: "Bar", data: [ [11, 13], [19, 11], [30, -7] ] } ]

Plot Options

------------

All options are completely optional. They are documented individually

119

below, to change them you just specify them in an object, e.g.

var options = {

series: {

lines: { show: true },

124

points: { show: true }

}

};

$.plot(placeholder, data, options);

129

130

131

Customizing the legend

132

======================

legend: {

show: boolean

labelFormatter: null or (fn: string, series object -> string)

137

labelBoxBorderColor: color

138

noColumns: number

139

position: "ne" or "nw" or "se" or "sw"

140

margin: number of pixels or [x margin, y margin]

141

backgroundColor: null or color

142

backgroundOpacity: number between 0 and 1

143

container: null or jQuery object/DOM element/jQuery expression

144

}

145

146

The legend is generated as a table with the data series labels and

147

small label boxes with the color of the series. If you want to format

148

the labels in some way, e.g. make them to links, you can pass in a

149

function for "labelFormatter". Here's an example that makes them

150

clickable:

151

152

labelFormatter: function(label, series) {

153

// series is the series object for the label

154

return '<a href="#' + label + '">' + label + '</a>';

155

}

156

157

"noColumns" is the number of columns to divide the legend table into.

158

"position" specifies the overall placement of the legend within the

159

plot (top-right, top-left, etc.) and margin the distance to the plot

160

edge (this can be either a number or an array of two numbers like [x,

161

y]). "backgroundColor" and "backgroundOpacity" specifies the

162

background. The default is a partly transparent auto-detected

163

background.

164

165

If you want the legend to appear somewhere else in the DOM, you can

166

specify "container" as a jQuery object/expression to put the legend

167

table into. The "position" and "margin" etc. options will then be

168

ignored. Note that Flot will overwrite the contents of the container.

Customizing the axes

====================

xaxis, yaxis, x2axis, y2axis: {

mode: null or "time"

min: null or number

max: null or number

autoscaleMargin: null or number

179

180

labelWidth: null or number

181

labelHeight: null or number

182

183

transform: null or fn: number -> number

184

inverseTransform: null or fn: number -> number

185

186

ticks: null or number or ticks array or (fn: range -> ticks array)

187

tickSize: number or array

188

minTickSize: number or array

189

tickFormatter: (fn: number, object -> string) or string

190

tickDecimals: null or number

191

}

192

193

All axes have the same kind of options. The "mode" option

194

determines how the data is interpreted, the default of null means as

195

decimal numbers. Use "time" for time series data, see the next section.

196

197

The options "min"/"max" are the precise minimum/maximum value on the

198

scale. If you don't specify either of them, a value will automatically

199

be chosen based on the minimum/maximum data values.

200

201

The "autoscaleMargin" is a bit esoteric: it's the fraction of margin

202

that the scaling algorithm will add to avoid that the outermost points

203

ends up on the grid border. Note that this margin is only applied

204

when a min or max value is not explicitly set. If a margin is

205

specified, the plot will furthermore extend the axis end-point to the

206

nearest whole tick. The default value is "null" for the x axis and

207

0.02 for the y axis which seems appropriate for most cases.

208

209

"labelWidth" and "labelHeight" specifies a fixed size of the tick

210

labels in pixels. They're useful in case you need to align several

211

plots.

212

213

"transform" and "inverseTransform" are callbacks you can put in to

214

change the way the data is drawn. You can design a function to

215

compress or expand certain parts of the axis non-linearly, e.g.

216

suppress weekends or compress far away points with a logarithm or some

217

other means. When Flot draws the plot, each value is first put through

218

the transform function. Here's an example, the x axis can be turned

219

into a natural logarithm axis with the following code:

220

221

xaxis: {

222

transform: function (v) { return Math.log(v); },

223

inverseTransform: function (v) { return Math.exp(v); }

224

}

225

226

Note that for finding extrema, Flot assumes that the transform

227

function does not reorder values (monotonicity is assumed).

228

229

The inverseTransform is simply the inverse of the transform function

230

(so v == inverseTransform(transform(v)) for all relevant v). It is

231

required for converting from canvas coordinates to data coordinates,

232

e.g. for a mouse interaction where a certain pixel is clicked. If you

233

don't use any interactive features of Flot, you may not need it.

234

235

236

The rest of the options deal with the ticks.

237

238

If you don't specify any ticks, a tick generator algorithm will make

239

some for you. The algorithm has two passes. It first estimates how

240

many ticks would be reasonable and uses this number to compute a nice

241

round tick interval size. Then it generates the ticks.

242

243

You can specify how many ticks the algorithm aims for by setting

244

"ticks" to a number. The algorithm always tries to generate reasonably

245

round tick values so even if you ask for three ticks, you might get

246

five if that fits better with the rounding. If you don't want any

247

ticks at all, set "ticks" to 0 or an empty array.

248

249

Another option is to skip the rounding part and directly set the tick

250

interval size with "tickSize". If you set it to 2, you'll get ticks at

251

2, 4, 6, etc. Alternatively, you can specify that you just don't want

252

ticks at a size less than a specific tick size with "minTickSize".

253

Note that for time series, the format is an array like [2, "month"],

254

see the next section.

255

256

If you want to completely override the tick algorithm, you can specify

257

an array for "ticks", either like this:

ticks: [0, 1.2, 2.4]

Or like this where the labels are also customized:

262

263

ticks: [[0, "zero"], [1.2, "one mark"], [2.4, "two marks"]]

264

265

You can mix the two if you like.

266

267

For extra flexibility you can specify a function as the "ticks"

268

parameter. The function will be called with an object with the axis

269

min and max and should return a ticks array. Here's a simplistic tick

270

generator that spits out intervals of pi, suitable for use on the x

271

axis for trigonometric functions:

272

273

function piTickGenerator(axis) {

274

var res = [], i = Math.floor(axis.min / Math.PI);

275

do {

276

var v = i * Math.PI;

277

res.push([v, i + "\u03c0"]);

278

++i;

279

} while (v < axis.max);

return res;

}

You can control how the ticks look like with "tickDecimals", the

286

number of decimals to display (default is auto-detected).

287

288

Alternatively, for ultimate control over how ticks look like you can

289

provide a function to "tickFormatter". The function is passed two

290

parameters, the tick value and an "axis" object with information, and

291

should return a string. The default formatter looks like this:

292

293

function formatter(val, axis) {

294

return val.toFixed(axis.tickDecimals);

295

}

296

297

The axis object has "min" and "max" with the range of the axis,

298

"tickDecimals" with the number of decimals to round the value to and

299

"tickSize" with the size of the interval between ticks as calculated

300

by the automatic axis scaling algorithm (or specified by you). Here's

301

an example of a custom formatter:

302

303

function suffixFormatter(val, axis) {

304

if (val > 1000000)

305

return (val / 1000000).toFixed(axis.tickDecimals) + " MB";

306

else if (val > 1000)

307

return (val / 1000).toFixed(axis.tickDecimals) + " kB";

308

else

309

return val.toFixed(axis.tickDecimals) + " B";

}

Time series data

================

Time series are a bit more difficult than scalar data because

316

calendars don't follow a simple base 10 system. For many cases, Flot

317

abstracts most of this away, but it can still be a bit difficult to

318

get the data into Flot. So we'll first discuss the data format.

319

320

The time series support in Flot is based on Javascript timestamps,

321

i.e. everywhere a time value is expected or handed over, a Javascript

322

timestamp number is used. This is a number, not a Date object. A

323

Javascript timestamp is the number of milliseconds since January 1,

324

1970 00:00:00 UTC. This is almost the same as Unix timestamps, except it's

325

in milliseconds, so remember to multiply by 1000!

326

327

You can see a timestamp like this

328

329

alert((new Date()).getTime())

330

331

Normally you want the timestamps to be displayed according to a

332

certain time zone, usually the time zone in which the data has been

333

produced. However, Flot always displays timestamps according to UTC.

334

It has to as the only alternative with core Javascript is to interpret

335

the timestamps according to the time zone that the visitor is in,

336

which means that the ticks will shift unpredictably with the time zone

337

and daylight savings of each visitor.

338

339

So given that there's no good support for custom time zones in

340

Javascript, you'll have to take care of this server-side.

341

342

The easiest way to think about it is to pretend that the data

343

production time zone is UTC, even if it isn't. So if you have a

344

datapoint at 2002-02-20 08:00, you can generate a timestamp for eight

345

o'clock UTC even if it really happened eight o'clock UTC+0200.

346

347

In PHP you can get an appropriate timestamp with

348

'strtotime("2002-02-20 UTC") * 1000', in Python with

349

'calendar.timegm(datetime_object.timetuple()) * 1000', in .NET with

350

something like:

351

352

public static int GetJavascriptTimestamp(System.DateTime input)

353

{

354

System.TimeSpan span = new System.TimeSpan(System.DateTime.Parse("1/1/1970").Ticks);

355

System.DateTime time = input.Subtract(span);

356

return (long)(time.Ticks / 10000);

357

}

358

359

Javascript also has some support for parsing date strings, so it is

360

possible to generate the timestamps manually client-side.

361

362

If you've already got the real UTC timestamp, it's too late to use the

363

pretend trick described above. But you can fix up the timestamps by

364

adding the time zone offset, e.g. for UTC+0200 you would add 2 hours

365

to the UTC timestamp you got. Then it'll look right on the plot. Most

366

programming environments have some means of getting the timezone

367

offset for a specific date (note that you need to get the offset for

368

each individual timestamp to account for daylight savings).

369

370

Once you've gotten the timestamps into the data and specified "time"

371

as the axis mode, Flot will automatically generate relevant ticks and

372

format them. As always, you can tweak the ticks via the "ticks" option

373

- just remember that the values should be timestamps (numbers), not

374

Date objects.

375

376

Tick generation and formatting can also be controlled separately

377

through the following axis options:

378

379

minTickSize: array

380

timeformat: null or format string

381

monthNames: null or array of size 12 of strings

382

twelveHourClock: boolean

383

384

Here "timeformat" is a format string to use. You might use it like

this:

xaxis: {

mode: "time"

timeformat: "%y/%m/%d"

390

}

391

392

This will result in tick labels like "2000/12/24". The following

393

specifiers are supported

394

395

%h: hours

396

%H: hours (left-padded with a zero)

397

%M: minutes (left-padded with a zero)

398

%S: seconds (left-padded with a zero)

399

%d: day of month (1-31)

400

%m: month (1-12)

401

%y: year (four digits)

402

%b: month name (customizable)

403

%p: am/pm, additionally switches %h/%H to 12 hour instead of 24

404

%P: AM/PM (uppercase version of %p)

405

406

You can customize the month names with the "monthNames" option. For

407

instance, for Danish you might specify:

408

409

monthNames: ["jan", "feb", "mar", "apr", "maj", "jun", "jul", "aug", "sep", "okt", "nov", "dec"]

410

411

If you set "twelveHourClock" to true, the autogenerated timestamps

412

will use 12 hour AM/PM timestamps instead of 24 hour.

413

414

The format string and month names are used by a very simple built-in

415

format function that takes a date object, a format string (and

416

optionally an array of month names) and returns the formatted string.

417

If needed, you can access it as $.plot.formatDate(date, formatstring,

418

monthNames) or even replace it with another more advanced function

419

from a date library if you're feeling adventurous.

420

421

If everything else fails, you can control the formatting by specifying

422

a custom tick formatter function as usual. Here's a simple example

423

which will format December 24 as 24/12:

424

425

tickFormatter: function (val, axis) {

426

var d = new Date(val);

427

return d.getUTCDate() + "/" + (d.getUTCMonth() + 1);

428

}

429

430

Note that for the time mode "tickSize" and "minTickSize" are a bit

431

special in that they are arrays on the form "[value, unit]" where unit

432

is one of "second", "minute", "hour", "day", "month" and "year". So

433

you can specify

434

435

minTickSize: [1, "month"]

436

437

to get a tick interval size of at least 1 month and correspondingly,

438

if axis.tickSize is [2, "day"] in the tick formatter, the ticks have

439

been produced with two days in-between.

Customizing the data series

444

===========================

445

446

series: {

447

lines, points, bars: {

448

show: boolean

449

lineWidth: number

450

fill: boolean or number

451

fillColor: null or color/gradient

}

points: {

radius: number

}

bars: {

barWidth: number

align: "left" or "center"

horizontal: boolean

}

lines: {

steps: boolean

}

shadowSize: number

}

colors: [ color1, color2, ... ]

472

473

The options inside "series: {}" are copied to each of the series. So

474

you can specify that all series should have bars by putting it in the

475

global options, or override it for individual series by specifying

476

bars in a particular the series object in the array of data.

477

478

The most important options are "lines", "points" and "bars" that

479

specify whether and how lines, points and bars should be shown for

480

each data series. In case you don't specify anything at all, Flot will

481

default to showing lines (you can turn this off with

482

lines: { show: false}). You can specify the various types

483

independently of each other, and Flot will happily draw each of them

484

in turn (this is probably only useful for lines and points), e.g.

var options = {

series: {

lines: { show: true, fill: true, fillColor: "rgba(255, 255, 255, 0.8)" },

489

points: { show: true, fill: false }

}

};

"lineWidth" is the thickness of the line or outline in pixels. You can

494

set it to 0 to prevent a line or outline from being drawn; this will

495

also hide the shadow.

496

497

"fill" is whether the shape should be filled. For lines, this produces

498

area graphs. You can use "fillColor" to specify the color of the fill.

499

If "fillColor" evaluates to false (default for everything except

500

points which are filled with white), the fill color is auto-set to the

501

color of the data series. You can adjust the opacity of the fill by

502

setting fill to a number between 0 (fully transparent) and 1 (fully

503

opaque).

504

505

For bars, fillColor can be a gradient, see the gradient documentation

506

below. "barWidth" is the width of the bars in units of the x axis (or

507

the y axis if "horizontal" is true), contrary to most other measures

508

that are specified in pixels. For instance, for time series the unit

509

is milliseconds so 24 * 60 * 60 * 1000 produces bars with the width of

510

a day. "align" specifies whether a bar should be left-aligned

511

(default) or centered on top of the value it represents. When

512

"horizontal" is on, the bars are drawn horizontally, i.e. from the y

513

axis instead of the x axis; note that the bar end points are still

514

defined in the same way so you'll probably want to swap the

515

coordinates if you've been plotting vertical bars first.

516

517

For lines, "steps" specifies whether two adjacent data points are

518

connected with a straight (possibly diagonal) line or with first a

519

horizontal and then a vertical line. Note that this transforms the

520

data by adding extra points.

521

522

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

523

remove shadows.

524

525

The "colors" array specifies a default color theme to get colors for

526

the data series from. You can specify as many colors as you like, like

527

this:

528

529

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

530

531

If there are more data series than colors, Flot will try to generate

532

extra colors by lightening and darkening colors in the theme.

Customizing the grid

====================

grid: {

show: boolean

aboveData: boolean

color: color

backgroundColor: color/gradient or null

543

tickColor: color

544

labelMargin: number

545

markings: array of markings or (fn: axes -> array of markings)

546

borderWidth: number

547

borderColor: color or null

548

clickable: boolean

549

hoverable: boolean

550

autoHighlight: boolean

551

mouseActiveRadius: number

552

}

553

554

The grid is the thing with the axes and a number of ticks. "color" is

555

the color of the grid itself whereas "backgroundColor" specifies the

556

background color inside the grid area. The default value of null means

557

that the background is transparent. You can also set a gradient, see

558

the gradient documentation below.

559

560

You can turn off the whole grid including tick labels by setting

561

"show" to false. "aboveData" determines whether the grid is drawn on

562

above the data or below (below is default).

563

564

"tickColor" is the color of the ticks and "labelMargin" is the spacing

565

between tick labels and the grid. Note that you can style the tick

566

labels with CSS, e.g. to change the color. They have class "tickLabel".

567

"borderWidth" is the width of the border around the plot. Set it to 0

568

to disable the border. You can also set "borderColor" if you want the

569

border to have a different color than the grid lines.

570

571

"markings" is used to draw simple lines and rectangular areas in the

572

background of the plot. You can either specify an array of ranges on

573

the form { xaxis: { from, to }, yaxis: { from, to } } (secondary axis

574

coordinates with x2axis/y2axis) or with a function that returns such

575

an array given the axes for the plot in an object as the first

576

parameter.

577

578

You can set the color of markings by specifying "color" in the ranges

579

object. Here's an example array:

580

581

markings: [ { xaxis: { from: 0, to: 2 }, yaxis: { from: 10, to: 10 }, color: "#bb0000" }, ... ]

582

583

If you leave out one of the values, that value is assumed to go to the

584

border of the plot. So for example if you only specify { xaxis: {

585

from: 0, to: 2 } } it means an area that extends from the top to the

586

bottom of the plot in the x range 0-2.

587

588

A line is drawn if from and to are the same, e.g.

589

590

markings: [ { yaxis: { from: 1, to: 1 } }, ... ]

591

592

would draw a line parallel to the x axis at y = 1. You can control the

593

line width with "lineWidth" in the range object.

594

595

An example function might look like this:

596

597

markings: function (axes) {

598

var markings = [];

599

for (var x = Math.floor(axes.xaxis.min); x < axes.xaxis.max; x += 2)

600

markings.push({ xaxis: { from: x, to: x + 1 } });

return markings;

}

If you set "clickable" to true, the plot will listen for click events

606

on the plot area and fire a "plotclick" event on the placeholder with

607

a position and a nearby data item object as parameters. The coordinates

608

are available both in the unit of the axes (not in pixels) and in

609

global screen coordinates.

610

611

Likewise, if you set "hoverable" to true, the plot will listen for

612

mouse move events on the plot area and fire a "plothover" event with

613

the same parameters as the "plotclick" event. If "autoHighlight" is

614

true (the default), nearby data items are highlighted automatically.

615

If needed, you can disable highlighting and control it yourself with

616

the highlight/unhighlight plot methods described elsewhere.

617

618

You can use "plotclick" and "plothover" events like this:

619

620

$.plot($("#placeholder"), [ d ], { grid: { clickable: true } });

621

622

$("#placeholder").bind("plotclick", function (event, pos, item) {

623

alert("You clicked at " + pos.x + ", " + pos.y);

624

// secondary axis coordinates if present are in pos.x2, pos.y2,

625

// if you need global screen coordinates, they are pos.pageX, pos.pageY

626

627

if (item) {

628

highlight(item.series, item.datapoint);

629

alert("You clicked a point!");

}

});

The item object in this example is either null or a nearby object on the form:

634

635

item: {

636

datapoint: the point, e.g. [0, 2]

637

dataIndex: the index of the point in the data array

638

series: the series object

639

seriesIndex: the index of the series

640

pageX, pageY: the global screen coordinates of the point

641

}

642

643

For instance, if you have specified the data like this

644

645

$.plot($("#placeholder"), [ { label: "Foo", data: [[0, 10], [7, 3]] } ], ...);

646

647

and the mouse is near the point (7, 3), "datapoint" is [7, 3],

648

"dataIndex" will be 1, "series" is a normalized series object with

649

among other things the "Foo" label in series.label and the color in

650

series.color, and "seriesIndex" is 0. Note that plugins and options

651

that transform the data can shift the indexes from what you specified

652

in the original data array.

653

654

If you use the above events to update some other information and want

655

to clear out that info in case the mouse goes away, you'll probably

656

also need to listen to "mouseout" events on the placeholder div.

657

658

"mouseActiveRadius" specifies how far the mouse can be from an item

659

and still activate it. If there are two or more points within this

660

radius, Flot chooses the closest item. For bars, the top-most bar

661

(from the latest specified data series) is chosen.

662

663

If you want to disable interactivity for a specific data series, you

664

can set "hoverable" and "clickable" to false in the options for that

665

series, like this { data: [...], label: "Foo", clickable: false }.

Specifying gradients

====================

A gradient is specified like this:

672

673

{ colors: [ color1, color2, ... ] }

674

675

For instance, you might specify a background on the grid going from

676

black to gray like this:

677

678

grid: {

679

backgroundColor: { colors: ["#000", "#999"] }

680

}

681

682

For the series you can specify the gradient as an object that

683

specifies the scaling of the brightness and the opacity of the series

684

color, e.g.

685

686

{ colors: [{ opacity: 0.8 }, { brightness: 0.6, opacity: 0.8 } ] }

687

688

where the first color simply has its alpha scaled, whereas the second

689

is also darkened. For instance, for bars the following makes the bars

690

gradually disappear, without outline:

bars: {

show: true,

lineWidth: 0,

fill: true,

fillColor: { colors: [ { opacity: 0.8 }, { opacity: 0.1 } ] }

697

}

698

699

Flot currently only supports vertical gradients drawn from top to

700

bottom because that's what works with IE.

Plot Methods

------------

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

707

can call:

708

709

- highlight(series, datapoint)

710

711

Highlight a specific datapoint in the data series. You can either

712

specify the actual objects, e.g. if you got them from a

713

"plotclick" event, or you can specify the indices, e.g.

714

highlight(1, 3) to highlight the fourth point in the second series

715

(remember, zero-based indexing).

716

717

718

- unhighlight(series, datapoint) or unhighlight()

719

720

Remove the highlighting of the point, same parameters as

721

highlight.

722

723

If you call unhighlight with no parameters, e.g. as

724

plot.unhighlight(), all current highlights are removed.

- setData(data)

You can use this to reset the data used. Note that axis scaling,

730

ticks, legend etc. will not be recomputed (use setupGrid() to do

731

that). You'll probably want to call draw() afterwards.

732

733

You can use this function to speed up redrawing a small plot if

734

you know that the axes won't change. Put in the new data with

735

setData(newdata), call draw(), and you're good to go. Note that

736

for large datasets, almost all the time is consumed in draw()

737

plotting the data so in this case don't bother.

- setupGrid()

Recalculate and set axis scaling, ticks, legend etc.

743

744

Note that because of the drawing model of the canvas, this

745

function will immediately redraw (actually reinsert in the DOM)

746

the labels and the legend, but not the actual tick lines because

747

they're drawn on the canvas. You need to call draw() to get the

canvas redrawn.

- draw()

Redraws the plot canvas.

753

754

- triggerRedrawOverlay()

755

756

Schedules an update of an overlay canvas used for drawing

757

interactive things like a selection and point highlights. This

758

is mostly useful for writing plugins. The redraw doesn't happen

759

immediately, instead a timer is set to catch multiple successive

760

redraws (e.g. from a mousemove).

- width()/height()

Gets the width and height of the plotting area inside the grid.

765

This is smaller than the canvas or placeholder dimensions as some

766

extra space is needed (e.g. for labels).

- offset()

Returns the offset of the plotting area inside the grid relative

771

to the document, useful for instance for calculating mouse

772

positions (event.pageX/Y minus this offset is the pixel position

773

inside the plot).

774

775

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

776

777

Returns the calculated offset of the data point at (x, y) in data

778

space within the placeholder div. If you are working with dual axes, you

779

can specify the x and y axis references, e.g.

780

781

o = pointOffset({ x: xpos, y: ypos, xaxis: 2, yaxis: 2 })

782

// o.left and o.top now contains the offset within the div

783

784

785

There are also some members that let you peek inside the internal

786

workings of Flot which is useful in some cases. Note that if you change

787

something in the objects returned, you're changing the objects used by

788

Flot to keep track of its state, so be careful.

- getData()

Returns an array of the data series currently used in normalized

793

form with missing settings filled in according to the global

794

options. So for instance to find out what color Flot has assigned

795

to the data series, you could do this:

796

797

var series = plot.getData();

798

for (var i = 0; i < series.length; ++i)

799

alert(series[i].color);

800

801

A notable other interesting field besides color is datapoints

802

which has a field "points" with the normalized data points in a

803

flat array (the field "pointsize" is the increment in the flat

804

array to get to the next point so for a dataset consisting only of

805

(x,y) pairs it would be 2).

- getAxes()

Gets an object with the axes settings as { xaxis, yaxis, x2axis,

810

y2axis }.

811

812

Various things are stuffed inside an axis object, e.g. you could

813

use getAxes().xaxis.ticks to find out what the ticks are for the

814

xaxis. Two other useful attributes are p2c and c2p, functions for

815

transforming from data point space to the canvas plot space and

816

back. Both returns values that are offset with the plot offset.

- getPlaceholder()

Returns placeholder that the plot was put into. This can be useful

821

for plugins for adding DOM elements or firing events.

- getCanvas()

Returns the canvas used for drawing in case you need to hack on it

826

yourself. You'll probably need to get the plot offset too.

- getPlotOffset()

Gets the offset that the grid has within the canvas as an object

831

with distances from the canvas edges as "left", "right", "top",

832

"bottom". I.e., if you draw a circle on the canvas with the center

833

placed at (left, top), its center will be at the top-most, left

corner of the grid.

- getOptions()

Gets the options for the plot, in a normalized format with default

values filled in.

Hooks

=====

In addition to the public methods, the Plot object also has some hooks

846

that can be used to modify the plotting process. You can install a

847

callback function at various points in the process, the function then

848

gets access to the internal data structures in Flot.

849

850

Here's an overview of the phases Flot goes through:

851

852

1. Plugin initialization, parsing options

853

854

2. Constructing the canvases used for drawing

855

856

3. Set data: parsing data specification, calculating colors,

857

copying raw data points into internal format,

858

normalizing them, finding max/min for axis auto-scaling

859

860

4. Grid setup: calculating axis spacing, ticks, inserting tick

861

labels, the legend

862

863

5. Draw: drawing the grid, drawing each of the series in turn

864

865

6. Setting up event handling for interactive features

866

867

7. Responding to events, if any

868

869

Each hook is simply a function which is put in the appropriate array.

870

You can add them through the "hooks" option, and they are also available

871

after the plot is constructed as the "hooks" attribute on the returned

872

plot object, e.g.

873

874

// define a simple draw hook

875

function hellohook(plot, canvascontext) { alert("hello!"); };

876

877

// pass it in, in an array since we might want to specify several

878

var plot = $.plot(placeholder, data, { hooks: { draw: [hellohook] } });

879

880

// we can now find it again in plot.hooks.draw[0] unless a plugin

881

// has added other hooks

882

883

The available hooks are described below. All hook callbacks get the

884

plot object as first parameter. You can find some examples of defined

885

hooks in the plugins bundled with Flot.

886

887

- processOptions [phase 1]

888

889

function(plot, options)

890

891

Called after Flot has parsed and merged options. Useful in the

892

instance where customizations beyond simple merging of default

893

values is needed. A plugin might use it to detect that it has been

894

enabled and then turn on or off other options.

895

896

897

- processRawData [phase 3]

898

899

function(plot, series, data, datapoints)

900

901

Called before Flot copies and normalizes the raw data for the given

902

series. If the function fills in datapoints.points with normalized

903

points and sets datapoints.pointsize to the size of the points,

904

Flot will skip the copying/normalization step for this series.

905

906

In any case, you might be interested in setting datapoints.format,

907

an array of objects for specifying how a point is normalized and

908

how it interferes with axis scaling.

909

910

The default format array for points is something along the lines of:

911

912

[

913

{ x: true, number: true, required: true },

914

{ y: true, number: true, required: true }

915

]

916

917

The first object means that for the first coordinate it should be

918

taken into account when scaling the x axis, that it must be a

919

number, and that it is required - so if it is null or cannot be

920

converted to a number, the whole point will be zeroed out with

921

nulls. Beyond these you can also specify "defaultValue", a value to

922

use if the coordinate is null. This is for instance handy for bars

923

where one can omit the third coordinate (the bottom of the bar)

924

which then defaults to 0.

925

926

927

- processDatapoints [phase 3]

928

929

function(plot, series, datapoints)

930

931

Called after normalization of the given series but before finding

932

min/max of the data points. This hook is useful for implementing data

933

transformations. "datapoints" contains the normalized data points in

934

a flat array as datapoints.points with the size of a single point

935

given in datapoints.pointsize. Here's a simple transform that

936

multiplies all y coordinates by 2:

937

938

function multiply(plot, series, datapoints) {

939

var points = datapoints.points, ps = datapoints.pointsize;

940

for (var i = 0; i < points.length; i += ps)

points[i + 1] *= 2;

}

Note that you must leave datapoints in a good condition as Flot

945

doesn't check it or do any normalization on it afterwards.

- draw [phase 5]

function(plot, canvascontext)

951

952

Hook for drawing on the canvas. Called after the grid is drawn

953

(unless it's disabled) and the series have been plotted (in case

954

any points, lines or bars have been turned on). For examples of how

955

to draw things, look at the source code.

956

957

958

- bindEvents [phase 6]

959

960

function(plot, eventHolder)

961

962

Called after Flot has setup its event handlers. Should set any

963

necessary event handlers on eventHolder, a jQuery object with the

964

canvas, e.g.

965

966

function (plot, eventHolder) {

967

eventHolder.mousedown(function (e) {

968

alert("You pressed the mouse at " + e.pageX + " " + e.pageY);

});

}

Interesting events include click, mousemove, mouseup/down. You can

973

use all jQuery events. Usually, the event handlers will update the

974

state by drawing something (add a drawOverlay hook and call

975

triggerRedrawOverlay) or firing an externally visible event for

976

user code. See the crosshair plugin for an example.

977

978

Currently, eventHolder actually contains both the static canvas

979

used for the plot itself and the overlay canvas used for

980

interactive features because some versions of IE get the stacking

981

order wrong. The hook only gets one event, though (either for the

982

overlay or for the static canvas).

983

984

985

- drawOverlay [phase 7]

986

987

function (plot, canvascontext)

988

989

The drawOverlay hook is used for interactive things that need a

990

canvas to draw on. The model currently used by Flot works the way

991

that an extra overlay canvas is positioned on top of the static

992

canvas. This overlay is cleared and then completely redrawn

993

whenever something interesting happens. This hook is called when

994

the overlay canvas is to be redrawn.

995

996

"canvascontext" is the 2D context of the overlay canvas. You can

997

use this to draw things. You'll most likely need some of the

998

metrics computed by Flot, e.g. plot.width()/plot.height(). See the

999

crosshair plugin for an example.

Plugins

-------

Plugins extend the functionality of Flot. To use a plugin, simply

1007

include its Javascript file after Flot in the HTML page.

1008

1009

If you're worried about download size/latency, you can concatenate all

1010

the plugins you use, and Flot itself for that matter, into one big file

1011

(make sure you get the order right), then optionally run it through a

1012

Javascript minifier such as YUI Compressor.

1013

1014

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

1015

1016

Each plugin registers itself in the global array $.plot.plugins. When

1017

you make a new plot object with $.plot, Flot goes through this array

1018

calling the "init" function of each plugin and merging default options

1019

from its "option" attribute. The init function gets a reference to the

1020

plot object created and uses this to register hooks and add new public

1021

methods if needed.

1022

1023

See the PLUGINS.txt file for details on how to write a plugin. As the

1024

above description hints, it's actually pretty easy.

1025