Skip to content

dimple.storyboard

Jump to bottom Edit New page
Christabella edited this page Jun 15, 2017 · 4 revisions

A storyboard uses one or more category dimensions to create an animation. For example creating a storyboard by "Month" on a year of sales data will create 12 frames. You may use the storyboard methods to change frames manually but by default the chart will iterate through the data points automatically.

Constructor
Properties

#####Methods#####

Constructor

dimple.storyboard(chart, categoryFields) [code] - Create the storyboard, setting it's parent chart and the category fields whose values you wish to iterate to create frames of animation. While the series can be created using its constructor, it is advisable to use the factory method in the chart object (setStoryboard) as this will add it to the chart's storyboard property as well as constructing the object. And it will take care of some additional tasks such as mapping axes.

  • chart (Required): The dimple.chart object to which the chart will be connected. As well as the chart being passed here, it must also have this storyboard assigned to its storyboard property.

  • categoryFields (Required): This accepts either a single string value or an array of string values. The following options are accepted values for categoryFields:

    • Single string value: e.g. new storyboard(myChart, "Brand"). This string value must be a field name from the data and its distinct values will be used to create the frames of animation. E.g. "Brand 1", "Brand 2"...

    • Array of string values: e.g. new storyboard(myChart, ["Brand", "Region"]). The string values must be field names from the data and the combination of their distinct values will be used to create the frames of animation. E.g. "Brand 1/Region 1", "Brand 1/Region 2", "Brand 2/Region 1"...

Example:

// Animate for each month in the data
myChart.storyboard = new dimple.storyboard(myChart, "Month");

Properties

dimple.storyboard.autoplay [code] - By default this value is true which will cause the chart to start animating when the chart's draw method is called. Setting this after drawing will do nothing until the draw method is called again. Creating a non-animating storyboard can be useful where events are to be used to change frames.

Example:

// draw a chart without autoplaying the storyboard
var myStoryboard = myChart.setStoryboard("Month");
myStoryboard.autoplay = false;
myChart.draw();

// play button click handler
function play() {
	myStoryboard.startAnimation();
}

dimple.storyboard.categoryFields [code] - The category fields whose unique combination of values will be used to create frames of animation. Unlike setting this via the constructor or helper method this must be an array.

Example:

// Create a storyboard for brand
var myStoryboard = myChart.setStoryboard("Brand");
// Oops I meant date
myStoryboard.categoryFields = ["Date"];

dimple.storyboard.chart [code] - The dimple.chart object to which the storyboard will be connected. As well as the chart being passed here, it must also have this storyboard in its dimple.chart.storyboard property.

This will probably be largely unused as the chart is set during the constructor or factory methods. It is maintained in the public API to find a storyboard's parent.

Example:

// Add a storyboard to the chart object
var myStoryboard = myChart.setStoryboard("Brand");
// Get myChart via the storyboard
console.log(myStoryboard.chart);

dimple.storyboard.fontSize [code] - This is 10px by default as of version 2. In order to get the dimple version 1 handling (where fonts are resized according to the chart size) set this to "auto". Otherwise any valid CSS font-size string may be passed.

// Let's keep it old skool
myStoryboard.fontSize = "auto";

dimple.storyboard.fontFamily [code] - This is sans-serif by default, any CSS font-family is valid here. Changing this will override the font used for axes.

// Use a serif font for this axis
myStoryboard.fontFamily = "serif";

dimple.storyboard.frameDuration [code] - The duration of the frame in milliseconds. This will be the length of each individual frame in an animation or the time to transition states if changing frames manually.

Example:

// A year in a minute "Data Analytics for Speed Readers"
var myStoryboard = myChart.setStoryboard("Day");
myStoryboard.frameDuration = 164;
myChart.draw();

dimple.storyboard.onTick [code] - An event which will be fired every time the animation ticks. This accepts a function and will receive a dimple.eventArgs object in its first parameter, however as much of the eventArgs' properties relate to a selected series only the frameValue will be populated.

Example:

// Write the day value to the console every time the animation changes
var myStoryboard = myChart.setStoryboard("Day");
myStoryboard.onTick = function (e) {
		console.log(e.frameValue);
	};
myChart.draw();

dimple.storyboard.storyLabel [code] - A d3 text element created to display the current frame text when the chart draws. This is provided here to allow easy modification of attributes after rendering.

Example:

// Draw the animation
var myStoryboard = myChart.setStoryboard("Day");
myChart.draw();
// Move the story label to the left edge
myStoryboard.storyLabel.attr("x", 0);

