This documentation is for WSO2 Stream Processor 4.4.0 (the latest version of WSO2 SP. View documentation for the Streaming Integrator, the successor of WSO2 SP.

All docs This doc
                                                                                                                                                                                                                                                                                                                                       
||
Skip to end of metadata
Go to start of metadata

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:
  • 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:

DirectoryContents
<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

publicContains the Index.html file that is used in the Stackblitz editor to render the live preview.
srcContains all the source code files required to preview the widget in the Dashboard.
src/themeContains 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/widgetContains 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:

  1. 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.
  2. 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.

  3. 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.
  4. 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.
  5. 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

PurposeTo 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:

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 linkwso2-linechart-siddhiprovider


WSO2-MultiBarChart

PurposeTo 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 sourceCreate 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:

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 linkwso2-multibarchart


WSO2-worldmap

PurposeTo view how your data can be distributed in a world map.
Information sourceCreate 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:

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 linkwso2-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 sourceCreate 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:

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 linkwso2-subscriber-piechart

WSO2-subscriber/publisher-barchart

PurposeTo 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 sourceCreate 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:

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 linkwso2-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 sourceCreate 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:

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

Preview linkwso2-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.

  1. Access the Stream Processor Studio. For detailed instructions, see Stream Processor Studio Overview.
  2. Create a Siddhi application with an aggregation definition.
  3. 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).

  4. 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>);

  5. 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>);

  6. 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
  7. Simulate events to the Siddhi application you created. For instructions to simulate events, see Simulating Events.
  8. Change the granularity from seconds up to years and generate the six JSON files.
  9. Replace the six files in the <Widget_root>/mocking/dataset directory with the six JSON files you generated.
  10. 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 linkwso2-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.

  • No labels