Integrating a JavaScript plugin to your OutSystems app

Stable Version 1.0.0 (OutSystems 11)
Published on 12 Feb by 
Created on 12 Feb
Details
This is the component that was used on the "Integrating a JavaScript plugin to your OutSystems application" How-To video available at https://www.youtube.com/watch?v=MaYCbcPSzms
Read More

Introduction

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

 

WebBlock overview

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.

 

 

UsageExample

 

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.

Reviews (0)
Category
Components, Samples & How-tos
Support Options
This component is not supported by OutSystems. You may use the discussion forums to leave suggestions or obtain best-effort support from the community, including from Jay Santos who created this component.
Dependencies
Integrating a JavaScript plugin to your OutSystems app has no dependencies.
Requirements
Platform
11.0.0.200
Database
All
Stack
.NET
Component Consumers
No consumers yet.
Weekly Downloads 
Related Components
Silk UI Web
OutSystems R&D
A fully responsive and beautiful UI framework that works within the OutSystems Platform. Build amazing looking applications, in a fraction of the time, which work perfectly across devices. Learn how to start using Silk UI and see the examples at silkui.outsystems.com . Obtain assistance on using Silk UI in our forums .
28474
Multiple File Upload
Multi Uploaders
Allow you to upload multiple files in one upload form or using drag and drop functionality.
2764
OutSystems UI Mobile
OutSystems R&D
Create amazing native mobile applications using this fully integrated UI framework for OutSystems, with dozens of UI patterns ready to use.
9989
More from Jay Santos
How2UserRegistration
Stacey Levine
Sample application to show how to extend the user table and allow self registration of users into your application
688
IconateWebBlockApp
Jay Santos
0