EChart Userview Menu Plugin

Introduction

The EChart Menu plugin is a user-friendly charting plugin for Joget DX 8, serving as an alternative to the default Chart Menu. By selecting any datalist in your app, you can display its records in various graph types.

The plugin allows reusing datasource configurations and datalist filters, enhancing flexibility. Additionally, multiple charts can be displayed on a single userview page via the Dashboard Menu.

You can download this plugin from the Joget Marketplace.

For more information on the JS library used, visit: https://echarts.apache.org.

The source code is available in the JogetOSS repository at https://github.com/jogetoss/echart-menu. JogetOSS is a community-led initiative for open-source projects related to the Joget platform, and contributions are welcome.

Get started

Where to get the plugin

You can download the EChart Menu plugin from the Joget Marketplace.

How to install

Start your Joget server and open the App Center.
Log in as an admin.
Go to Settings > Manage Plugins > Upload Plugin and upload the downloaded plugin.

Configure EChart menu properties

ID: Enter a unique ID for the menu element. Userview will use this ID in the URL for the menu if Custom ID property is empty.
Custom ID: Item link slug. Optional field.
Ensure that value defined here is unique to other userview menus in the app, since the first matching/conflicting ID will take precedence in page loading.
Label: Define the menu label. Mandatory field.
Chart Title: Chart Title to be displayed as part of the generated chart.
Chart Theme: Choose from a wide selection of chart color themes. You can also select Custom to define your theme.

Custom Theme JSON:

This option appears when Chart Theme is set to Custom.

Follow the steps below to generate custom theme.

Go to https://echarts.apache.org/en/theme-builder.html and customize your own theme.
When ready, click Export.

Paste the content of the file downloaded here.

{
    "version": 1,
    "themeName": "shine",
    "theme": {
        "seriesCnt": 4,
        "backgroundColor": "rgba(0,0,0,0)",
        "titleColor": "#333333",
        "subtitleColor": "#aaaaaa",
        "textColorShow": false,
        "textColor": "#333",
        "markTextColor": "#eeeeee",
        "color": [
            "#c12e34",
            "#e6b600",
            "#0098d9",
            "#2b821d",
            "#005eaa",
            "#339ca8",
            "#cda819",
            "#32a487"
        ],
        "borderColor": "#ccc",
        "borderWidth": 0,
        "visualMapColor": [
            "#1790cf",
            "#a2d4e6"
        ],
        "legendTextColor": "#333333",
        "kColor": "#c12e34",
        "kColor0": "#2b821d",
        "kBorderColor": "#c12e34",
        "kBorderColor0": "#2b821d",
        "kBorderWidth": 1,
        "lineWidth": 2,
        "symbolSize": 4,
        "symbol": "emptyCircle",
        "symbolBorderWidth": 1,
        "lineSmooth": false,
        "graphLineWidth": 1,
        "graphLineColor": "#aaaaaa",
        "mapLabelColor": "#c12e34",
        "mapLabelColorE": "#c12e34",
        "mapBorderColor": "#eee",
        "mapBorderColorE": "#ddd",
        "mapBorderWidth": 0.5,
        "mapBorderWidthE": 1,
        "mapAreaColor": "#ddd",
        "mapAreaColorE": "#e6b600",
        "axes": [
            {
                "type": "all",
                "name": "通用坐标轴",
                "axisLineShow": true,
                "axisLineColor": "#333",
                "axisTickShow": true,
                "axisTickColor": "#333",
                "axisLabelShow": true,
                "axisLabelColor": "#333",
                "splitLineShow": true,
                "splitLineColor": [
                    "#ccc"
                ],
                "splitAreaShow": false,
                "splitAreaColor": [
                    "rgba(250,250,250,0.3)",
                    "rgba(200,200,200,0.3)"
                ]
            },
            {
                "type": "category",
                "name": "类目坐标轴",
                "axisLineShow": true,
                "axisLineColor": "#333",
                "axisTickShow": true,
                "axisTickColor": "#333",
                "axisLabelShow": true,
                "axisLabelColor": "#333",
                "splitLineShow": false,
                "splitLineColor": [
                    "#ccc"
                ],
                "splitAreaShow": false,
                "splitAreaColor": [
                    "rgba(250,250,250,0.3)",
                    "rgba(200,200,200,0.3)"
                ]
            },
            {
                "type": "value",
                "name": "数值坐标轴",
                "axisLineShow": true,
                "axisLineColor": "#333",
                "axisTickShow": true,
                "axisTickColor": "#333",
                "axisLabelShow": true,
                "axisLabelColor": "#333",
                "splitLineShow": true,
                "splitLineColor": [
                    "#ccc"
                ],
                "splitAreaShow": false,
                "splitAreaColor": [
                    "rgba(250,250,250,0.3)",
                    "rgba(200,200,200,0.3)"
                ]
            },
            {
                "type": "log",
                "name": "对数坐标轴",
                "axisLineShow": true,
                "axisLineColor": "#333",
                "axisTickShow": true,
                "axisTickColor": "#333",
                "axisLabelShow": true,
                "axisLabelColor": "#333",
                "splitLineShow": true,
                "splitLineColor": [
                    "#ccc"
                ],
                "splitAreaShow": false,
                "splitAreaColor": [
                    "rgba(250,250,250,0.3)",
                    "rgba(200,200,200,0.3)"
                ]
            },
            {
                "type": "time",
                "name": "时间坐标轴",
                "axisLineShow": true,
                "axisLineColor": "#333",
                "axisTickShow": true,
                "axisTickColor": "#333",
                "axisLabelShow": true,
                "axisLabelColor": "#333",
                "splitLineShow": true,
                "splitLineColor": [
                    "#ccc"
                ],
                "splitAreaShow": false,
                "splitAreaColor": [
                    "rgba(250,250,250,0.3)",
                    "rgba(200,200,200,0.3)"
                ]
            }
        ],
        "axisSeperateSetting": true,
        "toolboxColor": "#06467c",
        "toolboxEmphasisColor": "#4187c2",
        "tooltipAxisColor": "#cccccc",
        "tooltipAxisWidth": 1,
        "timelineLineColor": "#005eaa",
        "timelineLineWidth": 1,
        "timelineItemColor": "#005eaa",
        "timelineItemColorE": "#005eaa",
        "timelineCheckColor": "#005eaa",
        "timelineCheckBorderColor": "#316bc2",
        "timelineItemBorderWidth": 1,
        "timelineControlColor": "#005eaa",
        "timelineControlBorderColor": "#005eaa",
        "timelineControlBorderWidth": 0.5,
        "timelineLabelColor": "#005eaa",
        "datazoomBackgroundColor": "rgba(47,69,84,0)",
        "datazoomDataColor": "rgba(47,69,84,0.3)",
        "datazoomFillColor": "rgba(167,183,204,0.4)",
        "datazoomHandleColor": "#a7b7cc",
        "datazoomHandleWidth": "100",
        "datazoomLabelColor": "#333333"
    }
}

