@eqproject/eqp-dashboard v3.0.0

Table of contents

• Getting started
• Use cases
• API
• Credits

Required

• Angular Material installed and imported
• ngx-echarts installed (Check compatibility with your angular version)
• @juggle/resize-observer
• echarts
• @angular-material-components/datetime-picker (v2.0.4)
• @angular-material-components/moment-adapter
• Moment.js

Getting started

This package allows the creation of a flexible dashboard with different types of widgets. Each widget may contain various information such as graphs, statistics or entire external components

Step 1: Install eqp-dashboard:

NPM

npm install --save @eqproject/eqp-dashboard

Step 2: Import the EqpDashboardModule :

import { EqpDashboardModule } from '@eqproject/eqp-dashboard';

@NgModule({
  declarations: [AppComponent],
  imports: [EqpDashboardModule],
  bootstrap: [AppComponent]
})
export class AppModule {}

API

Inputs

Outputs

Models used

WidgetConfig Model: class for configure each individual widget

EndPointData Model

EndPointDataParams Model

EndpointParamCvlConfig Model

Static exposed functions

StatisticItem Model

LineChartOption Model

Describes the model for configuring LINE type charts | Property | Description | Type | Required | Examples | | ------------- | ------------- | ------------- | ------------- | ------------- | | xAxis | The data configuration for the X Axis of the chart | XAxisConfig | yes | View use cases 1 | | yAxis | The data configuration for the Y Axis of the chart | YAxisConfig | yes | View use cases 1 | | series | The data configuration for the X Axis of the chart | LineSeriesData | LineSeriesData[] | yes | View use cases 1 | | legend | The data configuration for chart legend (automatically set to show the legend) | LineLegend | no | - | | tooltip | The data configuration for chart tooltip (automatically set to show tooltips on hover) | LineTooltip | no | - |

Static exposed functions | Name | Returned Type | Parameters | Examples | | ------------- | ------------- | ------------- | ------------- | | CreateLineChartModel | LineChartOptions | labels: string[], seriesData: Map<string, number[]>, yAxisPosition? : string, seriesColors?: string[] | labels: list of labels for the X axis ; seriesData: Dictionary containing the configuration of the series of values to be shown for the bar chart; yAxisPosition : String that determines the position of the Y axis (left or right); seriesColors: Allows you to define the colors to be used for each series of the chart. The array is positional so the first color will be attributed to the first series, the second color to the second series etc ... |

BarChartOption Model

Describes the model for configuring BAR type charts | Property | Description | Type | Required | Examples | | ------------- | ------------- | ------------- | ------------- | ------------- | | xAxis | The data configuration for the X Axis of the chart | XAxisConfig | yes | View use cases 2 | | yAxis | The data configuration for the Y Axis of the chart | YAxisConfig | yes | View use cases 2 | | series | The data configuration for the X Axis of the chart | LineSeriesData | LineSeriesData[] | yes | View use cases 2 | | legend | The data configuration for chart legend (automatically set to show the legend) | LineLegend | no | - | | tooltip | The data configuration for chart tooltip (automatically set to show tooltips on hover) | LineTooltip | no | - |

Static exposed functions | Name | Returned Type | Parameters | Examples | | ------------- | ------------- | ------------- | ------------- | | CreateBarChartModel | BarChartOptions | labels: string[], seriesData: Map<string, number[]>, yAxisPosition? : string, seriesColors?: string[] | labels: list of labels for the X axis ; seriesData: Dictionary containing the configuration of the series of values to be shown for the bar chart; yAxisPosition : String that determines the position of the Y axis (left or right); seriesColors: Allows you to define the colors to be used for each series of the chart. The array is positional so the first color will be attributed to the first series, the second color to the second series etc ... |

PieChartOption Model

Describes the model for configuring PIE type charts | Property | Description | Type | Required | Examples | | ------------- | ------------- | ------------- | ------------- | ------------- | | tooltip | object that defines the trigger property for the tooltip configuration | any | no | View use cases 3 | | legend | object that defines the properties orient e left for the legend configuration | any | no | View use cases 3 | | series | Defines the series data for the chart | PieSeries[] | no | View use cases 3 | | isDoughnut | If TRUE then show a DoughnutChart else show a PieChart | boolean | no | Default value: false |

Static exposed functions | Name | Returned Type | Parameters | Examples | | ------------- | ------------- | ------------- | ------------- | | CreatePieChartModel | PieChartOptions | seriesData: Map<string, PieSeriesValue[]>, isDoughnut: boolean | seriesData: Dictionary containing as many keys as there are different series to show in the chart, for each series it is necessary to indicate a list of values that make up the data of the same series; isDoughnut: Allows you to decide whether to show a pie chart or a doughnut chart |

