wealthbar / angular-d3

AngularJS directives for declaratively using D3

AngularJS-D3 Module

A set of AngularJS directives that provides a declarative syntax for building common charts using D3.

Installing

AngularD3 is available via Bower as angularD3

bower install angularD3

AngularD3 is available via NPM as angular_d3

npm install angular_d3

Project Goals

This provides an AngularJS module called ad3 which in turn provides a declarative HTML syntax for using D3 with AngularJS. The syntax has been inspired in part by Radian however at the time of starting this Radian was not available as an OSS project.

The goals of AngularD3 are:

• Provide a simple declarative syntax for common D3 graphs and charts
• An extensible core allowing for almost anything possible D3 to be expressed with a custom directive. You are able to both extend the existing chart visuals as well as create entirely new ones. One example might be adding special elements/labels that have their positions bound to data points based on the chart axes.
• Designed the "Angular Way (tm)" using similar style to extensibility and directive communication used by Angular directives like form and input. AngularD3 provides a d3Chart directive which provides d3ChartController analagously to ngFormController
• 100% stylable via CSS, with some added D3 'sugar' like allowing the use of the built in color scales with pie charts or being able to bind to a color scale from data.
• The ability to create custom directives that can both extend existing chart layouts as well as create new ones.

The overall goal of this project is to create a basic set of D3 directives that are sufficiently complete for flexible charts of most common types. To start: Bar, Line, Area, Pie, Arc. Additional chart elements, can be added either to enhance existing chart types or to create new ones simply by requiring d3ChartController.

AngularD3 is designed to provide enough flexibility to allow you to extend it with custom directives to do anything you could conceive of with D3 with no limitations, but still provide a convenient set of default functionality. Creating most simple graphs should be built in, while unlimited customization is still possible with relative ease.

If you have ideas and are interested in lending a hand, please open an issue, submit a pull request or just ping me @chrismnicola. This could be the beginning of beautiful friendship.

Current Directives

• d3-chart - Provides the top level directives meant to contain the rest of the chart declarations.
• d3-data - Provides a declarative way to load data into the current scope directly from a URL
• d3-axis - Defines an axis and provide it's range and location (top, left, bottom, right)
• d3-area - Define an area graph
• d3-line - Defines a line graph
• d3-bars - Defines a set of bars for a bar chart
• d3-gradient - Support for dynamically generating SVG gradients with data
• d3-include - Supports including arbitrary SVG with the chart

The directives are meant to be used to compost charts like so:

  <d3-data src="data/data.csv" data="line" columns="year, savings, total, optimal"></d3-data>
  <d3-data src="data/donutData.csv" data="pie" columns="age,population"></d3-data>
  <div d3-chart data="line" margin="{ top: 20, right: 30, bottom: 40, left: 20 }">
    <d3-axis name="year" label="Year" extent="true" orientation="bottom" ticks="5"></d3-axis>
    <d3-axis name="savings" label="Deposits" orientation="left" ticks="5"></d3-axis>
    <d3-axis name="total" label="Savings" orientation="right" ticks="5"></d3-axis>
    <d3-line x="year" y="optimal" yscale="total"></d3-line>
    <d3-area x="year" y="total"></d3-area>
    <d3-bars x="year" y="savings"></d3-bars>
  </div>

The d3-chart directive will first append <svg class="d3"><g></g></svg> to itself and then each inner directives will attach their own elements, using D3, from there. The d3ChartController provides access to its root <g></g> element via getChart() so that child directives can append themselves.

The d3-data directive provides a way of declaratively binding data, but this is entirely optional and it simply is a convenient way to bind a CSV data from any url directly to your current scope.

Documentation will be forthcoming as things develop but for now you will have to rely on a quick reading of the code.

Try it out

This project uses NPM and Webpack. To run it clone this repo and run:

npm install
npm start

Building

You can build a minified angularD3.js which will be saved in /dist by running

npm run-script build

You can also update the docs which will be saved in /docs by running

npm run-script docs

Feature Roadmap

• Basic chart forms for: Area, Line and Bars
• Supports multiple axis and multiple charts can be stacked
• Dynamically updating charts supporting animations (should be able to display and track incoming time-series data)
• Data source directives to declaratively specify and load external data sources and support D3's built in parsers for CSV, TSV, etc.
• Customizable chart legends
• Customizable and flexible labels
• Mouse and touch overlay support
• Scatter and Bubble plots
• Bullet charts
• Stacked area charts

If you have any other ideas for me, or feel like contributing to help add any of this missing functionality, I encourage you to submit a pull request.

License

Angular-D3 is free software under the MIT licence and may be redistributed under the terms specified in the MIT-LICENSE file.

angular-d3's Issues

