ember-d3-helpers

This library provides a collection of helpers for building D3 graphs via Ember.js templates. Component and helpers provided in this library are intended to be primitives that one could use to build a D3 graphs.

Support for more features is ongoing.

Configuration

Currently, there are no configuration options for this addon in config/environment.js. At the moment, this addon will add all the required d3 dependencies.

Live Examples

You can view a demo of a few ways to use these helpers here. Checkout ember-sparkles to see example implementations using these primitives.

Components

• d3-graph
• d3-element

Helpers

• Selection Helpers
  • d3-select
  • d3-select-all
  • d3-join
  • d3-attr
  • d3-call
• Transition Helpers
  • d3-transition
  • d3-transition-delay
  • d3-attr-tween
• Linear Scales
  • linear-scale
  • time-scale
  • seq-color-scale
• Ordinal Scales
  • band-scale
  • point-scale
  • cat-color-scale
• Scale Derivatives
  • scale-tics
  • scale-value
• Misc Helpers
  • immut-array
  • time-interval

Usage

{{d3-graph}}

d3-graph is used to provide root level selection to render discrete D3 elements, such as SVG <svg> and groups <g>. You can change this with by specifying the component's tagName (ie {{d3-graph (pipe ...) tagName="svg"}}).

It can be used inline.

{{d3-graph (pipe 
  (d3-attr "name" "fred")
)}}

It can be nested to allow multiple graph pipes to be rendered into the root component.

{{#d3-graph as |d3|}}
  {{d3.graph (pipe ...)}}
  {{d3.graph (pipe ...)}}
{{/d3-graph}}

You can pass a graph pipe into the parent component. The nested components will receive selection that's a result of the parent's graph pipe.

{{#d3-graph (pipe 
    (d3-select-all "rect")
    (d3-data data)
  ) as |d3|}}
  {{! selection here will be result of pipe above }}
  {{d3.graph (pipe ...)}}
  {{d3.graph (pipe ...)}}
{{

---

{{d3-element}}

d3-element is used to render simple SVG elements using d3's dynamic data join.

Properties

required

• element-name: a string specifying the type of SVG element to render (circle, rect, etc.)
• data: data to be bound to the component

optional

• selector: a unique selector string
• data-accessor: accessor function to pass to d3's data join method
• transition: a d3 transition object

Configurable Pipes

required

• on-enter

optional

• enter-transition
• update-transition
• on-update: if not provided, the post-transition update step uses on-enter (mirrors typical D3 behavior)
• exit-transition
• on-exit

example

{{d3-element
  element-name='circle'
  selector='rotator'
  data=points
  on-enter=(pipe
    (d3-attr 'cx' (r/get 'cx'))
    (d3-attr 'cy' (r/get 'cy'))
    (d3-attr 'r' 3)
  )
  update-transition=(pipe 
    (d3-attr 'r' 0)
  )
  on-exit=(pipe 
    (d3-attr 'r' 200)
  )
}}

---

Selection Helpers

(d3-select selector)

D3 Select

Select an element matching selector and return a selection object.

{{d3-graph (pipe 
  (d3-select "#my-link")
  (d3-attr "name" "fred")
)}}

(d3-select-all selector)

D3 Select All

Selects all elements that match the specified selector string.

{{d3-graph (pipe
  (d3-select-all "rect")
  (d3-data data)
  (d3-style "color" "red")
)}}

(d3-data data [key])

D3 Data

Joins the specified array of data with the selected elements, returning a new selection that it represents the update selection: the elements successfully bound to data.

{{d3-graph (pipe
  (d3-select-all "rect")
  (d3-data data key)
  (d3-join 
    enter=(pipe
      (d3-append "rect")
      (d3-text (r/get "number"))
    )
  )
)}}

(d3-join [enter=] [update=] [exit=])

Helper for implementing D3's general update pattern. This helper doesn't have a corresponding function in the API because this helper represents a pattern rather than a specific function in the API. Use it when you need to specify selection.enter().update().exit().

Read more about D3's General Update Pattern.

{{d3-graph (pipe
  (d3-select "svg")
  (d3-select-all "rect")
  (d3-data data)
  (d3-join
    enter=(pipe
      (d3-append "rect")
      (d3-text (r/param))
    )
    update=(pipe
      (d3-text (r/param))
    )
    exit=(pipe
      (d3-remove)
    )
  )
)}}

(d3-attr name value)

D3 Attr

Set attribute with specified name to specified value. Value can be a string or a function.

{{d3-graph (pipe
  (d3-select ".myelement")
  (d3-attr "name" name)
)}}

(d3-call (pipe ...))

D3 Call

Invokes the specified function exactly once, passing in this selection along with any optional arguments.

{{d3-graph (pipe 
  (d3-select ".test-items")
  (d3-call (pipe 
    (d3-select-all ".car")
    (d3-attr "color" "red")
  ))
  (d3-call (pipe
    (d3-select-all ".boat")
    (d3-attr "color" "blue")
  ))
  (d3-append 'i')
  (d3-attr "class" "truck")
)}}

---

Transition Helpers

(d3-transition [transition])

D3 Transition

Apply transition to a selection. Transition can be a name for this transition or a parent transition.

{{d3-graph (pipe 
  (d3-select-all "rect")
  (d3-data data)
  (d3-join
    enter=(pipe
      (d3-append "rect")
      (d3-attr height)
      (d3-transition)
      (d3-attr (r/get "y"))
  ))
)}}

(d3-transition-delay amount)

D3 Transition Delay

Apply a delay to a transition. Must be chained behind a transition.

{{d3-graph (pipe 
  (d3-join
    enter=(pipe
      (d3-append "rect")
      (d3-attr height)
      (d3-transition)
      (d3-delay 300)
      (d3-attr (r/get "y"))
  ))
)}}

(d3-attr-tween)

D3 Attr Tween

For each selected element, creates a tween for the attribute with the specified name with the specified interpolator value.

Good description of transition.attrTween can be found in this example.

---

Linear scales

linear-scale

D3 Linear Scale

export default Ember.Component.extend({
  domain: [0, 10],
  range: [0, 100]
});

{{#with (linear-scale domain range nice=true) as |scale|}}
  <span>I am {{scale-value scale 5}} 50 years old.</span>
{{/with}}

time-scale

D3 Time Scale

export default Ember.Component.extend({
  domain: [
    new Date(2016, 2, 1),
    new Date(2016, 2, 31)
  ]
});

{{#with (time-scale domain) as |scale|}}
  {{#each (scale-ticks scale (time-interval 'day')) as |date|}}
    <a>{{date}}</a>
  {{/each}}
{{/with}}

seq-color-scale

Sequential color scale description.

Ordinal scales

band-scale

Band scale description

point-scale

Point Scale description

cat-color-scale

Categorical color scale.

---

Scale Derivatives

scale-ticks

Scale ticks

scale-value

Get the calculated value from a scale

---

Misc Helpers

immut-array

Immutable array helper description

time-interval

A time interval helper.

---

Installation

• git clone this repository
• npm install
• bower install

Running

• ember server
• Visit your app at http://localhost:4200.

Running Tests

• npm test (Runs ember try:testall to test your addon against multiple Ember versions)
• ember test
• ember test --server

Building

• ember build

For more information on using ember-cli, visit http://www.ember-cli.com/.