PieSeries Model

Describes the model for configuring PIE series charts | Property | Description | Type | Required | Examples | | ------------- | ------------- | ------------- | ------------- | ------------- | | name | Name of the pie chart serie | string | yes | View use cases | | type | Type of the pie chart serie (set by default to the 'pie' value) | string | yes | View use cases 3 | | data | array of values that make up the single series of the graph | PieSeriesValue[] | no | View use cases 3 | | radius | Default set with the value 50% | string | yes | View use cases 3 |

PieSeriesValue Model

Describes the model for configuring PIE series charts | Property | Description | Type | Required | Examples | | ------------- | ------------- | ------------- | ------------- | ------------- | | name | Name of value of the serie | string | yes | View use cases | | value | Single value of the serie | number | yes | View use cases 3 | | itemStyle | Define the color to apply for the value of the chart (default NULL: use the standard color) | PieSeriesValueColor | no | An object of type PieSeriesValueColor with property color. The 'color' property is a string that can contain RGB or rgba function |

RadarChartOption Model

Describes the model for configuring RADAR type charts | Property | Description | Type | Required | Examples | | ------------- | ------------- | ------------- | ------------- | ------------- | | legend | Define the configuration for the chart legend | RadarLegendData | no | View use cases 4 | | tooltip | Define the configuration for the chart tooltip (automatically set to show tooltips on hover) | RadarTooltip | no | View use cases 4 | | radar | Define the indicator marker configuration for the chart | RadarIndicator[] | yes | View use cases 4 | | series | Define the series for the chart | RadarSeries[] | yes | View use cases 4 |

Static exposed functions | Name | Returned Type | Parameters | Examples | | ------------- | ------------- | ------------- | ------------- | | CreateRadarChartModel | RadarChartOption | legendLabels: string[]; radars: Map<string,RadarIndicatorData[]> ;seriesData: Map<string, PieSeriesValue[]>; radiusChartPercentage: string,showTooltip: boolean , fillChartArea: boolean | legendLabels: List of labels to be used as chart legend. If the char contains only one radar then the array must contain only one element otherwise it will contain one for each different radar;radars: Dictionary containing the configurations of all the radars to be shown in the chart. Each node of the dictionary must contain as a key the name to be attributed to the radar and the configuration of the radar indicators;seriesData: Dictionary containing the configuration of the series of values to be shown for each configured radar; radiusChartPercentage: Indicates the scaling percentage of the radars (default value = 75%); showTooltip: If TRUE then configure the tooltips for the chart (in the tooltip will be shown the values of the radar series on which you hover with the mouse); fillChartArea: If TRUE then for each radar it applies a style that will allow you to color the entire area drawn in the radar; |

RadarLegendData Model

RadarIndicatorData Model

RadarSeries Model

RadarSeriesData Model

GaugeChartOption Model

Static exposed functions | Name | Returned Type | Parameters | Examples | | ------------- | ------------- | ------------- | ------------- | | CreateGaugeChartModel | GaugeChartOptions | seriesData: Map<string, GaugeChartData[]> | seriesData: Dictionary containing the configuration of the series of values to be shown for the gauge chart |

GaugeChartSeries Model

GaugeChartDetailData Model

GaugeChartData Model

Use cases

Use Example in class :

Define selector in html

<eqp-dashboard [configs]="chartConfigs"></eqp-dashboard>

Define locale in the app.component.ts in order to set it for all the charts (the default value is 'it-IT')

    constructor(private eqpDashboardService : EqpDashboardService) { }
    
    ngOnInit(): void { }

    this.eqpDashboardService.setLocale('en-US')

CASE 1: Define variables and object to use to display a basic Line Chart Widget

    chartConfigs: WidgetConfig[];

    let lineChartConfig: WidgetConfig = new WidgetConfig();
    lineChartConfig.WidgetID = "Dashboard_LineChart";
    lineChartConfig.WidgetTitle = "Line Chart"
    lineChartConfig.WidgetSizeClass = WidgetSizeEnum.XS;
    lineChartConfig.WidgetType = WidgetTypeEnum.LINE_CHART;
    let lineSeriesData: Map<string, number[]> = new Map<string,number[]>();
    lineSeriesData.set("Serie 1", [10,25,35]);
    lineChartConfig.ChartOptions = LineChartOption.CreateLineChartModel(["Valore 1", "Valore 2", "Valore 3"], lineSeriesData);

    this.chartConfigs.push(lineChartConfig);

