The Possibilities of Front-End Development in OutSystems with JSON and JavaScript Libraries

As front-end developers, our main goal is to always achieve pixel-perfect applications by turning UI designs into reality. I believe most front-end developers wouldn't disagree when I say that our job, our mission is to make sure the applications we work on look and feel consistent, coherent, accessible and appealing. OutSystems is an incredible tool that, as a platform, allows us to deliver and implement a visual theme that replicates the intended vision created by the designers, and construct components and screens of multiple magnitudes to help developers bring the data and relevant information to the end-user. The way that data is accessed or the level of complexity required for a component can, however, vary tremendously and bring a new set of obstacles.

And that is why today I want to explore how JSON and JavaScript Libraries can help us deal with those possible hurdles and enhance our applications and components in OutSystems with additional functionality and integrations.

First, let’s talk about JSON and what exactly it is. JSON stands for JavaScript Object Notation and is a data format that stores information in an organized and easily readable manner. “Simplicity” is the keyword here - it’s easy to write and translate between the data structures used by most languages, having a text format that uses object and array structures for the representation of data. JSON’s popularity has risen as the need for websites and apps to more efficiently transfer data from one system to another has also grown. The speed of communication and less data to download are qualities of this format that make it more favorable compared to others such as XML.

You might be asking: “Why or in what circumstances would I, a front-end developer, then use JSON in OutSystems?”. If you have been working with OutSystems for a while, you've probably interacted with or manipulated JSON data without realizing - for example, in the older versions of OutSystems Charts, there used to be an Advanced Format input parameter of the chart in question that allowed us to format chart elements using Highcharts JSON (since then, OutSystems has updated Charts so that it’s easier UI-wise for a developer to make those customizations). But a main scenario is related to web service integration - when integrating with external systems or consuming web services that communicate using JSON, you'll need to parse the JSON responses (converting JSON strings into JavaScript objects) to extract the required data. JSON is commonly associated with REST services, especially for APIs on the web (REST API is a way of accessing web services in a flexible way without having any processing), so when integrating with third-party APIs or services that expect data in JSON format, you can use JSON to structure and exchange the required data.

You might be asking: “Why or in what circumstances would I, a front-end developer, then use JSON in OutSystems?”. If you have been working with OutSystems for a while, you've probably interacted with or manipulated JSON data without realizing - for example, in the older versions of OutSystems Charts, there used to be an Advanced Format input parameter of the chart in question that allowed us to format chart elements using Highcharts JSON (since then, OutSystems has updated Charts so that it’s easier UI-wise for a developer to make those customizations). But a main scenario is related to web service integration - when integrating with external systems or consuming web services that communicate using JSON, you'll need to parse the JSON responses (converting JSON strings into JavaScript objects) to extract the required data. JSON is commonly associated with REST services, especially for APIs on the web (REST API is a way of accessing web services in a flexible way without having any processing), so when integrating with third-party APIs or services that expect data in JSON format, you can use JSON to structure and exchange the required data.

OutSystems provides tools and components to handle JSON data, allowing you to serialize/deserialize data and interact with APIs. Plus, JSON can be used as an intermediate format for transforming and exchanging data within an OutSystems application. For instance, if you need to convert data from one structure to another or aggregate data from multiple sources, you can serialize (convert) the data to JSON, perform the required transformations or operations, and then deserialize it back into OutSystems structures.

With the “why” out of the way, how can one work with JSON data in OutSystems?

• Create a Structure: In the OutSystems Service Studio environment, go to the "Data" tab, right-click on the Structures folder and select "Add Structure." Define the structure fields that correspond to the JSON data you'll be working with. Give each field a name and specify its data type.

• Parse JSON: Create a logic flow and drag and drop the “JSON Deserialize” action from the Toolbox onto it. But before you can effectively utilize the 'JSON Deserialize' action from OutSystems, it's essential to prepare your JSON data for conversion into an OutSystems structure. To do this, you can use a JavaScript node to first apply JSON.stringify to your data. This step is crucial as it converts your data into a JSON string, which is the format expected by the 'JSON Deserialize' action and the way OutSystems handles JSON data. Configure the action by selecting the JSON string you generated with JSON.stringify and choose the target structure you created in step 1. The 'JSON Deserialize' action will then work its magic, converting the JSON data back into an OutSystems structure, allowing you to work with the data fields individually. This sequence ensures a seamless transition between JavaScript and OutSystems, making your JSON data manipulation smooth and efficient.

• Access JSON data: After parsing the JSON, you can access the individual data fields by using the dot notation. For example, if your JSON has a field named "FirstName," you can access it using the structure variable followed by a dot and the field name: MyStructure.Data.FirstName.

• Generate JSON: Drag and drop the “JSON Serialize” action from the Toolbox onto your logic flow. Configure the action by selecting the structure or variables containing the data you want to convert to JSON. The action will serialize the data into a JSON string (which as mentioned earlier is the way OutSystems handles JSON data). If you need to use the resulting JSON data in your logic as an actual JSON object, you'll also need to add a JavaScript node and use JSON.parse() to parse the JSON string into a JSON object. This parsed JSON object can then be used for various purposes, such as sending it as a parameter in a web service call or storing it in a database. This flexibility allows you to seamlessly work with JSON data within your OutSystems applications, whether you require the data in JSON string or JSON object form.

• Handling JSON arrays: If your JSON contains arrays, you can work with them in OutSystems as well. Arrays can be represented as a List or a Record List data type in OutSystems. To access the elements of a JSON array, you can use a For Each loop, iterating over the list or record list variable.

As we know, OutSystems allows us to develop applications rapidly, providing a wide range of built-in functionality and pre-built components. And while one of our tasks as OutSystems front-end developer is to create components that bring new capabilities and interaction to our applications, there are instances where using external libraries can be truly beneficial in integrating complex functionality to our custom widgets in a timely fashion. Simply put, leveraging existing, well-tested JavaScript libraries speeds up the development process in those instances where it’s asked of us to reinvent the wheel in short deadlines when the whole vehicle has already been invented, while noting that it’s important to consider factors like library compatibility, maintenance, security, and licensing when incorporating them into OutSystems applications.

External JavaScript libraries may also provide integrations with popular APIs (JSON!), services, or systems that are not directly supported by OutSystems. These libraries can facilitate seamless data exchange between OutSystems applications and external systems, enabling us to incorporate a wide range of functionalities and leverage existing infrastructure.

So how do we implement external JavaScript libraries, you ask?

• Find the Library: Identify the JavaScript library you want to use and make sure it meets your requirements. Popular libraries include jQuery, React, Angular, Chart.js, and many others. You can search for libraries on popular repositories like npm (Node Package Manager) or GitHub.

• Download or Reference the Library: Download the library file (usually a .js file) from the library's official website or repository.

• Add the Library to Your OutSystems Application: Once you have the library file, you need to add it to your OutSystems application. In the OutSystems Service Studio environment, open the module where you want to use the library. Open the ‘Scripts’ folder and add the library file.

• For the JavaScript library to be recognized, you have to reference the script in the screens or components where you want to take advantage of it - when you select that specific screen or block, there is a section in its properties called “Required Script” where you can then add one or multiple script files.

• Use the Library in Your Code: After adding the library to your OutSystems application, you can start using its functionality in your JavaScript code. In the OutSystems Service Studio, open the screen or module where you want to utilize the library. Create or edit a JavaScript action or function within a logic flow. You can write your custom JavaScript code and make use of the library's functions, objects, or APIs as needed.

Finally, how can we merge these two concepts and manipulate and display JSON data using the capabilities of JavaScript libraries (or just JavaScript in general for that matter)?

• In the client action where you have your JavaScript logic (in the JavaScript node of the flow), pass the JSON data that comes in string form as an input parameter and apply the JSON.parse() method to your variable that you created to store the JSON data. As the name suggests, the JSON parsing process converts the JSON object in text format to a JavaScript object that you can use as you see fit in your JS logic.

• But if you need to pass JSON data to server actions or consumed by client-side JavaScript code (like a JS library, for example), you then can convert that JavaScript object into a JSON string by using the JSON.stringify method. This static method has three parameters (the value which is required and in the screenshot below it’s the “jsonData” variable, a replacer and space parameters that are both optional).

These have been the basic steps on how to work with JSON and implement external JavaScript libraries in our applications. JSON provides a versatile and widely supported data format that enables seamless integration, data exchange, and manipulation within OutSystems applications. At Mediaweb, we always strive to stay on top of innovation and focus on straightforward solutions and optimized processes, that’s why these tools are part of our work processes. In addition to impacting workflow optimization, external libraries can also help developers stay up to date with the latest technologies, trends, and best practices - by integrating libraries that incorporate modern frameworks, tools, or techniques, we can take advantage of the advancements in the industry and ensure that our applications are built using the latest and most efficient approaches.

In summary, the one thing I keep (re)discovering each day is that OutSystems creates a space for a front-end developer to deliver on the promise of the design by exploring solutions that may seem out of our reach. It gives us the necessary tools to make any concept come true while remaining open to adding whatever functionality or technology we desire to make our final product the very best it can be. So what are the possibilities of front-end development in OutSystems? Limitless! Cover photo by Growtika in Unsplash