FHI Angular Highcharts

An opinionated wrapper to the official minimal Highcharts wrapper for Angular

• FHI Angular Highcharts
  • Dependencies
  • Get started
    • Install
    • Add to app
    • Remove warnings
  • API
    • Inputs
    • Outputs
    • Interface FhiDiagramOptions
      • Using two units
    • Interface FhiDiagramControls
    • Interface FhiDiagramFooter
    • Interface FhiDiagramSerie
    • Interface FhiDiagramSerieData
    • Interface FhiDiagramFlag
    • Interface FhiDiagramUnit
  • Changelog
  • Contribute
  • Demo

Dependencies

| FHI Angular Highcharts | FHI Angular Componets | FHI Style | Bootstrap | NgBootstrap | Highcharts | Highcharts Angular | Angular | Node/NPM | | ---------------------- | --------------------- | --------- | --------- | ----------- | ---------- | ------------------ | ------- | -------- | | 5 | 5 | 6.3 | 5.3.2 | 17 | 11.4 | 4.0 | 18 | 20/10 * | | >4.1 | 4 | 6.3 | 5.3.2 | 16 | 11.4 | 4.0 | 17 | 18/10 * | | >=3.1 <=4.1 | 4 | 6.2 | 5.3.2 | 16 | 11.4 | 4.0 | 17 | 18/10 * | | 3 | 4.0 | 6 | 5.3.2 | 16 | 11.1 | 4.0 | 17 | 18/10 * | | 2 | 3.1 | 5.9 | 5.3.2 | 16 | 11.1 | 4.0 | 17 | 18/10 * | | 1 | - | 5 | 5 | 15 | 11.1 | 4.0 | 16 | 18/9 * | | 0.7 | - | 5 | 5 | 14 | 11.1 | 3.1.2 | 15 | 18/9 * | | 0.6 | - | 5 | 5 | 14 | 10.3.3 | 3.1 | 15 | 18/9 * | | 0.5 | - | 5 | 5 | 14 | 10.3.3 | 3.1 | 15 | 18/9 * | | 0.4 | - | 5 | 5 | | 10.3.3 | 3.1 | 15 | 18/9 * | | 0.3 | - | 5 | 5 | | 10.3.3 | 3.1 | 15 | 18/9 * | | 0.2 | - | 4 | 5 | | 10.3.3 | 3.1 | 15 | 18/9 * | | 0.1 | - | 4 | 5 | | 10.3 | 3 | 14 | 16/8 * |

For more dependencies see peerDependencies in package.json

* designsystem.fhi.no uses these Node/NPM versions, older versions may work, but then you're on your own :wink:

Get started

Install

Install with npm: npm install @folkehelseinstituttet/angular-highcharts

Add to app

After installing the package and all dependencies, add the following code to your app:

// In global css-file (usually style.scss)
@import "@folkehelseinstituttet/angular-highcharts/styles/import/all";

// In a standalone component or a shared module
import { FhiAngularHighchartsModule } from '@folkehelseinstituttet/angular-highcharts';
...
  imports: [FhiAngularHighchartsModule]
...

// In a component (.ts)
import { FhiDiagramOptions, FhiDiagramSerie, FhiDiagramTypeIds } from '@folkehelseinstituttet/angular-highcharts';
...
  data: FhiDiagramSerie[] = [...];
  diagramOptions: FhiDiagramOptions = {
    title: 'Diagram title',
    data: data,
    diagramTypeId: 'line'
  };
...

<!-- In a template -->
<fhi-angular-highcharts [diagramOptions]="diagramOptions"></fhi-angular-highcharts>

Remove warnings

Highcharts gives some warnings due to the use of CommonJs as described here: https://github.com/highcharts/highcharts/issues/14183

From one of the comments:

Highcharts uses the UMD pattern which includes AMD, and it is probably detected by angular. On the other hand, I don't think that using an ES6 module pattern will change anything in the performance matters, you would have to import the entire highcharts core anyway, so technically it will be the same package - I would suggest ignoring the warning by adding Highcharts to the allowedCommonJsDependencies property in the angular.json file.

This is where allowedCommonJsDependencies is located in angular.json

