How to Integrate a D3 timeseries component

In this tutorial a stepwise instruction will be given on how to integrate a D3 timeseries component into an angular app (ng-app).

First initialize an app as described in the prepare section here or integrate this component in an existing project.

Step 1: import helgoland dependencies

To start working with the helgoland D3 component a few dependencies are needed: helgoland-d3 and helgoland-core are necessary to provide the D3 timeseries component, in detail, to visualize the diagram containing the dataset graphs and to get accesss via the dataset API. For translations ngx-translate is used and the ngx-translate-http-loader will load the translations.

Import dependencies to your ng-app by adding the following javascript code to src/app/app.module.ts:

// Add dependencies for helgoland components.
import { HelgolandD3Module } from '@helgoland/d3';
import { DatasetApiInterface, SplittedDataDatasetApiInterface } from '@helgoland/core';

// Add dependencies for translations.
import { HttpClient } from '@angular/common/http';
import { TranslateLoader, TranslateModule } from '@ngx-translate/core';
import { TranslateHttpLoader } from '@ngx-translate/http-loader';

Another step is to add the dependencies correctly to the @NgModule. As imports we will define the TranslateModule and the HelgolandD3Module and as providers we need to take the DatasetApiInterface with the SplittedDataDatasetApiInterface as useClass. To use the translation functions we will add a function called HttpLoaderFactory which is to be exported. You can compare your src/app/app.module.ts file with the following code below:

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    TranslateModule.forRoot({
      loader: {
        provide: TranslateLoader,
        useFactory: HttpLoaderFactory,
        deps: [HttpClient]
      }
    }),
    HelgolandD3Module
  ],
  providers: [
    {
      provide: DatasetApiInterface,
      useClass: SplittedDataDatasetApiInterface
    }
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }

export function HttpLoaderFactory(http: HttpClient) {
  return new TranslateHttpLoader(http);
}

Suggestions for error handling

• Cannot find namespace 'GeoJSON' see below

By manually adapting the configuration in src/tsconfig.app.js this issue should be solved. But to let the changes be accepted, the app has to be restarted (by executing ng serve). Add to the types-array the type geojson which then should look like this:

{
  "extends": "../tsconfig.json",
  "compilerOptions": {
    "outDir": "../out-tsc/app",
    "baseUrl": "./",
    "module": "es2015",
    "types": ["geojson"]
  },
  "exclude": [
    "test.ts",
    "**/*.spec.ts"
  ]
}

Step 2: add code

Now we will integrate the directive of the D3 timeseries component. Implement the directive of the graph by adding the following code to src/app/app.component.html. All fields in the n52-d3-timeseries-graph-directive are required to provide options, datasets and other information. Every other code that was generated by the app creation is not necessary to run the D3 timeseries component. This can be deleted or kept for further coding.

<div>
  <n52-d3-timeseries-graph [datasetIds]="datasetIdsMultiple" [selectedDatasetIds]="selectedIds" [datasetOptions]="datasetOptionsMultiple" [timeInterval]="timespan" (onTimespanChanged)="timespanChanged($event)" [graphOptions]="diagramOptionsD3"></n52-d3-timeseries-graph>
</div>

• Optional the style can be adapted by adding a css style modification to the directive. For example the following code will change the size:

<div style="height: 500px; width: 100%;"></div>

This code is implemented in the helgoland-toolbox github repository and can be viewed here.

Implement the functionality of the n52-d3-timeseries-graph-directive by adding the following code to the class AppComponent in src/app/app.component.ts:

• Attention: If you would like to have pre-selected colors for your graph, you can change and add the color as string in the array of the variable colors. If you do not provide any color-entries in the array or not enough color-entries with this array, all missing colors will be randomly generated in the D3 timeseries component, because each graph needs an own color-entry.

// These variables define the links for accessing the datasets and in which colors they are styled.
public datasetIdsMultiple = ['https://www.fluggs.de/sos2/api/v1/__63', 'https://www.fluggs.de/sos2/api/v1/__72'];
public colors = ['#123456', '#FF0000'];

// The timespan will be set to the last 28 hours which is calculated in milliseconds (milliseconds*1000 = 100000000).
public timespan = new Timespan(new Date().getTime() - 100000000, new Date().getTime());

// These are the plotting options. The boolen of 'togglePanZoom' is set to 'true' to pan the graph.
public diagramOptionsD3: D3PlotOptions = {
    togglePanZoom: true,
    showReferenceValues: false,
    generalizeAllways: true
};

// 'selectedIds' determines the graphs that are visualized with a larger stroke-width. This can be set by clicking on the y-axis.
public selectedIds: string[] = [];
public datasetOptionsMultiple: Map<string, DatasetOptions> = new Map();

constructor() {
    this.datasetIdsMultiple.forEach((entry, i) => {
        this.datasetOptionsMultiple.set(entry, new DatasetOptions(entry, this.colors[i]));
    });
}

// This function changes the timespan of the graph which is needed for panning (and zooming).
public timespanChanged(timespan: Timespan) {
    this.timespan = timespan;
}

This code is implemented in the helgoland-toolbox github repository and can be viewed here.

A very important step should not be missed
To use the functionality of the functions in the src/app/app.component.ts we need to add the dependencies to use for example Timespan and D3PlotOptions. This is done by using the following imports:

import { DatasetOptions, Timespan } from '@helgoland/core';
import { D3PlotOptions } from '@helgoland/d3';

Step 3: start working

Now, that we have added all dependencies and the code to access the functionality of the D3 timeseries component you can start working on your app. If you did not run the app while following this tutorial you should now see the timeseries graph by starting your app with ng serve.

Additional Options

Add initial min, max value for y axis

It is possible to emit a min and max value for the y-axis with the DatasetOptions for each dataset. With these values, the y-axis will only show the selected y-range. Some restrictions are:

• If there is no data provided in the selected timerange and y-axis min/max values, the default min and max range will be used.
• If the y-axis min and max values are equal, the default min and max range will be used.

Zero-based y axis

It is possible to set a boolean in the DatasetOptions (zeroBasedYAxis) to show the y axis with minimum as 0, if the data in the selected timerange is above 0, or maximum 0, if the data in the selected timerange is below 0.