CASE 2: Define variables and object to use to display a basic Bar Chart Widget

    chartConfigs: WidgetConfig[];

    let barChartConfig: WidgetConfig = new WidgetConfig();
    barChartConfig.WidgetID = "Dashboard_BarChart";
    barChartConfig.WidgetTitle = "Bar Chart"
    barChartConfig.WidgetSizeClass = WidgetSizeEnum.XS;
    barChartConfig.WidgetType = WidgetTypeEnum.BARS_CHART;
    let barSeriesData: Map<string, number[]> = new Map<string,number[]>();
    barSeriesData.set("Serie 1", [10,25,35]);
    barChartConfig.ChartOptions = BarChartOption.CreateBarChartModel(["Valore 1", "Valore 2", "Valore 3"], barSeriesData);

    this.chartConfigs.push(barChartConfig);

CASE 3: Define variables and object to use to display a basic Pie Chart Widget

    
    chartConfigs: WidgetConfig[];

    let pieChartConfig: WidgetConfig = new WidgetConfig();
    pieChartConfig.WidgetID = "Dashboard_Pie";
    pieChartConfig.WidgetTitle = "Pie Chart"
    pieChartConfig.WidgetSizeClass = WidgetSizeEnum.XS;
    pieChartConfig.WidgetType = WidgetTypeEnum.PIE_CHART;
    let pieSeries: Map<string, PieSeriesValue[]> = new Map<string, PieSeriesValue[]>();
    pieSeries.set("Serie 1", [{name: "A", value: 10},{name: "B", value: 25},{name: "C", value: 37},{name: "D", value: 42}]);
    pieChartConfig.ChartOptions = PieChartOption.CreatePieChartModel(pieSeries);
    
    this.chartConfigs.push(pieChartConfig);

CASE 4: Define variables and object to use to display a basic Radar Chart Widget

    chartConfigs: WidgetConfig[];

    let radarChartConfig: WidgetConfig = new WidgetConfig();
    radarChartConfig.WidgetID = "Dashboard_Radar";
    radarChartConfig.WidgetTitle = "Radar chart"
    radarChartConfig.WidgetSizeClass = WidgetSizeEnum.XS;
    radarChartConfig.WidgetType = WidgetTypeEnum.RADAR_CHART;

    let seriesName: string = "Serie 1";
    let indicators: Map<string, RadarIndicatorData[]> = new Map<string,RadarIndicatorData[]>();
    indicators.set(seriesName, [{ text: "Valore 1", max: 100}, { text: "Valore 2", max: 100}, { text: "Valore 3", max: 100}, { text: "Valore 4", max: 100}, { text: "Valore 5", max: 100}]);

    let seriesData: Map<string, RadarSeriesData[]> = new Map<string,RadarSeriesData[]>();
    seriesData.set(seriesName, [{ name: "Serie 1", value: [10,25,35,40,80] }]);
    radarChartConfig.ChartOptions = RadarChartOption.CreateRadarChartModel([seriesName], indicators, seriesData);

    this.chartConfigs.push(radarChartConfig);

CASE 5: Define variables and object to use to display a basic Gauge Chart Widget

    
    chartConfigs: WidgetConfig[];

    let gaugeChartConfig: WidgetConfig = new WidgetConfig();
    gaugeChartConfig.WidgetID = "Dashboard_Gauge";
    gaugeChartConfig.WidgetTitle = "Gauge chart"
    gaugeChartConfig.WidgetSizeClass = WidgetSizeEnum.XS;
    gaugeChartConfig.WidgetType = WidgetTypeEnum.GAUGE_CHART;

    let gaugeSeries: Map<string, GaugeChartData[]> = new Map<string, GaugeChartData[]>();
    gaugeSeries.set("Valore 1", [ { name: "Km/h", value: 50}])
    gaugeChartConfig.ChartOptions = GaugeChartOption.CreateGaugeChartModel(gaugeSeries)

    this.chartConfigs.push(gaugeChartConfig);

