colapdev / ngx-britecharts

@colap-dev/ngx-britecharts is an Angular2 library for creating and displaying Britecharts charts (https://github.com/eventbrite/britecharts/) in your web application using D3.js v4. Checkout the demo: https://colapdev.github.io/ngx-britecharts/

ngx-britecharts

@colap-dev/ngx-britecharts is an Angular2+ library for creating and displaying Britecharts in your web application using D3.js v4. Demo available for Angular's versions 2, 4 and 5.

Don't now what Britecharts is? Check this out.

Demo

Visit https://colapdev.github.io/ngx-britecharts/.

Installation

npm install @colap-dev/ngx-britecharts --save

Using it in your project

Include the charts module.

import { ChartModule } from '@colap-dev/ngx-britecharts/dist';

@NgModule({
  imports: [
    ...
    ChartModule,
    ...
  ],
  declarations: [
   ...
  ],
  providers: [
   ...
  ],
  bootstrap: [...]
})

Adding styles

In order to use the original Britecharts styles you'll need to include the needed CSS files. There's a base file for all charts and then each chart has it's own CSS.

@import '../../node_modules/britecharts/dist/css/common/common.min.css';
@import '../../../node_modules/britecharts/dist/css/charts/bar.min.css';
@import '../../../node_modules/britecharts/dist/css/charts/brush.min.css';
@import '../../../node_modules/britecharts/dist/css/charts/bullet.min.css';
@import '../../../node_modules/britecharts/dist/css/charts/donut.min.css';
@import '../../../node_modules/britecharts/dist/css/charts/grouped-bar.min.css';
@import '../../../node_modules/britecharts/dist/css/charts/line.min.css';
@import '../../../node_modules/britecharts/dist/css/charts/scatter-plot.min.css';
@import '../../../node_modules/britecharts/dist/css/charts/sparkline.min.css';
@import '../../../node_modules/britecharts/dist/css/charts/stacked-area.min.css';
@import '../../../node_modules/britecharts/dist/css/charts/stacked-bar.min.css';
@import '../../../node_modules/britecharts/dist/css/charts/step.min.css';

Chart types

Each chart type is defined by a number defined in the enum ChartType.

Bar = 1
Brush = 2
Bullet = 3
Donut = 4
GroupedBar = 5
Heatmap = 6
Legend = 7
Line = 8
ScatterPlot = 9
Sparkline = 10
StackedArea = 11
StackedBar = 12
Step = 13

Rendering the chart

HTML

<ngx-bc-chart #lineChart [data]="lineChartData" [chartConfig]="lineChartConfig" [chartType]="8"></ngx-bc-chart>

Component

@ViewChild('lineChart') lineChart: ChartComponent;
private lineChartData = [...];
private lineChartConfig = {
    properties: {
        isAnimated: true,
        aspectRatio: 0.5,
        grid: 'horizontal',
        tooltipThreshold: 600,
        margin: {
            top: 60,
            bottom: 50,
            left: 50,
            right: 30
        },
        dateLabel: 'fullDate',
    },
    click: this.onDemoLineChartClick,
    tooltip: {
        valueLabel: 'value',
        title: 'Quantity Sold',
    },
    loading: false
};

Check the demos for examples of chart configurations.

• The properties attributes are all optional, they correlate with their corresponding Britechart chart API.
• The click handler expects a function.
• If the tooltip attribute exists the corresponding tooltip for the chart will be set up. In some cases it is the Mini-tooltip and in others it is the Tooltip. Check Britechart docs for more info.
• If the loading attribute is present and it is true then the chart will show it loading state. Some charts doesn't have a loading state. In that case nothing will be shown (not even the chart).
• In some cases, specially the donut chart, you will like to have some properties values to be related to the container's width. To achieve this you'll have to define sizeRelativeToContainerWidth in the config object. Every key contained in it will have its value set by dividing the container's width by the value set. Check donutChartConfig in the examples to see how this works.
• If you would like to handle the custom events fired by the chart you should include the events attribute in the config. Each member of this attribute should be a custom event defined by Britecharts and a function to hanlde it. Check donutChartConfig in the examples to see how this works. Please mind that this may override the events used by the tootlip.

It's worth noting that all the API is exposed and public so you can interact with the chart and it's tooltip from your component. In the line chart example defined above you can access it and it's corresponding tooltip by doing:

this.lineChart.chart...
this.lineChart.tooltip...

Exporting the chart

To export the chart just call the exportChart function the chart exposes.

Parent:

HTML:

<ngx-bc-chart #lineChart ....></ngx-bc-chart>
<button (click)="exportChartClick()" ....>Export</button>

Component:

@ViewChild('lineChart') lineChart: ChartComponent;
private exportChartClick() {
    this.lineChart.chart.exportChart('Exported bar chart.png', 'Chart title');
}

The file name and chart title must be sent inside the event.

Data format

The data format used by the charts is the same defined by Britecharts, you can check each available type in their docs.

Running the demo

1. Clone this repo.
2. cd into demo folder.
3. npm install
4. npm run start
5. Browse to http://localhost:4200

Contributing

We are open to pull requests including:

• More demos.
• Better docs.
• Tests.

Support

Feel free to open any issue in case you need help.

Acknowledgments

Britecharts community, specially Marcos Iglesias for his support and patience.

@dzurico for this post http://www.dzurico.com/how-to-create-an-angular-library/.

ngx-britecharts's Issues

On a new install of angular 7 getting errors.

Getting this error when running the ng serve command
ERROR in node_modules/@colap-dev/ngx-britecharts/node_modules/rxjs/Subject.d.ts(24,5): error TS2416: Property 'lift' in type 'Subject<T>' is not assignable to the same property in base type 'Observable<T>'. Type '<R>(operator: Operator<T, R>) => Observable<T>' is not assignable to type '<R>(operator: Operator<T, R>) => Observable<R>'. Type 'Observable<T>' is not assignable to type 'Observable<R>'. Type 'T' is not assignable to type 'R'. node_modules/@colap-dev/ngx-britecharts/node_modules/rxjs/observable/dom/WebSocketSubject.d.ts(77,5): error TS2416: Property 'lift' in type 'WebSocketSubject<T>' is not assignable to the same property in base type 'AnonymousSubject<T>'. Type '<R>(operator: Operator<T, R>) => WebSocketSubject<R>' is not assignable to type '<R>(operator: Operator<T, R>) => Observable<T>'. Type 'WebSocketSubject<R>' is not assignable to type 'Observable<T>'. Types of property 'operator' are incompatible. Type 'Operator<any, R>' is not assignable to type 'Operator<any, T>'. Type 'R' is not assignable to type 'T'.

Bad commit hash for britecharts dependency

I have a project with a npm-shrinkwrap.json including the following:

   "@colap-dev/ngx-britecharts": {
      "version": "0.5.4",
      "resolved": "https://registry.npmjs.org/@colap-dev/ngx-britecharts/-/ngx-britecharts-0.5.4.tgz",
      "integrity": "sha1-MDPxaTtd1q7VDIBBP4/Yp8a1BDc=",
      "requires": {
        // ......
        "britecharts": "github:martinmanzo/britecharts#b3d501bab99390ef61e7879221f2ff10b22441ae",
        // ......
      },
      // .....
   }

But that commit (b3d501bab99390ef61e7879221f2ff10b22441ae) does not exist.
I can still build files on machines that have that version of britecharts in their npm cache, but on other machines npm install will fail:

npm install
EXEC : Unhandled rejection error : Command failed: C:\Program Files\Git\cmd\git.EXE checkout b3d501bab99390ef61e7879221f2ff10b22441ae 
fatal: reference is not a tree: b3d501bab99390ef61e7879221f2ff10b22441ae

I can only assume that some history re-writing has taken place in the martinmanzo/britecharts repository.

I can see that the currently published spec for ngx-britecharts version 0.5.4 uses "github:martinmanzo/britecharts#fork-master" as the version for the britecharts dependency, which does not seem like a correct way to ensure no breaking changes are accidentally included in new builds.

How can I ensure that my project continues to build using the same versions of britecharts that it has been previously, without relying on copying from my npm cache?

All I can think of is to try and work out which version of britecharts was actually used by comparing the contents of the zipped package in the npm cache with the history of the martinmanzo/britecharts repo, and then hand-code the commit in the npm-shrinkwrap.json file, but this does not seem a good way to go. Also if the martinmanzo/britecharts repo really has had history re-written, then I am not even guaranteed to find the correct version there.

Does it work with the new major NG releases?

I'm using angular v5 and this code

import {
  BarChartModule,
} from '@colap-dev/ngx-britecharts/dist';

@NgModule({
  bootstrap: [Components.Core],
  imports:   [
    ...
    BarChartModule,
    RouterModule.forRoot(routes),
  ],
  providers: [
    ...
  ],
  declarations: [
    ...
  ],
})
export default class CoreModule { }

causes a startup exception:

Uncaught Error: Unexpected value 'BarChartModule' imported by the module 'CoreModule'. Please add a @NgModule annotation.
    at syntaxError (vendor.js:84678)
    at vendor.js:99301
    at Array.forEach (<anonymous>)
    at CompileMetadataResolver.getNgModuleMetadata (vendor.js:99284)
    at JitCompiler._loadModules (vendor.js:117713)
    at JitCompiler._compileModuleAndComponents (vendor.js:117674)
    at JitCompiler.compileModuleAsync (vendor.js:117590)
    at CompilerImpl.compileModuleAsync (vendor.js:118834)
    at PlatformRef.bootstrapModule (vendor.js:5803)
    at Object.795 (boot.js:10567)

Calling BarChartModule.forRoot(), causes a similar error with different unexpected type:

Uncaught Error: Unexpected value '[object Object]' imported by the module 'CoreModule'. Please add a @NgModule annotation.
    at syntaxError (vendor.js:84678)
    at vendor.js:99301
    at Array.forEach (<anonymous>)
    at CompileMetadataResolver.getNgModuleMetadata (vendor.js:99284)
    at JitCompiler._loadModules (vendor.js:117713)
    at JitCompiler._compileModuleAndComponents (vendor.js:117674)
    at JitCompiler.compileModuleAsync (vendor.js:117590)
    at CompilerImpl.compileModuleAsync (vendor.js:118834)
    at PlatformRef.bootstrapModule (vendor.js:5803)
    at Object.795 (boot.js:10567)

Running `npm install @colap-dev/ngx-britecharts britecharts` installs an empty dependency

No files are published to npm