Label and Axis Improvements

A few new use cases requiring some more flexibility in labeling.

• Allow label to be positioned more easily
• Allow a function based formatter to be bound to d3.tickFormat

Most likely I'll make the second one a breaking changes changing the string based format attribute to one that is evaluated thus:

format="$,.2"

will have to be changed to

format="'$,.2'"

Alternatively a non-breaking attribute could be introduced instead like d3-format, ng-format or bind-format which would be evaluated. I'm not sure this is really that much better though.

Is this project still active?

I was thinking about making something exactly like this, and some of the roadmap features are on my todo list (i.e. bubble charts, mouse events). I just want to make sure that it's still under active development, since I see that its been a while since most of the library was built.

Add directive to support dynamically generating gradients

This will be useful for cases where a custom gradient is needed. It should be bindable to data so that gradients can be used in representing information through colour codings.

Allow bar chart to be horizontal

Refactor most attributes for observation and expressions

Most of the directive attributes should be capable of binding using Angular expressions and they should use $observe to check for changes. This would allow functions, filters, etc. to be used with them and for the values to change dynamically.

Hover / touch

First off great module.

I noticed you had a task for tool tips , but it was fairly dated so I am just curious if this is still something you are planning on adding in.
Thanks

Build a nice looking demo site

Seriously need some help here.

Allow tickValues to be set

By only allowing ticks to be set D3 has control over how many ticks actually get displayed. This isn't always ideal or desired. Add an attribute to set ticksValues instead.

see: https://stackoverflow.com/questions/14444854/d3-axis-ticks-hard-count

bower name contains upper case 'angularD3'

bower invalid-meta The "name" is recommended to be lowercase, can contain digits, dots, dashes

`bower.json` references non-existent files

Hey, firstly kudos for building this!
The problem is: bower.json references "main": "dist/angularD3.js", but it is not shipped as a part of the Bower package.

Would you mind fixing that?

Rendering needs to be more extensible

We need a more extensible design for rendering. SVG is pretty limited in what can be done using CSS alone so sometimes you want to change the way something is rendered just slightly.

The built in directives should ideally support extensibility like this so that small changes can be made without necessarily having to replace them with a completely new directive that does mostly the same thing.

Documentation on json source data

The documentation seems poor; there are no live examples and no documentation about json source data

0.1 Feature Roadmap

Features planned for version 0.1

• Basic chart forms for: Area, Line and Bars
• Support for Donut/Pie charts
• Supports multiple axis and multiple charts can be stacked
• Dynamically updating charts supporting animations
• Support for dynamically updating time series data (with animations)
• Data source directives to declaratively specify and load external data sources and support D3's built in parsers for CSV, TSV, etc.
• Support for customizable chart legends
• Mouse-over and touch-based overlay support
• Improved documentation site

Add d3-include directive to allow for arbitrary SVG to be inserted

Something we ended up doing with WealthBar to support gradients was a directive that will inject arbitrary SVG elements from it's own element into the actual SVG. However I think an actual gradient directive might be better for that use case this will allow us to support more unforeseen use cases more easily.

Example

<d3-include>
  <defs>
    <lineargradient id="grad1">
      <stop offset="0%" style="stop-color:#00B298"></stop>
      <stop offset="100%" style="stop-color:#21bca5"></stop>
    </lineargradient>
  </defs>
</d3-include>

Axis labels are not redrawing after reszing

This may be related to the changes that added the grid lines to the axis.

Please provide a real demo

Instead of cleverly combining all the JS and CSS into single minified files, can you do what most other widgets do and provide actual demos that provide a simple model to follow to use the widget? I have no idea what the actual usage of this widget is by looking at the "demo" you provide.

issue running

cloned repo, ran

npm install

npm start

 http://localhost:8080/webpack-dev-server/
webpack result is served from /
content is served from /Users/joe/Documents/angular-d3
Hash: 34b80ebc88e09b465030
Version: webpack 1.15.0
Time: 3919ms
                                 Asset           Size  Chunks             Chunk Names
                          angularD3.js        1.66 MB       0  [emitted]  angularD3
  f4769f9bdb7466be65088239c12046d1.eot        20.1 kB          [emitted]  
 fa2772327f55d8198301fdb8bcfc8158.woff        23.4 kB          [emitted]  
  e18bbf611f2a2e43afc071aa2f4e1512.ttf        45.4 kB          [emitted]  
  89889688147bd7575d6327160d64e760.svg         109 kB          [emitted]  
  c61666832b100158d53116794e3e62b9.csv      552 bytes          [emitted]  
  414fa762ef1f59dc6fc6fb518300417f.csv      108 bytes          [emitted]  