Methods

dimple.storyboard.addOrderRule(ordering, desc) [code] - Add a rule by which the values in the storyboard dimension will be ordered. If no order rules are specified the default behaviour is to sort by the dimension itself. If the values can be parsed as a number or a date then a suitable order will be applied. Order rules will be used in the order they are added. This means that subsequent rules will only be considered if a pair of values evaluate to equal according to the first rule. If all specified rules evaluate to equal for a particular pair the default rule will be applied. If they are still equal their position in the data will be used.

  • ordering (Required): The core field of the rule, there are a number of values which can be passed here. The different cases are discussed below:
    • A dimension. This should be a string name representing a dimension in the data. In this case it is advisable to use a dimension with a lower or equal granularity to the dimension being sorted. For example if sorting countries and specifying myStoryboard.addOrderRule("Continent") the countries will be grouped by continent and then alphabetically within each. In this example the first five countries would be Afghanistan, Armenia, Azerbaijan, Bahrain and Bangladesh, because Asia is alphabetically first of the continents, and these are the first Asian countries alphabetically. Sorting continents by country would produce unreliable results because the first country encountered is used to sort its respective continent. Numeric values will be summed by the field to be sorted and ordered based on their totals.
    • A function. The function must take 2 parameters and return an integer. Both parameters will receive a data row. This row will have all the fields in the chart data provided, but critically, there will be a single value for the field being sorted and an array of values for every other field (even if there is a single value). Therefore your function should behave accordingly. The function should return a negative value if the contents of the first parameter should appear before the second parameter's contents in the sorted values. If the second should come first, your function should return a positive integer. If they evaluate equally return 0.
    • An array. The array should contain the expected values for the dimension to be sorted. The values will simply be placed in the same order as the array. Therefore if sorting days of the week (which would be default be alphabetic) you could use myStoryboard.addOrderRule(["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]). Any values not in the list will be appended to the end using following rules (or the default rule).
  • desc (Optional): By default this will be false. If true is passed the values will be returned in reverse order.

Example:

// Draw the chart for each country
var myStoryboard = myChart.setStoryboard("Country");
// Order this by continent alphabetically, and then by GDP descending within each continent.
myStoryboard.addOrderRule("Continent");
myStoryboard.addOrderRule("GDP", true);

dimple.storyboard.getFrameValue() [code] - Retrieve the current frame value during an animation.

  • returns (string): The current frame value from the category fields' unique values.

Example:

// Draw the animation
var myStoryboard = myChart.setStoryboard("Day");
myChart.draw();
// Log the first day in the series
console.log(myStoryboard.getFrameValue());

dimple.storyboard.goToFrame(frameText) [code] - Move the storyboard to a specific frame and redraw with a transition.

  • frameText (Required): The frame value to move to. The value passed should be a string from the unique values in the distinct values of the categoryFields.

Example:

// Draw the animation
var myStoryboard = myChart.setStoryboard("Day");
myChart.draw();
// Log the first day in the series
console.log(myStoryboard.getFrameValue());

dimple.storyboard.pauseAnimation() [code] - Halt the animation but maintain the current frame so that calling startAnimation will continue from the current frame.

Example:

// draw a chart and begin animation
var myStoryboard = myChart.setStoryboard("Month");
myChart.draw();

// play button click handler
function play() {
	myStoryboard.playAnimation();
}

// pause button click handler
function pause() {
	myStoryboard.pauseAnimation();
}

// stop button click handler
function pause() {
	myStoryboard.stopAnimation();
}

dimple.storyboard.startAnimation() [code] - Start/continue the animation from the current frame. Each frame will last the number of milliseconds determined by the frameDuration property.

Example:

// draw a chart and begin animation
var myStoryboard = myChart.setStoryboard("Month");
myChart.draw();

// play button click handler
function play() {
	myStoryboard.playAnimation();
}

// pause button click handler
function pause() {
	myStoryboard.pauseAnimation();
}

// stop button click handler
function pause() {
	myStoryboard.stopAnimation();
}

dimple.storyboard.stopAnimation() [code] - Halt the animation and reset the current frame so that calling startAnimation will start from the first frame.

Example:

// draw a chart and begin animation
var myStoryboard = myChart.setStoryboard("Month");
myChart.draw();

// play button click handler
function play() {
	myStoryboard.playAnimation();
}

// pause button click handler
function pause() {
	myStoryboard.pauseAnimation();
}

// stop button click handler
function pause() {
	myStoryboard.stopAnimation();
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally