Using Sample Widgets to Create Custom Widgets

WSO2 provides sample widgets for your reference so that you can create custom widgets with similar configurations. These widgets are hosted as projects in Stackblitz. To create your own custom widgets based on these samples, you can fork them and edit them as required. Once you have created your own widgets, you can download them as Zip files and deploy them in the WSO2 SP Dashboard Portal.

Before you begin:

Install Node.js and npm by clicking one of the following links:
- On Windows
  - X64: Download Node 8.8.1-x64
  - X86: Download Node.8.8.1-x86
- On Linux and other OS: Download for Linux and others
Understand how to work with Stackblitz.
Click here for a brief overview of Stackblitz:
1. Go to the WSO2 Stackblitz account. All the available sample widgets are listed.
2. Click on a sample widget. The related project is displayed as shown below.
  
  As marked above, the project page is divided into three sections.
  - Directory view: The section on the left displays the directory structure.
  - File view: When you click a file in the directory view, the contents of that file are displayed in the file view in the middle.
  - Preview: The section on the right provides a preview of the widget.
3. To customize this widget in your own account, click Fork. Once you make the required changes, click Save.

The following sections cover the available sample widgets and how you can use them as templates to create your own custom widgets.

Accessing, downloading, and installing sample widgets

The directory structure of a widget is as follows:

▼mocking

▼components

►assets

►dataSet

►public

►resources

▼src

►theme

The following table describes the contents of the directories in the above structure:

Directory	Contents
`<root>`	Contains global configuration and Javascript files, the index, and the package.json file.
`mocking`	Contains the publisher and subscriber simulation parts and React components that give the Dashboard Frame experience with external customizations(Theme/EventStack). It includes: The overview components(Frame/PublisherMock/SubscriberMock) used in the live preview. The data set for preview. `Widget.js` and `ChannelManager.js` for illustrating the `@wso2-dasboards/widget`.
`resources`	Contains the `widgetConf.json` file that holds all the meta information of the widget. This includes the following: Widget name Widget ID Thumbnail URL Configs Pubsub Types: `publisher` and `subscriber` ProviderConfig Configs Type: `siddhidataprovider` Config Siddhi Application or Aggregation Definition Query Data Query Publisher Interval
`public`	Contains the `Index.html` file that is used in the Stackblitz editor to render the live preview.
`src`	Contains all the source code files required to preview the widget in the Dashboard.
`src/theme`	Contains the material UI Theme customizations that are required for the user to interact with components and to change their view (e.g., dark and light).
`src/widget`	Contains the React code used to implement the widget.

All the code in files below the src/widget directory is included in the production build.

To use the samples, follow the steps below:

Open the required sample in the WSO2 account in Stackblitz and click Fork to make a copy in your fork. Observe how the widget operates and its functionality.
Make the required changes in the MyWidget.jsx file. For details on each individual widget, see Available sample widgets.

It is recommended for you to edit only the MyWidget.jsx file because it is the only file required by the WSO2 SP Dashboard portal. The other files are available for the purpose of simulating the WSO2 SP Dashboard Portal functionality in Stackblitz so that you can understand how the widget is expected to function in the Dashboard Portal. However, you can edit the theme.js file in <root>/src/theme directory if you want to change the theme (i.e., the light background or the dark background) and other properties related to the look and feel such as the colors, height, width, etc.
Optionally, add configurations to the <WIDGET_HOME>/resources/widgetConf.json file and make modifications to the other configuration files as described in the above table.
Once you finish editing the widget in the Stackblitz editor, download the file as a zip file by clicking on the icon marked in the image below. Then extract the content.
To install, build, and deploy the widget, open your terminal and navigate to the root directory of the widget. Then issue the following commands.
- To install all the dependencies for the widget, issue npm i.
- To build the widget, issue npm run build.
- To deploy the widget, issue npm run deploy.

Available sample widgets

The following is a list of sample widgets hosted in Stackblitz undee the wso2stackblitz account. You can observe the way in which they function via the mocking tools in Stackblitz. If you need to create similar widgets, you can fork the project for the required widget and edit the <WIDGET_HOME>/resources/widgetConf.json file to customize it based on your requirement.

