How to integrate a Jquery Plugin in the OutSystems Platform

How to integrate a Jquery Plugin in the OutSystems Platform

  
Badoca Safari Park is a Zoo like place, situated here in Portugal. It’s a great place to spend some quality time with your family. If you don’t know it, I definitely recommend it!

Recently, researching on jQuery components, I was asked to think of a revamp of their site. One of the functionalities that I decided to implement was an album of photos of the animals that live in the Park (You can find my .oml in attach). I’ve searched the web and found a beautiful widget in http://ryrych.github.com/rcarousel/. I was also inspired by this example here.  

Since I had to integrate the plugin in my OutSystems project, I’ve researched the Community for some information on this but there was nothing that would take me in a deep dive on the matter. After talking with a lot of colleagues I managed to gather a bunch of good practices, and come up with a solution that I’m actually very proud of! Thanks to you all :)

So, let’s go on a step-by-step safari on how to include a jQuery plugin on your OutSystems application. We’ll use the RCarousel plugin mentioned above as the example.

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 downloaded the plugin, you should have a bunch of files that you have to include in your OutSystems project (CSS, JavaScript, images, etc.).
 
          One way of using these would be to import these files as resources and then reference them in JavaScript or style sheet. However, with this approach, sharing your widget with another eSpace becomes harder since the resources would not be visible to the consumer
 
           For my implementation, I’ve created a new web block for each jQuery resource, and dumped the full file content in the JavaScript of the web block. This way jQuery will be available like to our widget and we can reuse these web blocks on the pages were we need to use the widget. Alternatively, we can add them in the beginning of the layout and in that way they will be loaded in all pages that use that layout.
 

 
 
 
3.       Create the web block were your widget will live
           Now is it time to create a new web block, where we 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 all the needed structure to get your widget working. In this case, I create a few containers comparing the source code from the sample:

 
 
            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 in which case we might create a non-mandatory Speed parameter in the web block.
 
4.       Style you widget
           To get all the style working you should copy it to the style sheet of the web block. Additionally, don’t forget to assign the styles to the containers needed.
 
.

          In my case I had to copy extra styles used in the sample and edit them for some layout corrections. The reason was that I found some ID association in the CSS (#carousel) that I needed to replace with CSS classes (.carousel). If you want more info about this, a recent post highlights some guidelines on how to properly use CSS in the Agile Platform
 
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 you check the plugin website for that. 
          First we need to include our Widget JQuery code. Like in the resources we will copy all the source code to JavaScript of our web block. The next step is bringing our component to life. To accomplish this we just need to instantiate it like you would normally do a jQuery plugin. This is normally pretty well covered in the plugin site.
          In the Agile Platform,   you just need to create an Expression (with Escape content set to No) on the end of web block and paste there the call code.
          I have used the code from the example with some changes to accommodate image size, number of images showed, etc.

 

           And that’s it – you can now publish your eSpace and start using your new jQuery powered widget.
 
           I hope you enjoyed this guide and if you have comments don’t hesitate to post them here. I’m eager to learn how you include some jQuery goodness in your OutSystems Applications. 
Very clearly explained !

I would create a webblock for every picture or object you want to put in the carousel.
That way you're even more felxible ....

And be careful with implementing different versions of jQuery in all kinds of webblocks, these might interfere with each other.

jQueryUI is already incorporated (yes, it's an old version) in the platform ... I hope that outsystems will update the jQuery core and jQuery UI to the latest and greatest sometime .... HINT HINT to development :-)
It seems they picked up on your hint Joop, finally :)
Nice Post
Hello,

How can download the plugin Jquery ?

Thanks,

Hi Ricardo,

Jquery is no plugin, it is part of the platform.
Thank you , ferry helpful

I can't use the oml.


"Foreign Module Error

Your OutSystems subscription only allows publishing modules developed in your environment, or downloaded from the OutSystems Forge. To share this module with the community, upload it at http://www.outsystems.com/goto/forge".