jQuery and Ajax: the ready Event Handler to the rescue.

[dan]

We wish to add a slider to a web page. Ebase Xi does not currently provide a control which provides this functionality, but there is a jQuery UI widget which can do the job for us (http://jqueryui.com/slider/).

In order to create a slider control jQuery UI requires us to add a <div> to the page, and then call a jQuery UI function .slider() on it. jQuery UI will then do the rest: it transforms this <div> into a slider widget for you.

Let us briefly look at the 5 steps needed to add this slider in Ebase Xi:
1. Add jQuery and jQueryUI JavaScript files as external Client Scripts.
2. Add the matching jQueryUI css file as a Style Sheet.
3. Add a Panel Control to the page with an empty layout (this is our <div>).
4. Open up the Panel Control’s Html Element Properties dialog and add slider as its id locator.
5. Add the code to transform the Panel Control into a slider (.slider()).

For more information about doing the first 4 steps, please refer to the Ebase Xi Documentation (http://dev-docs.verj.io/ufs/doc/Creatin ... lients.htm is a good starting point).

Let’s have a look at what step 5 involves. According JQuery UI We need to add the code:

Code: Select all

$(document).ready(function() { $("#slider").slider(); })

This code says that when the page is ready look for the element with an id of slider (‘#slider’) and perform the function ‘slider’ on it, thus transforming the Panel Control into a slider widget.

In older versions of Ebase Xi the only mechanism available to you was to add this code (surrounded by <script> tags) to HTML++. Indeed, adding it here works: when the page is loaded by a browser, the code is executed and the Panel Control is turns into a slider widget.

In more modern versions of Ebase Xi it is also possible to create a Client Script to do this and add it to the Template, Form, or Page in question. Now the when page is loaded by a browser, this Client Script is also loaded (automatically) and the code is executed, transforming the Panel Control into a slider widget.

Herein lies a problem however: it only happens when the page is loaded. Ebase Xi has a ‘Use Ajax’ Form property that only refreshes controls on the page as and when they change, allowing for a much more fluid user experience. For example if you have a button on the page which shows the slider when clicked the AJAX mechanism will simply add the Panel Control to the page. If the Ajax mechanism is not used then the entire page is submitted back to the server and the whole page is reloaded (thus running the code again and transforming the Panel Control into a slider).

Notice that when the Ajax mechanism is used the whole page is not reloaded and also that the code we added to the HTML++ and the Client Script only runs when the page loads. Why is this a problem? Well, the code looks for the Panel Control and runs the slider function on it but if the Panel Control is hidden in the Ebase Xi designer and shown when a button is pressed, the Panel Control is not in the page when the code executes. This means when the Panel Control is shown it just looks like a panel.

Also, if the Panel Control is refreshed (rather than shown) by the Ajax mechanism then it is replaced in the page. This means that the previous control which had the code run on it to transform itself into a slider is removed and the new Panel Control added in its place. The visible effect of this is that the slider transforms back into a Panel Control (a plain old <div>).

Clearly this isn’t desired behaviour. The solution is to make sure that the code to transform the Panel Control is executed whenever the Panel Control is shown or refreshed and this is exactly what Ebase Xi’s ready Event Handler is there to do. This Event Handler can be found, with all the other jQuery Event Handlers, in the jQuery tab of a control’s Html Element Properties dialog.

The ready Event Handler is slightly different from these other Event Handlers in that it is not triggered directly by a user action in the same way as a click Event Handler is triggered when a control is clicked for example. Instead the ready Event Handler is triggered automatically every time the page loads (in exactly the same way that the jQuery ready function we used in our code above is) and every time the Ajax mechanism refreshes one or more controls – including when it shows and hides controls.

The code we need to add to the Panel Controls Html Elements Properties ready Event Handler is simply:

Code: Select all

$(“#slider”).slider();

Ebase Xi now makes sure this is executed whenever a page loads or controls are refreshed so the Panel Control continues to look like a slider.

It’s worth comparing the code in this ready Event Handler to the other Event Handlers, an example of which is click. These other Event Handlers are triggered by events generated by the control they are configured on. All Event Handlers run in the context of the thing that generated the event they are handling, so for click and the other Event Handlers run in the context of the control. This means that to perform some action (like execute some code) on itself it doesn’t have to find itself first:

Code: Select all

$(this).slider();

This would be all the code the click Event Handler would need to transform the Panel Control it is configured on into a slider widget when clicked.

Looking at the code in the ready Event Handler we see that we had to find the Panel Control first ($(“#slider”)). This is because the ready Event Handler is triggered by an event originating from the page and not the control it was configured on and so runs in the page's context. This is why when we write code in the ready Event Handler we must first find the control we are interested in as we did by looking up the id locator we gave to the Panel Control.

Here is an example Form showing this example.