Chart Library Version:
Choose echart library version.
- 4.9.0
- 5.1.2
Chart Type:
Available chart types:
- Area Chart
- Bar Chart
- Line Chart
- Donut Chart
- Pie Chart
- Custom
  
  With the Custom option, you can define multiple charts and chart types on a single page to represent different sets or interpretations from the same datasource.
  Additional configurations are required to define the chart type(s) for each number value(s). See Data Mappings below.
Chart Dataset:
- Current Page Dataset - Generates chart based on the data on the current datalist page being displayed.
- Entire Dataset - Generates chart based on the entire dataset of the datalist.
Show Tabular Data:
Show tabular data at the configured position.
- No
- Top
- Bottom
Show Export Links:
This option is visible when "Show Tabular Data" is visible. Show or hide the export links located below the tabular data.
- No
- Yes
Show Filters:
Show or hide the filters on the top right of the chart. The filters are defined in the datalist chosen.
- No
- Yes

Data mappings

Area Chart, Bar Chart, Line Chart, Donut Chart, Custom

List: Target Datalist to read records from.
X-axis Value: Datalist column to represent the x-axis or categories of the chart.
Number Values: Define the column representing the category values.
- Number Value: Datalist column to represent the category values of the chart.
- Show Value Label in Chart?: Check this option to display the category values on the chart.
- Series Customization:
  See chart configuration documentation here:
  - Area Chart & Line Chart - https://echarts.apache.org/en/option.html#series-line
  - Bar Chart - https://echarts.apache.org/en/option.html#series-bar
  - Donut Chart - https://echarts.apache.org/en/option.html#series-pie
  Here expects JSON value(s) to modify the features or look-and-feel of the series.
  
  For example, if a bar chart type is selected to display the categories as a stacked bar chart, you can key in as such:
```
{
    stack : 'one',
    label: {
        show: true,
        precision: 1,
        valueAnimation: true
    }
}
```
  If the Chart Type selected is Custom, a chart type and its necessary properties must be defined.
  To see all available chart types, see the documentation here: https://echarts.apache.org/en/option.html#series.
  
  Examples as below:
```
{"type" : "line"}
```
```
{"type" : "pie",
 "radius" : "40%",
 "center": ["50%", "25%"],
 "label": {
   "formatter": "{a} {b}: {@2012} ({d}%)"
 }
}
```
  You can also download the sample app for reference.

Pie chart

