Introduction
In this tutorial, you will learn the basics of how to show data using the grid layout.
The grid layout, thinkmap.layout.grid.GridLayout, is ideal for situations in
which you are comparing multiple properties of your data.
Typically, it is used when you are trying to understand and analyze a result set, in which the nodes have
properties that can be compared. These properties can be discrete (for example, job titles, movie ratings, or
categories) or they can be continuous (e.g. time series data, costs, or height).
In this tutorial, we look at about 300 movies from the 1980's. These movies can then be sorted and grouped based on several factors:
- Release Date - (continuous time series)
- Budget - (continuous)
- US Gross - (continuous)
- Runtime - (continuous)
- Stars - (discrete)
- Ratings - (discrete)
Each movie is represented by a circle. The size of the circle can be changed to represent the values of different properties, as per the pull down menu.
The Grid Layout
The positions of nodes and edges in a Thinkmap display are determined by layouts. The grid layout lays out nodes where the position of the nodes is determined by the value of a specific property of the node. The position is determined based on where that value would appear on a grid's axis. Typically, one axis represents the value of one property, and the other axis represents the value of another property, allowing the end users to quickly understand the relationships between the two properties.
Getting Started
If you view the source of this page, you can see the code that makes up this example in its entirety, but we'll go through it section-by-section here.
If you view the source of this example, you will notice that we are linking to two important source files:
The first file is the thinkmap.js file for your project. The second file grid.js contains
the code for this example, which we will now discuss.
Let's examine grid.js. We start first by creating the graph and the display.
// create a graph
var graph = new thinkmap.graph.Graph();
// the graph should get its data from the "moviedb.tas" remote datasource
graph.datasource('/moviedb.tas');
// create a display that is placed within the <div> with the id "map"
var display = new thinkmap.display.Display(document.getElementById('map'));
// allow the user to zoom the display with the mouse wheel
display.zoomOnWheel(true);
// enable scrollbars
display.scrollbars(true);
We also set a tooltip so that when a user mouses over a movie, he sees details about the move:
/* Configure tooltip popups for the display. The tooltip
* function is passed an entity, and returns a string representing
* HTML that is placed within the tooltip.
*/
display.tooltips(function(e){
return ''+e.data.title +'' +
'
Released: ' +
thinkmap.dateFormat(e.data.release,'mmmm dd, yyyy') +
'
Duration: ' +
(e.data.runtime ? configs.runtime.format(e.data.runtime) : '?') +
'
Rated ' +
e.data.rating +', '+ e.data.stars + ' stars' +
'
US Gross: ' +
(e.data.usgross ? formatCurrency(e.data.usgross) : '?') +
'
Budget: ' +
(e.data.budget ? formatCurrency(e.data.budget) : '?')
;
})
.showDelay(500) // wait 500 milliseconds before the tooltip appears
.hideDelay(150); // wait 150 milliseconds before the tooltip is hidden
This example sets the grid layout options based on how the user changes the select menus for each axis.
Discrete vs. Continuous Properties
The grid layout has two primary ways it lays out data. If the data is continuous, the gridLayout positions the items according to a continuous scale on the axis. If the data is discrete, then the grid layout positions the items in swim lanes, making room for them along the axis as much as necessary, so that there is no overlap.
Our example uses a variety of discrete and continuous values, with both linear and time-series scales. To make it easier to work with this variety, we create a configs object that contains these options:
/* Create an object that groups the various options that will be configured
* when the user switches the axis and radius select menus. When the user
* changes the select menu, we will choose the appropriate configuration
* for the selected item.
*/
var configs = {
budget: {
/*
* The filter function is used to select which movies
* appear in the display. This function will be called for every
* movie in the graph. If it returns true, the movie will be
* included.
*/
filter: function(e) { return e.data.budget != null; },
/*
* The value function returns the value that will be
* used to position the node.
*/
value: function(e) { return e.data.budget; },
/*
* The scale designates the type of scale used for the axis, which
* is then used to determine the positioning of the nodes. If the
* scale is specified, the grid layout will position the nodes
* exactly according to the scale, even if there is overlap.
* In this case, the scale is linear, meaning there is a linear
* relationship between the input values and the output
* values.
*/
scale: thinkmap.scale.linear(),
/*
* The format is used to determine how labels are drawn for
* each axis. The function takes a number and returns a string
* (the label). In this case we use a formatCurrency function
* (specified below).
*/
format: formatCurrency,
/*
* the value of the radius property is a linear scale that
* takes inputs from 0 to 90,000,000 and returns outputs
* from 2 to 30. We use this value to determine the radius of the
* circle.
*/
radius: thinkmap.scale.linear().inputs(0,90000000).outputs(2,30)
},
release: {
filter: function(e) { return e.data.release != null; },
value: function(e) { return e.data.release; },
/*
* The scale associated with release is a time scale. A time scale
* takes as input a date, and returns a linear value.
*/
scale: thinkmap.scale.time(),
/* If you do not specify a format, the grid will use the default
* format function. The default format function for dates
* automatically picks a formatter based on the time scale being
* displayed.
*/
format: null
},
...
}
The configs object is then used when we change the value of the select menu. Most of this action happens in the changeAxes function, which is called after we first load the movies, and then whenever the select menus for the movie changes.
First we get our values from the appropriate configs object
function changeAxes() {
// the name of the property to display as the xAxis
var xAxisProperty = document.getElementById('xAxisSelect').value;
// the name of the property to display as the yAxis
var yAxisProperty = document.getElementById('yAxisSelect').value;
/*
* configX is assigned the corresponding configuration option from the
* configs object defined above.
*/
var configX = configs[ xAxisProperty ];
/*
* configY is assigned the corresponding configuration option from the
* configs object defined above.
*/
var configY = configs[ yAxisProperty ];
Then we filter so that we're only showing data for which we have values that correspond to the different axes
//create a selection that contains all movies.
var allMovies = graph.select('movie');
/*
* filtered is a selection based on the filter function defined in the
* configX and configY object. We exclude items for which we don't
* have values.
*/
var filtered = allMovies.filter(configX.filter).filter( configY.filter );
// Add and retain only filtered items to the display.
display.add(graph).retainOnly(filtered);
Then we lay out the graph based on the values.
// Configure the grid layout using the options defined above.
gridLayout
/*
* The formatX option determines the way in which axis labels on the
* x-axis are formatted based on the configX object. A format
* function is passed a scale value, and returns a string that
* is represented within the axis. (e.g. 200000 might return 200,000
* or $200k.)
*/
.formatX(configX.format)
/*
* The valueX option determines which value is used to position
* items corresponding to the x-axis.
*/
.valueX(configX.value)
.formatY(configY.format)
.valueY(configY.value)
/*
* The transition() options tells the grid layout to animate between
* scales if both scales are of the same type. In this case Grid
* lines and axis labels animate smoothly into position.
*/
.transition()
// Set the scale for the X axis.
.scaleX( configX.scale ? // if configX has a scale,
/* set it to be one that allows all entities to
* be laid out on the screen, from 5 pixels on the left to
* 5 pixels to the right, based on the configX scale.
*/
gridLayout
.bestFitX( 5, display.width()-5, configX.scale )
/* otherwise set the scale to null, which causes the grid
* to lay out discrete values in swim lanes.
*/
: null )
// Set the scale for the Y axis, but reverse it
.scaleY( configY.scale ? // if configY has a scale,
/* set it to be one that allows all entities to be laid out
* on the screen so that there is a 5 pixel border on the top
* and on the bottom.
*/
gridLayout.bestFitY( 5, display.height()-5,
/* use the flipped scale, placing low number on the bottom
* and high numbers at the top.
*/
configY.scale.flip() )
: null ) ; //otherwise discrete values and swimlanes
/*
* display.layout() causes all layouts (in this case the grid layout)
* associated with the display to lay out.
*/
display.layout();
Changing Circle Size
This example also allows the user to change what the radius of the circle represents.
With Thinkmap, the way that Entities are represented is determined by creating templates.
/*
* Set up the template used to display the movie entity type. In addition
* to the definition here, other elements of the look and feel are set
* in the CSS definitions in the index.html file.
*/
display.template('movie').as(
/*
* Template functions are called when an entity is added or data is
* updated. They are passed an element selection which
* contains the svg representing the particular entity. In this
* case, we append a circle element to each movie. The 'r' attribute
* is set to the value returned by the radiusFunction.
* In the SVG, (where x is the returned value) is
* appended to the element.
*/
function(selection,e){
selection.append('circle').attr('r', radiusFunction(e));
});
In this case, we use radiusFunction to set the value of the radius. Let's look at radiusFunction:
/*
* radiusFunction returns a value for the radius, based on the property
* chosen from the circle select menu
*/
function radiusFunction(entity) {
// Set the name of the property based on the circleSelect menu.
var property = circleSelect.value;
// If there is a scale from the configs object for the chosen property,
if (entity.data[property] != null && configs[property]
&& configs[property].radius) {
// return the output from the radius scale for that property
return configs[property].radius( entity.data[property] );
} else {
// otherwise return 5.
return 5;
}
}
The function takes the value of the property chosen in the pull down menu, and uses the scale from the configs property to determine the radius.
Then, we bind two functions to the pulldown menu, so when a user changes the menu, we change the size and colors of the circle
// the circleSizeSelect pull down menu
var circleSelect=document.getElementById('circleSizeSelect');
/*
* Listen for changes to the circleSizeSelect menu. When the menu changes,
* call resizeCircles and recolorCircles functions
*/
circleSelect.addEventListener('change', function() {
resizeCircles();
recolorCircles();
});
The resizeCircles function animates the change in size based on the new value:
// resize the circles based on the appropriate scale
function resizeCircles() {
// the value from the select menu
var property = circleSelect.value;
// the scale from the configs object
var radiusScale = configs[property].radius;
/*
* Create a smooth transition to the appropriate radius using the scale
* from the configs object.
*
* First create an element selection from all entities of type movie.
*/
display.select('movie').elements()
//select all circle elements from within the element selection
.selectAll('circle')
/*
* make a smooth transition of the 'r'(radius) attribute
*/
.transition().attr('r', function(entity) {
//if the property defined by the select menu is null, return 5
return entity.data[property] == null ? 5 :
//otherwise return the value of the radiusScale for the
//property
radiusScale(entity.data[property]);
} )
/*
* after the transition has completed, call refit, which causes
* the scales to be adjusted based on the size and position of
* all the entities in the grid layout.
*/
.then( refit );
}
The recolorCircle function changes the style of the circles depending on if the circles have the property being displayed (we may show a movie for which we don't have the budget property, for example).
/*
* Recolor the circles based on whether they have a value for the property
* selected from the circleSelect menu
*/
function recolorCircles() {
/*
* Build a query that will select the entities with no data based on the
* value of our circle size select menu. First we select all nodes of
* type movie.
*/
var query = {$t:'movie'};
/*
* if "release" is selected from the circleSelect menu, query becomes
* {$t:'movie',release:{$neq:null}} or movies whose release property is
* not null.
*/
query[circleSelect.value] = { $neq: null };
/*
* withData is a display selection, containing entities in which the
* given property exists (is not null)
*/
var withData = display.select(query);
/*
* elements() returns an element selection of all items from the display
* selection. This allows us to work with DOM properties such as style.
* We remove the nodata class.
*/
withData.elements().removeClass('nodata');
/*
* noData is a display selection, which is the result of the set
* difference between a selection of all movies, and the withData
* selection.
*/
var noData = display.select('movie').difference(withData);
/*
* elements() returns an element selection of all items from the
* display selection. We add the nodata class, defined in the CSS of
* the index.html file.
*/
noData.elements().addClass('nodata');
}
Note that the recolorCirlce function refers to the CSS class 'nodata'. The transition that allows for the fill to fade in is specified there:
/* The nodata class causes a circle to fill with a .5 second
transition*/
.movie.nodata circle {
fill: rgba(243,135,23,0) ;
-webkit-transition-duration: .5s;
-moz-transition-duration: .5s;
-ms-transition-duration: .5s;
}
After circles change size or we adjust the size of the display, we call the refit function, which causes the axes to adjust based on the entities in the display.
function refit() {
// Animate smoothly to the bestFit scale for x and y.
gridLayout.transition()
/*
* set the x-axis scale to allow all the entities to fit from 5
* pixels to the left to 5 pixels to the right of the display.
*/
.scaleX( gridLayout.bestFitX(5, display.width()-5 ) )
/*
* set the x-axis scale to allow all the entities to fit from 5
* pixels from the top to 5 pixels to the bottom of the display.
*/
.scaleY( gridLayout.bestFitY(5, display.height()-5 ) );
// display.layout() causes the entities displayed within the grid layout
// to animate to their proper position.
display.layout();
}
Summary
In this tutorial, you learned about the basics of working with the gridLayout,
and in changing different options based on the data supplied to the layout.
In addition, you learned how to change the appearance of an entity based on
dynamic properties that can be adjusted by the user.