WSO2-LinChart-SiddhiDataProvider

Purpose	To preview a sample line chart and observe its functionality via a data set.
Information source	If you include this sample in WSO2 Stream Processor without making any changes, it uses the Siddhi Data Provider to load the data by executing a Siddhi application and the relevant Siddhi query. For more information about writing Siddhi applications and Siddhi queries, see the following sections: Developing Streaming Applications Tutorials
Customizing the widget	To learn about different chart types and how to do the configurations for customizations, see the React-VizGrammar documentation. The `<Widget_root>/src/widget/MyWidget.jsx` file contains the source code relevant to the widget, and you can customize it as required, taking the following into account. In the `componentDidMount` method, the data set is requested from the Channel Manager(i.e., `@wso2-dashboard/widget`). Use `formatDataToVizgrammar()` to format the data set to fit into the Vizgrammar chart. Changes to the chart are included in the `render()` results.
Preview link	wso2-linechart-siddhiprovider

WSO2-MultiBarChart

Purpose	To view a multiple bar chart that enables you to change the dimensions in real-time, and view multiple Y axis dimensions against a single X axis dynamically.
Information source	Create the Siddhi application and the query that forms the required columns. These columns are used to populate the chart. For more information about writing Siddhi applications and Siddhi queries, see the following sections: Developing Streaming Applications Tutorials
Customizing the widget	Check boxes are automatically loaded based on the data set provided. To change the chart type and the color configurations, see the React-VizGrammar documentation. The `<Widget_root>/src/widget/MyWidget.jsx` file contains the source code relevant to the widget, and you can customize it as required, taking the following into account. In the `componentDidMount()`, the data set is requested from the Channel Manager(`@wso2-dashboard/widget`). You can change the view of the check box panel by editing the code in `renderCheckBoxPannel()`. Use `formatDataToVizgrammar()` to format the data set to fit into the Vizgrammar chart. Chart configurations are declared as constants on top of the `MyWidget.jsx` file.
Preview link	wso2-multibarchart

WSO2-worldmap

Purpose	To view how your data can be distributed in a world map.
Information source	Create the Siddhi application and the query that builds the required data set. For more information about writing Siddhi applications and Siddhi queries, see the following sections: Developing Streaming Applications Tutorials
Customizing the widget	The `<Widget_root>/src/widget/MyWidget.jsx` file contains the source code relevant to the widget, and you can customize it as required. To change the map type and the color variations, see the React-VizGrammar documentation.
Preview link	wso2-worldmap

WSO2-subscriber-piechart

Purpose	Shows how to manipulate a chart or table according to a particular value. You can use the publisher simulation to publish a date event or a JSON object, and you can view a pie chart sorted by the date events. You can check out the published events using the event stack. This widget is implemented to filter the data according to the published date events as well as the raw JSON object. To view this information in the Dashboard Portal, use the Date Range Picker that is already implemented for the widget ( in the DATE RANGE PICKER tab), or enter the region as a key value pair in the RAW VALUE PUBLISHER tab. For example, if you enter `region` as the key and `Caribbean` as the value as shown below, the widget filters the values eventhough the date range is not selected. If the date range as well as the region is provided, the widget filters the data based on both the inputs provided.
Information source	Create the Siddhi application and the query that builds the required data set. For more information about writing Siddhi applications and Siddhi queries, see the following sections: Developing Streaming Applications Tutorials
Customizing the widget	To learn about different chart types and how to do the configurations for customizations, see the React-VizGrammar documentation. The `<Widget_root>/src/widget/MyWidget.jsx` file contains the source code relevant to the widget, and you can customize it as required, taking the following into account. To create a subscriber widget, enter `subscriber` as the pubsub type in the `<Widget_root>/resources/widgetConf.json` file. The data set is requested from the Channel Manager (`@wso2-dashboard/widget`) in the `componentDidMount` method. Use `formatDataToVizgrammar()` to format the data set to fit into the Vizgrammar chart. Chart configurations are declared as a constant at the top of the `MyWidget.jsx` file. The data column in the data set must be mentioned under `CHART_CONFIGS`. A subscriber widget needs to be connected to a publisher widget. For more information about connecting the subscriber widget to a publisher widget, see Inter-widget Communication via the Pubsub Model. For more information about how to simulate the connected widgets, see Testing sample widgets via mocking tools.
Preview link	wso2-subscriber-piechart