List: Target Datalist to read records from.
X-axis Value: Datalist column to represent the categories of the pie chart.
Number Value: Datalist column to represent the category values of the pie chart.
Series Customization: See chart configuration documentation at https://echarts.apache.org/en/option.html#series-pie .
Here expects JSON value(s) to modify the features or look-and-feel of the series.
Examples: Resize pie chart size
```
{
    "radius": "50%"
}
```

Chart options

Area Chart, Line Chart

X-axis Label: Label for the X-axis.
X-Axis Display as: Choose how to display the X-axis value:
- Category
- Number
- Date
Y-axis Label: Label for the Y-axis.
No Boundary Gap: If checked, there will be no gaps on the sides of the chart within the plot area.
Smooth Line: If checked, the chart lines will be curved for a smooth appearance. If unchecked, chart lines will be straight. This option is ignored if the Series Customization property is set.
Show Legend: If checked, the chart legend will be shown.
Show Tool Tip: If checked, mousing over data points will display additional information.
Width: Maximum width of the chart.
Height: Minimum height of the chart.

Bar chart

X-axis Label: Label for the X-axis.
X-Axis Display as: Choose how to display the X-axis value:
- Category
- Number
- Date
Y-axis Label: Label for the Y-axis.
No Boundary Gap: If checked, there will be no gaps on the sides of the chart within the plot area.
Show Legend: If checked, the chart legend will be shown.
Display as Horizontal Chart?: If checked, the X-axis and Y-axis will be swapped to represent data horizontally.
Show Tool Tip: If checked, mousing over data points will display additional information.
Width: Maximum width of the chart.
Height: Minimum height of the chart.

Donut chart

Show Legend: If checked, the chart legend will be shown.
Show Tool Tip: If checked, mousing over data points will display additional information.
Width: Maximum width of the chart.
Height: Minimum height of the chart.

Line chart

Show Legend: If checked, the chart legend will be shown.
Show Value Label in Chart?: If checked, category values will be shown. This option is ignored if the Series Customization property is set.
Show Tool Tip: If checked, mousing over data points will display additional information.
Width: Maximum width of the chart.
Height: Minimum height of the chart.

Custom

X-axis Label: Label for the X-axis.
X-Axis Display as: Choose how to display the X-axis value:
- Category
- Number
- Date
No Boundary Gap: If checked, there will be no gaps on the sides of the chart within the plot area.
Show Legend: If checked, the chart legend will be shown.
Display as Horizontal Chart?: If checked, the X-axis and Y-axis will be swapped to represent data horizontally.
Show Tool Tip: If checked, mousing over data points will display additional information.
Width: Maximum width of the chart.
Height: Minimum height of the chart.

Advanced

Additional Customization: For all customizable properties, see the documentation https://echarts.apache.org/en/option.html.
Here expects JSON value(s) to customize the overall chart functions or look-and-feel.

Example:
```
grid : {
    top: "55%"
},
tooltip : {
    "trigger": "item",
    "formatter": "{a} {b}: {c} ({d}%)"
}
```
If the label is too long, use the following code
```
grid: { containLabel: true }
```

UI key data filter

UI Key Name:
When defined, the additional conditions will be appended using the value defined here as the parameter and the UI key value as the value.

Example:
SQL: SELECT category, count(category) FROM table1
Userview Key Name: type
Userview Key Value: val
Resultant SQL: SELECT category, count(category) FROM table1 WHERE type = 'val'
When the UI key value is defined, you may define #userviewKey# in your SQL query to replace it with the UI key value.

Example:
SQL: SELECT category, count(category) FROM table1 WHERE type = '#userviewKey#'
Userview Key Value: val
Resultant SQL: SELECT category, count(category) FROM table1 WHERE type = 'val'

UI

Custom Header: Custom Header in HTML.
Custom Footer: Custom Footer in HTML.

Performance & offline

Configure caching and offline settings for optimal performance.

Cache settings

Set caching scope (None, Application, User) and duration in seconds.

Fields to configure:

Scope:
Caching options are:
- None: No caching.
- Application: Cache content by application where all users will see the same content.
- User: Cache by username.
Duration (s): Duration in seconds to cache content defaults to 20 seconds if applicable.

For more information, see Performance Improvement with UI Caching.

PWA offline settings

PWA Offline support is dependent on the theme used.

Enable cache for offline support: Enable caching for offline support, which is usually set for mobile browsers.

For more information, see Progressive Web Application.

Download plugin

Get the latest version of the EChart Menu plugin from the Joget Marketplace.

Download sample app

Download the demo app for EChart Userview Menu Plugin:

APP_kb_dx8_echartDemo.jwa

Created by Julieth Last modified by Aadrian on Nov 19, 2024