Skip to content

Latest commit

 

History

History
465 lines (356 loc) · 10.8 KB

README.md

File metadata and controls

465 lines (356 loc) · 10.8 KB
Raw

Build Status

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

Helpers

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")
)}}

(d3-on typenames [listener [capture]])

D3 On

Adds or removes a listener to each selected element for the specified event typenames. The specified listener will be evaluated for each selected element, being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element.

An optional capture flag may be specified which corresponds to the W3C useCapture flag.

{{d3-graph (pipe
  (d3-select ".test-items")
  (d3-call (pipe
    (d3-select-all ".car")
    (d3-on "click" listener)
  ))
)}}

Shape Helpers

(d3-arc params {innerRadius, outerRadius, startAngle, endAngle})

D3 Arc

The arc generator produces a circular or annular sector, as in a pie or donut chart.

(d3-area [xScale, yScale] {xAccessor, yAccessor})

D3 Areas

The area generator produces an area, as in an area chart.

{{d3-graph
  (pipe
    (d3-select-all 'path')
    (d3-data data)
    (d3-join
      enter=(pipe
        (d3-append 'path')
        (d3-attr 'd'
          (d3-area
            xScale
            yScale
            xAccessor=(d3-get 'x')
            yAccessor=(d3-get 'y')
          )
        )
      )
    )
  )
}}

(d3-line [xScale, yScale] {xAccessor, yAccessor})

D3 Lines

The line generator produces a spline or polyline, as in a line chart.

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 <repository-url> this repository
  • cd ember-d3-helpers
  • npm install
  • bower install

Running

Running Tests

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

Building

  • ember build

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