WSO2-subscriber/publisher-barchart

Purpose	To observe a scenario where subscribing for data and publishing data takes place at the same time. This bar chart is implemented to select a date object on the publisher widget so that the data can also be filtered by that date object. If you click on a bar, data specific to the country represented by the bar is displayed.
Information source	Create the Siddhi application and the query that builds the required data set. For more information about writing Siddhi applications and Siddhi queries, see the following sections: Developing Streaming Applications Tutorials
Customizing the widget	To learn about different chart types and how to do the configurations for customizations, see the React-VizGrammar documentation. The `<Widget_root>/src/widget/MyWidget.jsx` file contains the source code relevant to the widget, and you can customize it as required, taking the following into account. To create a subscriber and publisher widget, add `[“subscriber”, ”publisher”]` as the pubsub type. The data set is requested from the Channel Manager (`@wso2-dashboard/widget`) in the `componentDidMount` method. Use `formatDataToVizgrammar()` to format the data set to fit into the Vizgrammar chart. Chart configurations are specified as a constant at the top of the `MyWidget.jsx` file. The data column in the data set must be mentioned under `CHART_CONFIGS`. A subscriber widget must be connected to a publisher widget. For more information about connecting the subscriber widget to a publisher widget, see Inter-widget Communication via the Pubsub Model. For more information about how to simulate the connected widgets, see the Testing sample widgets via mocking tools.
Preview link	wso2-subscriber-publisher-barchart

WSO2-ValuePublisher

Purpose	The WSO2 dashboard supports inter-widget communication via a pub-sub model. If you need to publish a name-value pair to manipulate another widget, you can use this sample. The published value can be seen in the stack bar (as shown below) as well as in the mocking subscriber tool.
Information source	Create the Siddhi application and the query that builds the required data set. For more information about writing Siddhi applications and Siddhi queries, see the following sections: Developing Streaming Applications Tutorials
Customizing the widget	The `<Widget_root>/src/widget/MyWidget.jsx` file contains the source code relevant to the widget, and you can customize it as required, taking the following into account To define the widget as a publisher widget, enter `publisher` as the pubsub type in the `<Widget_root>/resources/widgetConf.json` file. For more information about inter-widget communication, see Inter-widget Communication via the Pubsub Model.
Preview link	wso2-valuepublisher

WSO2-Aggregated chart

