Developing and Using Angular Libraries
A developer gives a tutorial on how to create, configure, and use an Angular library, including all the TypeScript code you will need to get going.
Join the DZone community and get the full member experience.Join For Free
In the AngularAndSpring project charts are displayed. To display the charts I have developed the ngx-simple-charts library. The design goal is to be D3.js based, have a typesafe Angular API, and be so simple and small that it can be migrated fast to new Angular versions. Currently the library supports line charts, bar charts might be supported in the future.
Creating and Configuring the Angular Library
The Angular CLI can generate a library shell with this command:
ng generate library <library_name>
In the library shell you get a Module, a Component, and a Service. The library API is defined in the public-api file.
To add the D3 charts, the libraries and typings need to be added in the package.json:
The scripts part of the package.json has these additions:
The 'build-watch' script rebuilds the library on change. That helps development.
The 'build-prod' script builds the library with production settings that are needed to publish it on npm. According to the Angular team, libraries should not be published with Ivy enabled.
In the library folder, the package.json needs to get the library dependencies:
The 'peerDependencies' are expected from the project that uses the library.
The 'dependencies' are used to build the library.
The ng-package.json has the umd module config and the whitelisted dependencies:
If the 'umdModuleIds' are not provided, Angular will guess at them and the 'd3' dependencies need to be whitelisted.
Implementing the Charts in the Library
The component and the service have been moved to their own folders. To add the charts to the component the template has been updated:
The CSS classes offer some styling options and make the chart use all the space that is available in the div.
The SVG tag is the host element with the 'svgchart' reference variable of the chart that is generated with the D3 library.
The SCSS file makes the chart file the available space and provides some basic styling:
The 'd3-chart' and 'd3-chart-wrapper' classes can be used to change the chart size.
The 'line' class is used to set the line style.
The chart component is setup like this:
In lines 1-6, the 'sc-line-chart' component is defined.
In line 7, the interfaces
OnChanges are added.
In lines 8-9, the SVG element ref is added with the
ViewChild annotation that references the template variable. The 'static' option has to be set to get SVG element ref.
In line 10, the d3Svg selection is defined to get the D3 representation of the element ref.
In lines 11-12, the input component parameter
chartPoints is defined. That is expected to contain the chart values in the ChartPoints format.
In lines 13-16, the D3 attributes for the x axis, the y axis, and the chart path are defined.
In lines 18-19, the method
ngAfterViewInit initializes the
d3svg property with the SVG element ref. The
ngAfterViewInit method needs to be used because the
ViewChild annotated value has to be availiable.
In lines 21-25, the x axis and the y axis are set with its CSS classes and the path is initialized.
In line 27,
updateChart is called to render the chart.
In line 30, the
ngChanges method is used to get notified of updates of the component parameters.
In lines 31-33, the method checks for changes to the
chartPoints component parameter and filters out the first change. It calls then the
updateChart method to render the chart.
To render the charts the
updateChanges method is used:
In lines 2-9, the width and the height are read out from the SVG element.
In line 10, the viewbox is set for the SVG element.
In lines 11-16, the input values are validated.
In lines 19-28, the x scale is generated. It expects either a Date or a String value.
In lines 32-34, the y scale is generated. It expects a number value.
In lines 36-41, the chart line is generated. It supports the data types of the scales and filters out invalid values. The space between data points is filled by the
In lines 44-46, the chart line is added to the SVG element with the line class for styling.
In lines 47-51, the x scale is added to the SVG element.
In lines 52-55, the y scale is added to the SVG element.
The Library Interface
To use the library it needs a typesafe interface. That is defined in the Module and the public-api file:
In lines 1-4, the typescript files that should be exported are declared. They contain the public interface of the library.
The Angular library module file:
In lines 1-6, the Angular Module of the library is defined. It has the chart component, a service, and imports the Angular CommonModule that is needed in the chart component. The chart component is exported to be used by Angular projects.
The TypeScript types for the chart component are in the chart-point file:
ChartPoints interface defines the chart name, the scale widths, and the
Using the Library
The AngularAndSpring project uses the ngx-simple-charts library. During the development of the library the npm link feature can be used. The ngx-simple-charts/dist/ngx-simple-charts/ directory can be linked into the project that uses the library. Then, 'npm run build-watch' rebuilds the library if the code is changed.
Add the library to the package.json:
Install the library.
The library module is added to the details.module:
The imported Modules now include NgxSimpleChartsModule in line 10. The module declares the detail components to show the data and charts of the currencies.
The AngularAndSpring project has four components that display charts. The components have the common base class detail-base:
In lines 1-7, the abstract class with the common properties is defined.
In line 11, the method
updateChartData is defined with its common interface of Tuples.
In line 12, the chart points in the tuples are mapped in the
ChartPoint interface array.
In lines 13-14, an array of the
ChartPoints interface is created for the ngs-simple-charts library. The library expects a
ChartPoints array to be able to support multi-line charts in the future.
The 'sc-line-chart' component is used in the template bfdetail.component.html:
In line 2, the
sc-line-chart component of the library is used and the chart points are provided by the
DetailBase class that the component class BfdetailComponent extends.
Creating and publishing the ngx-simple-charts library took some time. The Angular CLI helped a lot by generating a base. The npm link feature help in the development process. The implementation is very close to the examples of D3.js. There are examples of other Angular libraries that can be used for ideas. With all that help it was possible to build this library quite fast and easier than expected. A thank you to the Angular Team for the user friendly library architecture and CLI support.
The Future of ngx-simple-charts
The library enables developer to quickly update to new Angular versions. It is intended that it will stay small and with few features. In the future there might be more features, but only if that does not interfere with the fast updates goal. There are no resources to make it a fully featured chart library.
Opinions expressed by DZone contributors are their own.