448c34a56d699c29117adc64c43affeb.woff2          18 kB          [emitted]  
                                app.js        1.57 MB       1  [emitted]  app
                               app.css         148 kB       1  [emitted]  app
                      angularD3.js.map        1.94 MB       0  [emitted]  angularD3
                            app.js.map        1.84 MB       1  [emitted]  app
                           app.css.map        12.4 kB       1  [emitted]  app
                           favicon.ico  NaN undefined          [emitted]  
                            index.html       52 bytes          [emitted]  
chunk    {0} angularD3.js, angularD3.js.map (angularD3) 1.62 MB [rendered]
    [0] ./index.js 23 bytes {0} [built]
    [1] ./angularD3/index.coffee 455 bytes {0} [built]
    [2] ./~/angular/index.js 48 bytes {0} {1} [built]
    [3] ./~/angular/angular.js 1.25 MB {0} {1} [built]
    [4] ./angularD3/services/d3service.coffee 1.1 kB {0} [built]
    [5] ./~/d3/d3.js 337 kB {0} [built]
    [6] ./angularD3/services/d3locale.coffee 918 bytes {0} [built]
    [7] ./angularD3/directives/arc.coffee 2.25 kB {0} [built]
    [8] ./angularD3/directives/area.coffee 3.77 kB {0} [built]
    [9] ./angularD3/directives/axis.coffee 8.83 kB {0} [built]
   [10] ./angularD3/directives/bars.coffee 2.04 kB {0} [built]
   [11] ./angularD3/directives/chart.coffee 3.3 kB {0} [built]
   [12] ./angularD3/directives/data.coffee 506 bytes {0} [built]
   [13] ./angularD3/directives/gradient.coffee 1.33 kB {0} [built]
   [14] ./angularD3/directives/include.coffee 358 bytes {0} [built]
   [15] ./angularD3/directives/line.coffee 1.13 kB {0} [built]
   [16] ./angularD3/directives/pie.coffee 5.24 kB {0} [built]
chunk    {1} app.js, app.css, app.js.map, app.css.map (app) 1.52 MB [rendered]
    [0] ./app/index.js 167 bytes {1} [built]
    [2] ./~/angular/index.js 48 bytes {0} {1} [built]
    [3] ./~/angular/angular.js 1.25 MB {0} {1} [built]
   [17] ./~/jquery/dist/jquery.js 258 kB {1} [built]
   [18] ./app/scripts/app.coffee 593 bytes {1} [built]
   [19] ./angularD3/locale/en-US.js 577 bytes {1} [built]
   [20] ./angularD3/locale/fr-CA.js 571 bytes {1} [built]
   [21] ./angularD3/locale/zh-CN.js 492 bytes {1} [built]
   [22] ./app/scripts/main.coffee 236 bytes {1} [built]
   [23] ./app/scripts/main_controller.coffee 2.59 kB {1} [built]
   [24] ./app/data/data.csv 82 bytes {1} [built]
   [25] ./app/data/donutData.csv 82 bytes {1} [built]
   [26] ./app/scripts/main_view.html 3.35 kB {1} [built]
   [27] ./~/bootstrap/js/scrollspy.js 4.71 kB {1} [built]
   [28] ./~/bootstrap/dist/css/bootstrap.css 41 bytes {1} [built]
   [37] ./app/styles/index.scss 41 bytes {1} [built]

ERROR in Path must be a string. Received undefined
Child extract-text-webpack-plugin:
    chunk    {0} extract-text-webpack-plugin-output-filename 156 kB [rendered]
        [0] ./~/css-loader!./~/bootstrap/dist/css/bootstrap.css 154 kB {0} [built]
        [1] ./~/css-loader/lib/css-base.js 1.51 kB {0} [built]
        [2] ./~/bootstrap/dist/fonts/glyphicons-halflings-regular.eot 82 bytes {0} [built]
        [3] ./~/bootstrap/dist/fonts/glyphicons-halflings-regular.woff2 84 bytes {0} [built]
        [4] ./~/bootstrap/dist/fonts/glyphicons-halflings-regular.woff 83 bytes {0} [built]
        [5] ./~/bootstrap/dist/fonts/glyphicons-halflings-regular.ttf 82 bytes {0} [built]
        [6] ./~/bootstrap/dist/fonts/glyphicons-halflings-regular.svg 82 bytes {0} [built]
Child extract-text-webpack-plugin:
    chunk    {0} extract-text-webpack-plugin-output-filename 9.07 kB [rendered]
        [0] ./~/css-loader?sourceMap!./~/sass-loader?sourceMap!./app/styles/index.scss 7.57 kB {0} [built]
        [1] ./~/css-loader/lib/css-base.js 1.51 kB {0} [built]
webpack: Failed to compile.