Purpose	To preview a chart where the data is in the form of an aggregation, and where data can be filtered based on a selected time range. Charts based on the aggregation concept typically use the date range picker to view data for different date ranges and time granularities. For more information about the aggregation concept, see Incremental Analysis.
Information source	This widget includes sample data sets to allow you to observe how an aggregation chart functions. The following is a guide to prepare a dataset from your aggregation source. Access the Stream Processor Studio. For detailed instructions, see Stream Processor Studio Overview. Create a Siddhi application with an aggregation definition. Write an aggregation query with the required date ranges and granularity in order to retrieve your data set. This query should be as follows: From <AGGREGATION_DEFINITION> Within <FROM_DATE> , <TO_DATE> Per <Granularity> Select <COLUMN 1>,<COLUMN 2>,......... For instructions on writing queries to calculate and store aggregations (as required for step 2) as well as to retrieve those aggregations (as required for step 3), see Incremental Analysis. For detailed guidance on the same topic, see the tutorial Streaming Data Summarization (Incremental Aggregation). To get the data set you created via the aggregation query in a deployable form, generate it as an output by adding an output stream definition to the Siddhi application as shown below. `define stream OutputStream(<COLUMN_1 DATA_TYPE>, <COLUMN_2 DATA_TYPE>);` In order to deploy the data set, it needs to be derived as a JSON file. Therefore, connect a sink of the `file` type to the output stream you defined. The sink configuration should specify the path to the location where the file needs to be saved via the `file.uri` parameter. It should also include a mapping annotation with `json` as mapping type. `@sink(type='file', file.uri="<FOLDER_PATH>/seconds.json",append="false", @map(type="json"))` `define stream OutputStream(<COLUMN_1 DATA_TYPE>, <COLUMN_2 DATA_TYPE>);` To calculate aggregations, the aggregation definition needs to be joined with an input stream where the input information is received. The output of this query needs to be inserted into the output stream you defined. The template of this query is as follows. `From TriggerStream join <AGGREGATION_DEFINITION>` `Within <FROM_DATE> , <TO_DATE>` `Per <Granularity>` `Select <COLUMN 1>,<COLUMN 2>,.........` `Insert into outputStream` The completed Siddhi application looks as follows: { AGGREGATION_DEFINITION } @sink(type='file', file.uri="<FOLDER_PATH>/<Granularity>.json",append="false", @map(type="json")) define stream outputStream(<COLUMN_1 DATA_TYPE>, <COLUMN_2 DATA_TYPE>); define stream TriggerStream (trigger string); From TriggerStream join <AGGREGATION_DEFINITION> Within <FROM_DATE> , <TO_DATE> Per <Granularity> Select <COLUMN 1>,<COLUMN 2>,......... Insert into outputStream Simulate events to the Siddhi application you created. For instructions to simulate events, see Simulating Events. Change the granularity from seconds up to years and generate the six JSON files. Replace the six files in the `<Widget_root>/mocking/dataset` directory with the six JSON files you generated. Publish date events using the publisher simulation to see the widget populated with information from your data set.
Customizing the widget	To change the chart type and the color configurations, see data setGrammar documentation. The `<Widget_root>/src/widget/MyWidget.jsx` file contains the source code relevant to the widget, and you can customize it as required, taking the following into account: An aggregation-based widget needs the input from the Date Range Picker to display data for specified data ranges and time granularities. Therefore, it needs to be a subscriber widget connected to the Date Range Picker widget. Enter `subscriber` as the pubsub type in the `<Widget_root>/resources/widgetConf.json` file of the aggregation-based widget. If you need to replace the data set with your own, prepare six JSON files named `seconds`, `minutes`, `hours`, `days`, `months`, and `years` from the aggregation source (based on your requirement). The imports are specified in the `<widget_root>/mocking/ChannelManager.js` file.
Preview link	wso2-aggregated-chart

Testing sample widgets via mocking tools

When the functionality of a widget involves interacting with another widget, you also need the other widget to observe the functionality. This requirement exists mainly when the pubsub model is used when a user input made via one widget triggers a response in another widget. The sample widgets of this type are provided with a mocking tool. The mocking tool simulates the behaviour of the other widget with which the widget being tested is expected to interact.

Subscriber mocking tool
This tool is implemented to demonstrate the functionality of sample publisher widgets.

When the widget is a publisher, it needs a subscriber widget to subscribe to the information it publishes. For sample publisher widgets in Stackblitz, WSO2 provides this subscriber mocking tool to mock the expected action of the connected subscriber widget.
To activate this tool for a sample publisher widget, enter publisher as a key in the <WIDGET_HOME>/resources/widgetConf.json file as shown in the following extract:

"configs": {
"pubsub": {
"types": ["publisher"]
},

For example, the following bar chart is a publisher widget where if you click on a bar, the subscriber mocking tool displays information related to that bar in the same manner that a subscriber widget connected to this chart is expected to display that information.
Publisher mocking tool
This tool is implemented to demonstrate the functionality of sample subscriber widgets.

When the widget is a subscriber, it needs a publisher widget to publish the information it subscribes for. For sample subscriber widgets in Stackblitz, WSO2 provides this publisher mocking tool to mock the expected action of the connected publisher widget.
To activate this tool for a publisher widget, enter subscriber as a key in the <WIDGET_HOME>/resources/widgetConf.json file as shown in the following extract:

"configs": {
"pubsub": {
"types": ["subscriber"]
},

This tool publishes information in two methods:
- Date picker
  In this method, you can publish date range events with granularity. If you need to view the actual publishing object you can switch to the JSON view. In the JSON view, you can manipulate your changes, but only date events are backward compatible.
- Raw JSON
  In this tab, you can validate your own JSON object. You can manipulate various factors relating to the widget behaviour such as date filtering and changes in color via these JSON objects.