A very common scenario among advanced OutSystems developers is to get an off-the-shelf jQuery component seamlessly integrated into your OutSystems application. Here you will learn, by example, how to do so.

Badoca Safari Park is a wildlife sanctuary, situated in Portugal, that was in need of a website revamp. One of the functionalities that was missing was an album of photos of the animals that live in the Park (findthe base .oml HERE). After searching the web, inspired bythis example we’ve decided to integrate this beautiful widget, found in https://github.com/ryrych/rcarousel.

Here’s what you can do to include the RCarousel jQuery plugin (mentioned above) in our OutSystems application:

1. Download the plugin

Start by downloading the plugin code. Normally this comes as a zip file with several files.

Remember that if you want to reuse and publish your component you always need to check the license and copyright.

2. Add the plugin resources to you eSpace

Now that you have the plugin, you should have a bunch of files that have to be included in your OutSystems project (CSS, JavaScript, images, etc.).

One way of using these would be to import these files asresources and then reference them in JavaScript or CSS. However, this approach makes sharing your widget with other eSpaces harder, since the resources would not be visible to these consumers.

Instead it’s best to create a newWeb Block for each jQuery resource, and dump the full file content into the JavaScript of the Web Block. This way, the plugin can easily be made available (much like OutSystems’ own RichWidgets) to any consumer eSpaces that need to use it. Alternatively, you can add it to a theme’s “normal” page layout, causing it to be loaded in all pages that use that layout.

Now is it time to create a new Web Block, where you will insert all the configurations, style and jQuery code of the widget. This approach completely encapsulates the widget code in only one place, making it easier to reuse and change if necessary.

The first step is to create the necessary structure to get your widget working. In this case, by looking at the source code from the officialsample: we find that we need to nest images into a certain layout ofContainer widgets (i.e. DIVs).

If you want to influence the way this widget will work, you can use Web Block input parameters to control certain aspects of the jQuery plugin. For example, in our case, we might want to control the animation speed: we could do so via a non-mandatorySpeed parameter in the Web Block.

4. Style your widget

To get style working, you should copy the necessary CSS to the Stylesheet of the Web Block. Additionally, don’t forget to assign the necessaryStyle properties to the containers described above.

.

NOTE:You will notice that we copied and adjusted a few extra styles. The reason for this is that certain CSS selectors in the original plugin were using the element ID (e.g. #carousel), that in the OutSystems Platform are best replaced with CSS classes (e.g. .carousel). For more information on this, check out this thread on OutSystems Application's Web Design implementation guidelines.

5. Execute the needed jQuery

The last step is to make the actual jQuery code work as expected. Normally, plugins include a bunch of example code that comes in very handy - make sure to check the plugin website for these samples!

First you need to include our Widget JQuery code. Similar to the resources approach, you should copy all the source code to theJavaScript property of the Web Block.

The next step is bringing the component to life. To accomplish this you need to instantiate it, like you would normally do for any jQuery plugin. The details to do so are normally covered in the documentation and samples found in the plugin site.

In the OutSystems Platform specifically, to execute Javascript code during the rendering of a page, simply use an Expression widget (with theEscape Content property set to No) at the end of the Web Block and paste the call code there.

Here’s what the expression may look like if you want to adjust certain runtime values to accommodate image size, number of images shown, etc:

And that’s essentially it - you can now publish your eSpace and start using your new jQuery-powered widget!