Information

Integrating with jQuery

[Warning: A tiny little bit of Javascript ahead]

Want to know what jQuery is? You've come to the wrong place. Here I'm going to show you how to integrate jQuery with Intraweb...

So what's jQuery? To put it simply, it's a very powerful Javascript library that allow you to do a lot with little code, based on the notion of querying DOM objects.

Ok, big deal. What can it do for me?

Well to start with, it offers a whole range of plugins that make use of the library to provide outstanding functionality inside the browser. It also provides a lot of base functionality like easy Ajax support (though not as simple as Intraweb, you still need to know Javascript...actually jQuery).

Wait a minute. Isn't this competing with Intraweb? Why are you integrating with it? At Atozed we believe in harmony in a eco-system were all parties involved form a beautiful relationship both at a personal and professional level...yeah right!

Seriously, why are we trying to integrate with jQuery? Simple: it adds value to Intraweb and offers solutions to our customers. We're actually aiming at integrating with other Javascript libraries and jQuery is the start of it.

So how does it work? As usual, here comes the...

[Disclaimer: this is work in progress. Things might change from now to release. In fact, it might be radically different]

Enough already, how does it work? Warning: jQuery ahead!

First of all we've added a couple of new things to Intraweb. The server controller and all forms now have a property called ContentFiles of type TStringList (actually TIWStringList to be precise but that's irrelevant). ContentFiles allows you to add javascript and css files you want rendered on your form. Let's say you want to include a file named... jquery.js, you can add it to the ContentFiles and it will be automatically rendered in your form. In the name of "convention over configuration", it's assumed that the the file exists under the Files url. If you want to add a stylesheet, just put it's name, same thing will happen. This actually allows you to add more than one Stylesheet per form as well as simplify the whole process. Oh, if you want it rendered on all forms, just add it to the ContentFiles property of the ServerController instead of the individual forms.

Secondly, we've added a new non-visual control which is called TIWJQueryWidget (and in the future there might be a TIWDojoWidget). This component has two important properties: ContentFiles and OnReady. I won't explain what the first one does since I just did, except to add that in this case, it's content is copied to the ContentFiles property of the form so that the form knows what to render. The OnReady is the soul of it all. jQuery basically allows to define behaviors for components by initializing some parameters once the document (HTML) has been loaded. This basically means that whatever you enter in OnReady will be automatically placed in the document loaded event. Normally this will be jQuery. Sounds all too complicated? It isn't. Let's see how it works.

Suppose you want a fabulous looking Calendar for your edit box. First step is to navigate to the jQuery web site and see what there is. At this url I find a plugin called datePicker. Like the way it looks and want to use it.

So I see that it requires a couple of files, namely a ui.datepicker.js and a ui.datepicker.css file. I click to download it and save it to my Files folder under my Intraweb application root, where I also have jquery.js (downloaded previously from the same site). I want to add a date picker to my edit controls. Once I have the files in place, I drop a TIWJQueryWidget component onto my form, double-click on the ContentFiles property and enter the names of the files it uses. 

Now all that's left to do is let the edit boxes know I want to use a date picker (the plugin that we selected actually tells us what we need to do). This is where the OnReady comes in.  We write the following code:

$('#EDITSTART').datepicker();
$('#EDITEND').datepicker();

Next we run the application. When we enter the edit box, we get:

Viola! Remember the warning about JS? It was quite little wasn't it?

What next?

Well I've just shown you one simple example, but there's so much more you can do with jQuery without much effort. The obvious question is, are we going to provide wrappers around jQuery? Not initially. There are many reasons. First of all, there might be licensing issues with some plugins. Secondly there's issues with keeping in sync with jQuery and other releases. It also requires a lot of effort to create wrappers that will give access to all the possibilities that each of the plugins (or even the base library) offer, and seeing how simple it is to work with it as is, it might not be the best approach. However, the jury is still out on that one, but the fact that we've made a widget component is a good sign.......

I'll try and post some more entries on how to work with jQuery in the next couple of weeks. Hopefully you'll get this functionality in the next release. Oh, and there's also another new component on the palette, I'll try and post about that one very soon.