This document describes how to integrate an external JavaScript plugin to your OutSystems application. You can also find this content as a video in https://www.youtube.com/watch?v=MaYCbcPSzms
We’l ldivide the document into two sections: Web Block Overview (describing the structure and variables of the Web Block) and Usage Example (using the WebBlock in a proper application).
The goal is to create a reusable framework based around the Iconate JavaScript plugin, for that we have created a Web Block which is available at the Forge at https://www.outsystems.com/forge/component-overview/5309/integrating-a-javascript-plugin-to-your-outsystems-app.
The Web Block itself is very straightforward, it is composed of an If, in the True block we have an image and in the False block we have two Expressions (Fig. 1).
Fig. 1: The Iconate WebBlock structure
The If statement verifies if the block is being shown in Preview Mode. If so it will show the Iconate Logo so the developer can check where the icon will be shown on the page. If we are not in Preview Mode (i.e.: We are actually seeing the page being rendered in a browser) then the False block is activated, where we have two Expressions, we’llgo over the expressions in a while, but first let’s check the five InputParameters (Fig. 2).
Fig. 2: Input parameters of the Iconate WebBlock
- animationName: The name of the animation to be applied to the icons, you can find the list of available animations at Iconate’s GitHub repository - https://github.com/bitshadow/iconate
- iconclass: The icon element’s class name. In our example we’ll use FontAwesome icons - https://fontawesome.com/ - These are the icons used in Iconate’s demo on their website, they’re also the icons used by the Icon Widget on OutSystems. FontAwesome class names start with a “fa”prefix, then the name of the icon and finally any additional settings as suffix.
- fromIcon: The original icon shown on the screen.
- toIcon: The icon you’ll transition to the first time.
- uniqueId: ID of the Web Block. This will be used by the block to uniquely identify variables and methods, so you can have several instances of the Block on the same screen.
Now let’s go over the expressions. The first expression contains the code that will actually activate the switching animation of the icons (Fig. 3), let’s go over the code.
Fig. 3: Code of the first expression
First of all we have two variables named “iconelement_” and “options_”, to both variables we’re adding the uniqueId parameter as suffix, in order to uniquely identify the variables for each Web Block instance.
Next, we have a function that is called on the ready event. This event is triggered once the DOM have finished rendering, so the function will be called once the screen have finished loading.On this function we are setting the content for the two variables “iconelement_”and “options_”, you can see that the document.getElementById method is looking fora uniqueId + “_icon” ID. This is set on the second expression. On the “options_”variable we add the icon and animation information, this will be used by Iconate’s iconate method. Finally on this function we add an event listener for clicks to the icon, this listener will trigger the “callIconate_”function, which finally calls the Iconate plugin iconate function, which is the function that actually animates the icons.
Below the ready function, we have the“callIconate_” function, which is also identified by the uniqueId suffix. Inthis function we call the iconate function, which actually animates the icons.This method receives as parameters:
- The icon to be animated
- The options variable
- A callback function, which in our case simply switches the “to” and “from” parameters from the options variable. This way we can keep clicking on the icon and switch back and forth.
Now let’s check the second expression(Fig. 4).
Fig. 4: Second expression
This expression is simply creating the HTML icon element, defining the id as the “uniqueId” Web Block parameter plus the “_icon” suffix to differentiate the icon from the Web Block itself. And the class is set as the “iconClass” parameter. We’ll talk more about it when we check the Web Block’s usage.
Now let’s see how to use the WebBlock itself. The use is pretty straightforward: You simply drag the block into your page (inside OutSystems Service Studio you’ll see the Iconate logo on your page, since you’re in Preview Mode), and set the Input Parameters, let’s see an example on how to set said parameters (Fig. 5).
Fig. 5: Iconate WebBlock with parameters configured
- animation:You can find the list of available animations on Iconate’s GitHub repository - https://github.com/bitshadow/iconate
- iconclass: As mentioned, we are using FontAwesome’s icons, their names start with the “fa” prefix to which you can add a style settings (you can find more info here - https://fontawesome.com/how-to-use/on-the-web/referencing-icons/basic-use), after that we have the name of the icon (you can find all the icons and its names here - https://fontawesome.com/icons?d=gallery),finally we’ve added the “fa-3x” suffix in order to render the icon three times its original size.
- fromIconand toIcon:The icons that will be used to switch back and forth when clocked.
- uniqueId: The Web Blocks Id parameter.