CASE 6: Define the variables and object to use to display Chart Widget by calling a custom endpoint to fetch Chart Data

    @ViewChild('externalTemplate', { static: true }) externalTemplate: TemplateRef<any>;

    constructor() {

    }

    ngOnInit() {
      this.configureWidget();
    }

    configureWidget() {
      endPointChart: WidgetConfig = new WidgetConfig();
      chartConfigs: WidgetConfig[];

      this.endPointChart.WidgetTitle = "EndPoint Chart";
      this.endPointChart.WidgetType = WidgetTypeEnum.BARS_CHART;
      this.endPointChart.WidgetSizeClass = WidgetSizeEnum.XS;
      this.endPointChart.WidgetID = 'ID_EndPointChartTest002';
    
      this.endPointChart.EndPointData = {
        Url: "YOUR_ENDPOINT_URL",
        Token: "TOKEN",
        RequestMethod: RequestMethodEnum.GET,
        Params: {
          { 
            PropertyLabel: "Company", 
            PropertyName: "FK_Company", 
            PropertyValue: null, 
            PropertyType: EndPointDataParamType.CVL, 
            CvlConfig: EndpointParamCvlConfig.CreateEndpointParamCVLConfig(null, [{ID:1, Label: "Azienda 1"}, {ID:2, Label: "Azienda 2"}], "ID","Label", false, true, true, null, false),
          },
          { PropertyLabel: "Data inizio", PropertyName: "StartDate", PropertyValue: data1, PropertyType: EndPointDataParamType.DATE },
          { PropertyLabel: "Data fine", PropertyName: "EndDate", PropertyValue: date2, PropertyType: EndPointDataParamType.DATE },
          { PropertyLabel: "Filtro testuale", PropertyName: "Text", PropertyValue: null, PropertyType: EndPointDataParamType.TEXT },
          { PropertyLabel: "Filtro numerico", PropertyName: "Number", PropertyValue: null, PropertyType: EndPointDataParamType.NUMBER },
          { PropertyLabel: "External", PropertyName: "ExternalInput", PropertyValue: null, PropertyType: EndPointDataParamType.EXTERNAL_TEMPLATE, ExternalTemplateConfig: this.externalTemplate, ParamClass: "col-12" }
        }
      }

      this.chartConfigs = [
        this.endPointChart
      ];
    }
    
    testExternalTemplate(widget: WidgetConfig) {
      //DO SOMETHING
      //IF YOU NEED TO UPDATE THE WIDGET YOU NEED TO INVOKE runEndPointCall METHOD FROM EqpDashboardComponent (use ViewChild to access it)
    }

  <ng-template #externalTemplate let-widget="widget" let-parameter="parameter">
      <button (click)="testExternalTemplate(widget)">Click me</button>
  </ng-template>

CASE 7: Define a WidgetConfig to display a component dynamically

    config: WidgetConfig = new WidgetConfig();
    chartConfigs: WidgetConfig[];
    
    //On your app.component.ts register the selector of the component you want to inject into the dashboard
    //Use this instruction
    ComponentMapperService.register("app-my-component", MyComponent);

    this.config.CustomComponentSelector = "app-my-component";
    this.config.WidgetSizeClass = WidgetSizeEnum.XS;
    this.config.WidgetTitle = 'Test Component 001';
    this.config.WidgetID = 'ID_TestComponent003';

    this.chartConfigs = [
      this.config
    ];

CASE 8: Define a WidgetConfig to display simple statistical data

    chartConfigs: WidgetConfig[];

    let statisticConfig: WidgetConfig = new WidgetConfig();
    statisticConfig.WidgetTitle = "Statistic Widget";
    statisticConfig.WidgetSizeClass = WidgetSizeEnum.XS;
    statisticConfig.WidgetID = 'StatisticWidget_Dashboard';
    statisticConfig.WidgetType = WidgetTypeEnum.STATISTIC_CHART;
    statisticConfig.StatisticWidget = [
      { Icon: "check_circle", Label: "Completati", Value: 70, MaxValue: 100 }
    ]

    this.chartConfigs.push(statisticConfig);

CASE 9: Define a WidgetConfig to display CUSTOM_CHART

    chartConfigs: WidgetConfig[];

    let customConfig: WidgetConfig = new WidgetConfig();
    customConfig.WidgetTitle = "Custom Widget";
    customConfig.WidgetSizeClass = WidgetSizeEnum.XS;
    customConfig.WidgetID = 'CustomWidget_Dashboard';
    customConfig.WidgetType = WidgetTypeEnum.CUSTOM_CHART;

    //According to the echarts library, it is possible to configure the chart option object with the information of the desired chart.
    //If an endpoint is used, the json ChartOption will be returned by the server.
    customConfig.ChartOptions = {
      xAxis: {
        type: 'category',
        data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
      },
      yAxis: {
          type: 'value'
      },
      series: [{
          data: [150, 230, 224, 218, 135, 147, 260],
          type: 'line'
      }]
    }

    this.chartConfigs.push(statisticConfig);

Credits

This library has been developed by EqProject SRL, for more info contact: info@eqproject.it