Advanced graphs in OutSystems using JavaScript 3rd-party libraries
While OutSystems offers built-in chart components (available at https://charts.outsystems.com/), developers sometimes seek more advanced graphing functionalities. In such cases, leveraging third-party JavaScript libraries, like AmCharts, can provide robust solutions without the need to reinvent the wheel.
In this article, we will explore how to integrate these JavaScript external libraries within OutSystems to build more complex graphs that meet diverse business needs.
We will use an exploding pie chart (also known as pie of a pie) as an example.
Step 1: Explore JavaScript libraries
Start by researching JavaScript libraries that offer the specific type of chart you need. For instance, you can find the exploding piechart example on the AmCharts website.
Once you’ve identified the desired chart type, understand the different sections in the JavaScript source code made available.
- Styles: Defines CSS styles for the chart container.
2. Resources: Imports necessary JavaScript libraries from AmCharts.
3. Chart code: JavaScript code that creates and configures the pie chart, including data setup, series configuration, and event handling.
4. HTML: HTML code that creates a div element with the id “chartdiv” where the chart will be rendered.
Finally, proceed to download the necessary JavaScript resources, which will be imported to OutSystems in the next step.
Step 2: Import Scripts
Let’s move on to the implementation using OutSystems.
Start by importing the JavaScript scripts to the module (right-click the Scripts folder under the Interface tab and select “Create Script” or “Import Script”).
Then, still in the Interface tab, go to the screen/block where you want to display the piechart, and select the 2 scripts in the Required Scripts property.
Step 3: Configure the User Interface
Review the code to identify the container element required for the chart. The code is expecting a container named chartdiv, with a width of 100% and a height of 500 pixels, so go ahead and create that.
#chartdiv {
width: 100%;
height: 500px;
}var container = am4core.create("chartdiv", am4core.Container);Step 4: Define the Data Structure
Understand the data format required by the JavaScript library. Look at the example JavaScript code to understand the structure of the data. Later, we will replace this dummy data with dynamic data passed as an input parameter.
chart.data = [{
"country": "Lithuania",
"litres": 500,
"subData": [{ "name": "A", "value": 200 }, { "name": "B", "value": 150 }, { "name": "C", "value": 100 }, { "name": "D", "value": 50 }]
}, {
"country": "Czech Republic",
"litres": 300,
"subData": [{ "name": "A", "value": 150 }, { "name": "B", "value": 100 }, { "name": "C", "value": 50 }]
}, {
"country": "Ireland",
"litres": 200,
"subData": [{ "name": "A", "value": 110 }, { "name": "B", "value": 60 }, { "name": "C", "value": 30 }]
}, {
"country": "Germany",
"litres": 150,
"subData": [{ "name": "A", "value": 80 }, { "name": "B", "value": 40 }, { "name": "C", "value": 30 }]
}, {
"country": "Australia",
"litres": 140,
"subData": [{ "name": "A", "value": 90 }, { "name": "B", "value": 40 }, { "name": "C", "value": 10 }]
}, {
"country": "Austria",
"litres": 120,
"subData": [{ "name": "A", "value": 60 }, { "name": "B", "value": 30 }, { "name": "C", "value": 30 }]
}];You can use the “Add structure from JSON” feature from OutSystems to automatically create the necessary structures.
You should end up with the structures shown below: Data and subData. The ‘Data’ structure will contain the primary categories (e.g., task statuses) and their total counts. The ‘subData’ structure will hold subcategories or subsegments related to each primary category (e.g., task ratings within each status).
For this specific usecase, I’ve added an extra color attribute to both structures, because I want to be able to specify the color of each pie in both piecharts.
Create a local variable in your screen/block (list of the Data structure), which will ultimately store the data needed for the chart.
Step 5: Get Data for the Chart
It’s time to populate our local variable with data that can be fetched using an aggregate or an Advanced SQL. This step can vary depending on your use case and business concept — in this article, we are focusing on task statuses within a project management system.
Let’s start by looking at the data model. There is an entity Task that stores the tasks, with 2 foreign keys linking to the static entities: Rating and Status.
The Status static entity contains 4 records: ‘Open,’ ‘In Progress,’ ‘Done,’ and ‘Cancelled.’ Similarly, the ‘Rating’ static entity has 4 records: ‘No Risk,’ ‘Risk,’ ‘Problem,’ and ‘Not Applicable’.
In the screen, there are 2 aggregates: GetTasksStatus (fetch set to At Start), with an On After Fetch event, and a GetRatingByStatus (fetch set to At Start).
The GetTasksStatus aggregate selects the color, label, and count of tasks grouped by status, while the GetRatingByStatus selects the color, label, and count of tasks grouped by rating, focusing on tasks that are set to the Done status.
The data from GetTasksStatus is used to display the overall distribution of tasks by status (illustrated in the left pie chart), while the data from GetRatingByStatus is used to display the distribution of ratings for the Done status (illustrated in the right pie chart).
In the OnAfterFetch event of the GetTasksStatus aggregate, we build the logic to populate our local variable.
Step 6: Generate Chart
With the container and data ready, it’s time to create the chart. For this, you can, for instance, create a client action GeneratePieChart which you can invoke after retrieving the data, within the ‘On After Fetch’ event of your data query.
In this client action, serialize the data to JSON format using JSON serialize, and then pass it to the JavaScript node responsible for creating the chart.
Create a JavaScript node and paste the JavaScript chart code obtained from the library’s documentation, making adjustments to fetch data from the input parameter instead of using dummy data.
You may need to do some more changes if you want the pie chart to be more customized to your needs, e.g. colors, legend, sizes, etc.
It’s time to publish the module and check the end-result:
Conclusion
Ready to see the exploding pie chart in action? Try out the Exploding Pie Chart Demo App now! To further simplify your development process, you can also utilize the Exploding Pie Chart component that I made available on the OutSystems Forge.
With these steps, you’re now equipped to enhance your OutSystems applications with dynamic and visually appealing charts using JavaScript libraries. It’s time to go and explore different chart types!
Thank you for reading! Your feedback is greatly appreciated, please let me know your thoughts by leaving your comments or contacting me via LinkedIn or OutSystems Profile.
Acknowledgments
I would like to thank Nuno Reis and Heriberto Filho for reviewing this article and encouraging me to share my knowledge with the community.
Disclaimers
The use of third-party JavaScript libraries, such as AmCharts, may be subject to their respective copyrights and licensing terms. It’s important to review and comply with the terms and conditions specified by the library’s provider.