...
      "architect": {
        "build": {
          "builder": "@angular-devkit/build-angular:browser",
          "options": {
            "allowedCommonJsDependencies": ["highcharts"],
...

API

Inputs

| Input | Type | Default | Required | Description | | ------------------ | ------------------- | ------- | -------- | ----------- | | [diagramOptions] | FhiDiagramOptions | - | yes | All properties used to configure the diagram. See FhiDiagramOptions for details. NB! The object sent in to @Input diagramOptions needs to be reassigned for change detection to kick in. |

Outputs

| Output | Event type | Description | | -------------------------- | ------------------- | ----------- | | (diagramTypeNavigation) | FhiDiagramTypeIds | If diagram type navigation i visible, this event will fire on every navigation. Outputs an existing diagram type id. | | (metadataButtonClick) | void | When link to "Om dataene" is clicked. |

Interface FhiDiagramOptions

| Property | Type | Default | Required | Description | | ------------------- | -------------------- | --------- | -------- | ----------- | | activeDiagramType | string | - | no | ID to specify default diagram type. Values defined by enum FhiDiagramTypeIds | | controls | FhiDiagramControls | - | no | Properties related to controls like navigation. See FhiDiagramControls for details. | | footer | FhiDiagramFooter | - | no | Properties related to the footer below the diagram. See FhiDiagramFooter for details. | | [openSource] | boolean | true | no | If false; the link to Highcharts.com disappears, AND LICENSE IS REQUIRED! | | [series] | FhiDiagramSerie[] | - | yes | The data used to render a diagram. See FhiDiagramSerie for details. | | tableOrientation | string | - | no | Transpose table by setting preferd orientation. Values defined by enum FhiTableOrientations | | title | string | - | yes | The title above the diagram. | | units | FhiDiagramUnit[] | - | no | Decimal count, and metadata for y-axis and tooltip. See FhiDiagramUnit for details. Currently only diagram type columnAndLine supports two units, all other diagram types supports max 1 unit. See below this table for more info about using two units. |

Using two units

Only diagram type columnAndLine supports two units, and to make it work

• both units must have an id (see FhiDiagramUnit for more info about unit id)
• at least two series must have unitId (with two unique values), and those ids must be present in the units array

Also nice to know

• the first "unit" in "units" will always represent the left y-axis
• and series associated with the first "unit" in "units" will always become columns

Interface FhiDiagramControls

| Property | Type | Default | Required | Description | | ----------------------------- | ---------- | ------- | -------- | ----------- | | fullScreenButton | object | - | no | Properties related to fullScreenButton. | | fullScreenButton.show | boolean | false | yes | Whether to show a button which opens the diagram in full screen. | | metadataButton | object | - | no | Properties related to metadata button. | | metadataButton.show | boolean | false | yes | Whether to show a button with an event for custom navigation to your metadata. | | navigation | object | - | no | Properties related to diagram type navigaton. PS. navigation.items will always contain table, therefore no navigation.items.table as part of the items interface. | | navigation.items.chartTypes | string[] | - | no | Chart types to show in diagram type navigaton defined by enum ChartTypeIds. | | navigation.items.mapTypes | string[] | - | no | Map types to show in diagram type navigaton defined by enum MapTypeIds. | | navigation.show | boolean | false | yes | Whether to show diagram type navigaton. | | navigation.type | string | - | no | ID to specify which type of navigation to use defined by enum DiagramTypeNavIds. | | tableOrientationButton | object | - | no | Properties related to tableOrientationButton. | | tableOrientationButton.show | boolean | false | yes | Whether to show a button which toggles rows/columns in the diagram type table. Not implemented yet, so has no effect atm. |

Interface FhiDiagramFooter

| Property | Type | Default | Required | Description | | -------------- | ------------------ | ------- | -------- | ----------- | | credits | object | - | no | Properties related to source ref. | | credits.href | string | - | yes | Link to source ref. | | credits.text | string | - | yes | Text to source ref. | | disclaimer | string | - | no | Text at the bottom of the footer used to say something about uncertainty in the data shown in a diagram. | | [flags] | FhiDiagramFlag[] | - | no | List of all flags used in FhiDiagramSerie[]. See FhiDiagramFlag for details. | | lastUpdated | string | - | no | Text after label Sist oppdatert in footer. Free format, but dd.mm.yyyy is the most common one. |

Interface FhiDiagramSerie

| Property | Type | Default | Required | Description | | -------- | ------------------------| ------- | -------- | ----------- | | data | FhiDiagramSerieData[] | - | yes | The individual data points in a serie. See FhiDiagramSerieData for details. | | name | string \| string[] | - | yes | The name of the serie as shown in the legend. NB! The type string is an formatted string; pipe (\|) is beeing used as seperator between category names if more than one category name is concatenated to one single serie name. To avoid dependency on a given separator, use an array of category names instead. NB! series can not contain duplicate serie.name | | stack | string | - | yes | This option allows for grouping series in a stacked chart. Only applies to diagramTypeId barStacked and columnStacked. | | unitId | number \| string | - | no | Used to associate the serie with a unit. This only works if unit.id (FhiDiagramUnit) is set, and value is equal to serie.unitId. |

Interface FhiDiagramSerieData

FhiDiagramSerieData is a custum type for FHI Angular Highcharts, but it is based on the smallest possible subset of the chart.series.[chart type].data object as described under nr 3. here (line chart used as example).

| Property | Type | Default | Required | Description | | -------- | ------------------ | ------- | -------- | ----------- | | name | string | - | yes | The name of the data point as shown in the tooltip. | | y | number \| string | - | yes | The value of the data point. If type is string the data point is treated as a flagged value. |

Interface FhiDiagramFlag

| Property | Type | Default | Required | Description | | -------- | -------- | ------- | -------- | ----------- | | label | string | - | yes | Description of the flag, ie. Anonymized | | symbol | string | - | yes | Symbol representing the flag, ie. :. |

Interface FhiDiagramUnit

| Property | Type | Default | Required | Description | | ---------- | ------------------ | ------- | -------- | ----------- | | id | number \| string | - | no | Used to associate the unit with a serie. This only works if a serie.unitId (FhiDiagramSerie) is set, and value is equal to unit.id. | | decimals | number | - | no | The decimal count. If not set the decimal count is same as in the source data. Count is limited to 9 decimals because Highcharts tooltips fails if 10 decimals or more. A warning will be given in the consol if more than 14 decimals. | | label | string | - | yes | The vertical y-axis label, showing next to the axis line. | | symbol | string | - | no | Symbol before or after the value in both tooltip and y-axis. | | position | string | - | no | Wether the symbol i placed before or after the numbers in the diagram. Possible values: 'start' \| 'end' | | yAxisMax | number | - | no | The maximum value of the y-axis. If not set, the max value is automatically calculated. NB! Highcharts may override the value in some edge cases. | | yAxisMin | number | - | no | The minimum value of the y-axis. If not set, the min value is automatically calculated. NB! Highcharts may override the value in some edge cases. |

Changelog

You find the changelog here.

Contribute

Read about how to contribute here

Demo

• Live example in our demo app: https://designsystem.fhi.no
• Repo for demo app: https://github.com/folkehelseinstituttet/Fhi.Frontend.Demo