sanddance.md 6.01 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209
# g1.sanddance

Transitions elements with flexible timing controls.

## g1.sanddance options

It accepts 2 parameters

1. `attrs`: changes any HTML / SVG attributes of the selection (e.g. `fill`, etc)
  - `fill`, `stroke` for color
  - `x`, `y`, `cx`, `cy`, `transform`, etc for position (but these are better controlled via the options)
  - etc.
2. `options`: defines layout options (e.g. `x`, `y`, `duration`, `speed`, etc)
  - `x`: transition the elements to the x position
  - `y`: transition the elements to the y position
  - `speed`: transition at constant speed in pixels per second
  - `duration`: transition time in milliseconds (overrides `speed`)
  - `delay`: transition delay in milliseconds (default is 0)
  - `easing`: transition easing in d3-ease method (default is d3.easeLinear)
  - `filter`: filter the selection based on a column value (ex: age > 30)

Examples:

```js
// smoothly changes the fill color to blue in 100 ms
var turn_to_blue = g1.sanddance({ fill: 'blue' }, { duration: 100 })
selection.call(turn_to_blue)

// g1.sanddance moves elements to the x, y specified in 100ms
var move = g1.sanddance({}, { x: 200, y: 200, duration: 100 })
selection.call(move)

// transitions at 1000 pixels/sec.
var move_at_constant_speed = g1.sanddance({}, {x: 300, y: 300, speed: 1000})
selection.call(move_at_constant_speed)

// transitions in 100ms duration.
var move_in_duration = g1.sanddance({}, {x: 400, y: 400, duration: 100})
selection.call(move_in_duration)

// transitions after 100ms delay.
var move_after_delay = g1.sanddance({}, {x: 300, y: 300, delay: 100})
selection.call(move_after_delay)

// transitions at ease of d3.easeBounce
var move_easing = g1.sanddance({}, {x: 300, y: 300, duration: 100, easing: d3.easeBounce})
selection.call(move_easing)

// filters the selection
var selection_filtered = g1.sanddance({fill: 'red'}, {duration: 100, filter: function(d) { return d.age > 30}})
selection.call(selection_filtered)
```

## g1.sanddance.chain

To apply a sequence of sanddances one after another, use `g1.sanddance.chain`. For example:

```js
// chain sanddances. First, fill everything red, then move x to 200 and y to 100
selection.call(
  g1.sanddance.chain(
    g1.sanddance({fill: 'red'}, {duration: 100}),
    g1.sanddance({}, {x: 200, y: 100, duration: 100})
  )
)
```

## g1.sanddance layouts

### grid

Returns a sanddance that moves elements into a grid. Usage:

```js
// Lay out the elements in a grid
selection.call(
  g1.sanddance({}, {        // Create a layout based on the data array
    layout: 'grid',         // lay out as a grid
    width: 400,             // with width 400
    height: 300,            // and height 300
    data: data,             // using the specified data
    sort: 'age',            // sorted by the 'age' column
    ascending: false,       // in descending order
    duration: 100           // in 100ms
  })
)
```

Options:
- `data`: an array that has the data that is used to lay out the elements
- `width`: width of the grid in SVG units
- `height`: height of the grid in SVG units
- `sort`: column name or `function(d, i)` to sort by
- `ascending`: `false` reverses the sort order (default: `true`)

Values can be specified as a scale. Example: `fill:` can be specified as below.

```js
fill: {
  metric: 'age',
  scheme: 'RdYlGn'
}
// or
fill: {
  metric: 'age',      // same as function(d) { return d.age }
  scale: 'linear',
  domain: [0, 50, 100],
  range: ['red', 'yellow', 'green'],
}
```

Scales are dictionaries with the following keys:

- `metric:` can be a string column name or a `function(d, i)` that returns a value for each item in the data
- `scheme:` d3 chromatic color scheme to interpolate to (e.g. `'RdYlGn'`)
- `scale:` d3 scale to use. Defaults to `'linear'`
- `range`: a list that contains the scale's range
- `domain`: a list that contains the scale's domain (defaults to the extent of the metric)

```js
// fill as scale config with linear scale
selection.call(
  g1.sanddance({
    fill: {
      metric: function(d) { return d.age },
      scale: 'linear',
      domain: [0, 100],
      range: ['red', 'blue'],
    }
  }, {
    layout: 'grid',
    data: data,
    width: 400,
    height: 300,
    duration: 100
  })
)

// fill as scale config with scheme
selection.call(
  g1.sanddance({
    fill: {
      metric: function(d) { return d.age },
      scheme: 'RdYlGn'
    }
  }, {
    layout: 'grid',
    data: data,
    width: 400,
    height: 300,
    duration: 100
 })
)
```

### hexpack

Returns a sanddance that moves elements into a hexpack. Usage:

```js
// Lay out the elements in a hexpack
selection.call(
  g1.sanddance({}, {        // Create a layout based on the data array
    layout: 'hexpack',      // lay out as hexpack
    width: 400,             // with width 400
    height: 300,            // and height 300
    data: data,             // using the specified data
    sort: 'age',            // sorted by the 'age' column
    ascending: false,       // in descending order
    duration: 100           // in 100ms
  })
)
```
The values can also be specified as a scale config and the options definitions are same as grid.

## g1.sanddance methods

`sanddance.update(new_attrs, new_options)` returns a new sanddance that updates
the old `attrs` with `new_attrs` and the old `options` with `new_options`.

```js
// The two lines below are the same:
g1.sanddance({ stroke: 'blue' }).update({ fill: 'red' })
g1.sanddance({ stroke: 'blue', fill: 'red' })

// Update the options
g1.sanddance({}, { delay: 100 }).update({}, { duration: 100 }),
g1.sanddance({}, { duration: 100, delay: 100 })
```

## g1.sanddance events

These events are triggered by the sanddance object.

- `init` when the sanddance is initialized
- `start` when the first transition begins (after delay)
- `end` when all transitions are complete

All events set the d3 selection as `this`. For example:

```js
// sanddance events
selection.call(
  g1.sanddance({ fill: 'red' })
    .on('init.log', function() { console.log('init', this) })
    .on('start.log', function() { console.log('start', this) })
    .on('end.log', function() { console.log('end', this) })
)
```