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 (find the base .oml HERE). After searching the web, inspired by this 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
3. Create the Web Block that will contain your widget
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 official sample: we find that we need to nest images into a certain layout of Container 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-mandatory Speed 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 necessary Style 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!
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.
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!