Skip to content

Upgrading to 3.0.0

Jump to bottom
Xiaohan Zhang edited this page Apr 21, 2017 · 16 revisions

🎉 We are pleased to announce Plottable v3.0.0! 3.0.0 brings a host of performance improvements and new features, as well as modernizing the codebase and the ways in which users consume the library. Please read on for a list of breaking changes and upgrade steps.

Breaking Changes

  1. [ACTION REQUIRED] .renderTo() only accepts HTML elements
  2. CDN changes
  3. Removing bower support
  4. d3 v4
  5. module format
  6. Typescript changes
  7. API changes
  8. Dropping IE9 support

Features

  1. Canvas Rendering
  2. BarPlot barAlignment
  3. BarPlot barEnd
  4. Axis interactions
  5. CategoryAxis tickLabelShearAngle

Improvements

Bugfixes

Breaking changes

HTML components

Previously, Components only understood SVG elements and had to be rendered to an SVG. Components now work with generic HTML elements, opening the way for more improvements such as canvas rendering. This introduces the following breaking changes:

[ACTION REQUIRED] .renderTo() only accepts HTML elements

Components now must .renderTo() an HTML element, not an <svg>. All users will need to modify the element they are passing to .renderTo() (or .anchor()) appropriately.

old:
<svg width="300" height="300"></svg>

new:
<div style="width: 300px; height: 300px"></div>
  • In SVG you could use the width= and height= attributes; in HTML please use CSS to size the chart appropriately.
  • We no longer apply overflow: visible to the renderTo target.
  • Component.originToSVG() renamed to Component.originToRoot().
  • Added Component.root() and Component.isRoot() methods.
  • Added Component.element() which returns the root HTML Element for that given component.
  • The internal DOM hierarchy has changed; existing CSS selectors targeting Plottable elements may no longer work. The gist of the changes are:
  1. content/foreground/background/box-container are now <svg>s instead of <g>s
  2. Table and Group now place their children on the .component element instead of on the .content.

CDN changes - rawgit.com no longer supported, cdnjs.com no longer supported

rawgit.com will no longer work as a CDN for newer versions of Plottable. We recommend using npm and webpack to bundle Plottable with your application. If that's not possible, you may use unpkg.com.

If on develop: https://rawgithub.com/palantir/plottable/develop/plottable.js --> //unpkg.com/plottable@latest/plottable.js

If on a specific version: https://rawgithub.com/palantir/plottable/v3.0.0-beta.1/plottable.js --> //unpkg.com/[email protected]/plottable.js

Similarly, we are no longer supporting cdnjs.com and it may break in the future. Use unpkg instead.

Removing bower support

Bower is an outdated package manager and we have dropped support for it. Please use yarn/npm instead.

d3 v4

We now use d3 v4.5.0, which opens the door to many bugfixes and general improvements. You will need to upgrade your d3 dependency to point to 4.5.0 or higher accordingly:

Script tag:

<!-- old -->
<script src="//cdnjs.cloudflare.com/ajax/libs/d3/3.5.16/d3.js"></script>
<!-- new -->
<script src="//cdnjs.cloudflare.com/ajax/libs/d3/4.5.0/d3.js"></script>

requireJS:

require.config({
    paths: {
        // old
        d3: "https://cdnjs.cloudflare.com/ajax/libs/d3/3.5.16/d3",
        // new
        d3: "https://cdnjs.cloudflare.com/ajax/libs/d3/4.5.0/d3",
    },
});

If you use d3 elsewhere, that code will need to be upgraded to v4 semantics. See Changes in D3 4.0.

The upgrade to d3v4 has also cause some API changes:

LinePlot / AreaPlot

.interpolator() has been renamed to .curve(). .interpolator() used to take strings of the form "linear-closed", coinciding with d3v3 easing names. These are now camelCased ("linear-closed" -> "linearClosed"). Here's the full list of accepted curve names. It also now accepts a d3.curveFactory:

linePlot.curve(d3.curveCatmullRom.alpha(0.5))

See d3-shape#curves for more info.

EasingAnimator

EasingAnimator.easingMode() used to take strings of the form "exp-in-out", coinciding with d3v3 easing names. These are now camelCased ("exp-in-out" -> "expInOut"). Here's the full list of accepted easing names. It also now accepts an arbitrary mapping function:

animator.easingMode((t) => Math.sin(t * Math.PI))

See d3-ease for more info.

SymbolFactory

  • triangleUp() renamed to triangle().
  • triangleDown() removed.
  • Added wye() and star().

Module format

The codebase is now written in ES2015 Module format and we now publish our modules on npm. The npm package contains our modules and typings.

Users should be able to pull in just the parts of Plottable they care about using import statements:

// import just the Category Axis
import { Category } from "plottable/build/src/axes/categoryAxis";

Upon upgrading, Typescript consumers may see "cannot be named" errors like:

Error:(16, 17) TS4058:Return type of exported function has or is using name 'Scale' from external module "<path>/plottable/build/src/scales/scale" but cannot be named.

This occurs when your module exports a Plottable type. The recommended fix is to explicitly type the exported type:

// bad
export const k = new Plottable.Plots.Bar();

// good
export const k: Plottable.Plots.Bar = new Plottable.Plots.Bar();

Typescript changes

Interfaces renamed

All Typescript interfaces now have an I prepended to them:

// old
var entity: Plottable.Entity... // no exported member Entity

// new
var entity: Plottable.IEntity

Minimum required version TS2.1

Our .d.ts files now use the keyof operator which only exists on Typescript 2.1 and above. Upgrade to Typescript 2.1 to prevent compile errors.

Typings

If you depend on @types/d3, you will need to upgrade your codebase to use @types/[email protected].

Some methods now get/set string literal union types

Plottable.Axes.Time.tierLabelPositions(), Plottable.Axes.Time.maxTimeIntervalPrecision(), Component.xAlignment(), Component.yAlignment(), and Plottable.RenderController.renderPolicy() now get/set string literal union types that define exactly the set of acceptable strings. Typescript may throw errors in places that previously worked:

Old:

var xAlign = "left";
component.xAlignment(xAlign); // Argument of type 'string' is not assignable to parameter of type '"left" | "center" | "right"'.

New:

var xAlign: Plottable.XAlignment = "left";
// or
const xAlign = "left";

component.xAlignment(xAlign);
// or
component.xAlignment("left");

API changes

Plottable.Components.Alignment renamed

  • Plottable.Components.Alignment.TOP -> Plottable.YAlignment.top
  • Plottable.Components.Alignment.CENTER -> Plottable.YAlignment.center or Plottable.XAlignment.center
  • Plottable.Components.Alignment.BOTTOM -> Plottable.YAlignment.bottom
  • Plottable.Components.Alignment.LEFT -> Plottable.XAlignment.left
  • Plottable.Components.Alignment.RIGHT -> Plottable.XAlignment.right

Plottable.RenderController.Policy enum members camelCased

  • Policy.IMMEDIATE -> Policy.immediate
  • Policy.ANIMATION_FRAME -> Policy.animationFrame
  • Policy.TIMEOUT -> Policy.timeout

Plottable.Plots.Bar.ORIENTATION_VERTICAL and ORIENTATION_HORIZONTAL renamed

  • Plottable.Plots.Bar.ORIENTATION_VERTICAL -> Plottable.Plots.BarOrientation.vertical
  • Plottable.Plots.Bar.ORIENTATION_HORIZONTAL -> Plottable.Plots.BarOrientation.horizontal

Remove Component Box API

Component's .bounding-box element has been removed. Use the .element() method to get the DOM element that bounds a Component.

Component's .background-fill element has been removed. This was added so users could add a background color using CSS chart. Instead, style the .component selector.

Old:

#myChart .background-fill {
  fill: "red";
}

New:

#myChart .component {
  background-color: "red";
}

Click Interaction

The DoubleClick interaction has been combined with Click and internally controls overlap between the two events.

  • callbacks are registered with onDoubleClick and unregistered with offDoubleClick
  • on a dblclick event, the single click callback will not be called
// old:

var singleClick = new Plottable.Interactions.Click();
var doubleClick = new Plottable.Interactions.DoubleClick();

singleClick.onClick(...) // will fire on both physical click instances
doubleClick.onDoubleClick(...)

// new:

var click = new Plottable.Interactions.Click();
click.onClick(...) // only fires on the first physical click
click.onDoubleClick(...) // only fires on the physical click corresponding to a double-click

Dispatchers

Dispatchers.Mouse.getDispatcher and Dispatchers.touch.getDispatcher should now be passed Components instead of SVG elements.

eventInsideSVG renamed to eventInside and now must be passed the Component to test as the first argument.

Browser support

Dropping IE9 support

We are bumping our minimum supported version of Internet Explorer from 9 to 11. IE9 is no longer supported by Microsoft and users are recommended to upgrade to a newer browser. Future releases should not be expected to have IE9 compatibility.

Features

Canvas rendering

  • Canvas rendering should improve performance for Plots with many elements, and avoid crashing the browser due to an overloaded DOM.
  • Plots now expose a plot.renderer("svg" | "canvas") method to tell the Plot to render to SVG or to Canvas.
  • No animations are supported
  • All PlotEntity objects (from calling entities(), entitiesAt(), entitiesIn(), or entityNearest()) returned from plots using the canvas renderer will have a null selection property (so e.g. changing the color of a clicked bar in Canvas is not possible)

Canvas Rectangle Plot and Bar Plot

Rectangle plot and bar plot are supported, supporting the stroke-width, stroke, fill, and opacity attributes.

rectangle canvas, 10k

Canvas Line Plot

Rendering Line Plot onto Canvas, supporting the stroke, stroke-width, and opacity attributes.

10 datasets, 10k points each

BarPlot barAlignment

BarPlot now exposes a barAlignment("start" | "middle" | "end") property that determines whether the .x() accessor defines the start, middle, or end of the bar being drawn.

BarPlot barEnd

BarPlot now also exposes a barEnd() that controls the width of the bar. This together with barAlignment() allows more direct control over the start and end coordinates for each bar and helps build histogram-like plots.

Axis interactions

Add Axis.tickLabelDataOnElement, which gets the data value for a tick label. This allows users to implement behaviors based on interacting with a tick label:

clickInteraction.onClick((point, event) => {
  const dataValue = axis.tickLabelDataOnElement(event.target);

  console.log("clicked on value", dataValue);
}).attachTo(axis);

CategoryAxis tickLabelShearAngle

Added tickLabelShearAngle property to CategoryAxis to enable shearing of long tick label text.

The existing tickLabelRotationAngle property can only rotate the text in the four cardinal directions, but tickLabelShearAngle can be any number of degrees from -80 to 80.

Note that while the lines of sheared text will still be wrapped within the bounds of the "primary" dimension (i.e. "width" in non-rotated text), the text may overflow the bounds of the "secondary" dimension (i.e. "height" in non-rotated text).

image

Improvements

Performance

  • Improved performance in XYPlot.entityNearest using a quad tree
  • Improved SVG line renderer performance.
  • Performance of drawing labels has been improved across the board.
  • Pan/Zoomed Category Axes will only take up as much space as needed to show available ticks (also improves perf) #3223
  • Reduce memory leaks in Plots.Bar.entityNearest and entitiesIntersecting (#3220)
  • Drastically increase perf by NOT invalidating text measuring cache on every render. Added explicit method to invalidate if necessary. (#3230)

Enum objects

We've added enum objects for the following enums:

  • Plottable.Animators.EaseName
  • Plottable.AxisOrientation
  • Plottable.XAlignment
  • Plottable.YAlignment
  • Plottable.Axes.TimeAxisOrientation
  • Plottable.Axes.TierLabelPosition
  • Plottable.Plots.CurveName
  • Plottable.Renderer
  • Plottable.Utils.Stacking.IStackingOrder

This makes it convenient to see what options are available in an enum and makes the code more readable:

new Plottable.Axes.Category(scale, Plottable.AxisOrientation.right);

Bugfixes

  • We now explicitly include @types/d3 as an npm dependency. Previously users needed to manually install @types/d3 when installing Plottable since we expose d3 types in our public API; this should now be installed automatically.
  • Fix Entity.position sometimes not giving the pixel position.
  • Fix nearestEntity comparing entities in data space, which didn't make sense for categorical axes.
  • Fix stacked bar labels for date axes (#3208)

Thanks,

Plottable Team

Clone this wiki locally