Problem
You need to manipulate or animate client-side user interface elements on a Visualforce page using jQuery.
Solution
jQuery is an open source, actively supported, JavaScript library used to add client-side manipulation to HTML pages. You can use it to do the same on your Visualforce pages. jQuery is a cross-browser library designed to simplify the client-side scripting of HTML. Its syntax is designed to make it easier to navigate a document, select DOM elements, create animations, handle events, and develop Ajax applications.
jQuery also provides capabilities for developers to create plugins on top of the JavaScript library. Using these facilities, you are able to create abstractions for low-level interaction and animation, advanced effects and high-level, theme-able widgets.
As an example of using jQuery, we will create a dialog box for a list of records that displays a field value in a modal window.
Prerequisites
You will need to download the jQuery and jQuery UI libraries. jQuery is the core library which offers DOM manipulation methods and jQuery UI is a higher level library which constructs widgets for use on your page. From the jQuery UI site, you can download a zip tailored to the portions of the libraries you need.
For the purposes of the code in this recipe, we’ll assume you’ve named the static resource “jQuery”. To access jQuery in your Visualforce pages, you then need to include the libraries with something like this:
1 | <apex:includeScript value="{!URLFOR($Resource.jQuery, '/js/jquery-1.4.2.min.js')}" /> |
2 | <apex:includeScript value="{!URLFOR($Resource.jQuery, '/js/jquery-ui-1.8.6.custom.min.js')}" /> |
3 | <apex:stylesheet value="{!URLFOR($Resource.jQuery, '/css/ui-lightness/jquery-ui-1.8.6.custom.css')}" /> |
About Using jQuery
To use jQuery within Force.com, you’ll need to make use of the jQuery.noConflict() function to reassign jQuery’s global variable to something which won’t conflict with any other libraries which may already be in use (including standard, native libraries used within Visualforce). You’ll see an example of this in the code below.
With jQuery, you typically locate an element based on a CSS selector, attach it to an event or widget, and then perform a specific function. Take this example:
1 | $j = jQuery.noConflict(); |
2 | $j("#phone").dialog({ autoOpen: false, modal: true, position: 'center' }); |
This instructs jQuery to find an element with the id of “phone”, create a dialog widget from it and set the initial parameters.
It’s a best practice to make use of the onReady event of jQuery to initialize your JavaScript. This event will fire when DOM elements are ready, but before assets like images download. So for example, you’d write something like this:
1 | $j(document).ready(function() { } |
A Code Sample
Here’s a complete code sample. Assuming you’ve followed the pre-requisites, simply create a new Visualforce page with this source:
01 | <apex:page showheader="false" standardController="Account" recordsetVar="accounts" > |
03 | <apex:includeScript value="{!URLFOR($Resource.jQuery, '/js/jquery-1.4.2.min.js')}" /> |
04 | <apex:includeScript value="{!URLFOR($Resource.jQuery, '/js/jquery-ui-1.8.6.custom.min.js')}" /> |
05 | <apex:stylesheet value="{!URLFOR($Resource.jQuery, '/css/ui-lightness/jquery-ui-1.8.6.custom.css')}" /> |
07 | $j = jQuery.noConflict(); |
08 | $j(document).ready(function() { |
09 | $j("#phone").dialog({ autoOpen: false, modal: true, position: 'center' }); |
12 | function showDialog(name, phone){ |
13 | $j("#phoneNumber").html(phone); |
14 | $j("#phone").dialog("open"); |
15 | $j('#phone').dialog("option" , "title" , name); |
16 | $j('#phone').dialog('option', 'position', 'center'); |
21 | .accountLink { color: blue; cursor: pointer; cursor: hand; } |
27 | <apex:dataList value="{!accounts}" var="account" id="theList"> |
28 | <a href="" class="accountLink" onclick="return showDialog('{!account.name}','{!account.Phone}')"><apex:outputText value="{!account.name}"/></a> |
32 | <div style="float:left">Phone:</div><div id="phoneNumber"></div> |
Discussion
The HTML in the page creates a div with an id set to “phone”. The JavaScript in the onReady jQuery function associates this div with a jQuery dialog widget, and sets it up to be a hidden modal window.
The showDialog() function, when called with a name and phone number, updates the phone number displayed within the div, sets its title, and opens the dialog making it visible and recentered.
So now you have a hidden div that can display data, and a function that will take this div and display it as a model dialog after adding data to it. To tie it all together, we create a link around every account name that we display, that uses the onClick even to invoke the showDialog() function.
jQuery takes care of the rest. In fact, jQuery provides powerful DOM manipulation and widget creation in a minimal amount of code. In this instance, the dialog box is draggable, modal (meaning the main page is not usable while the box is open), and can be closed with the escape key with only one line of code.
Note we re-center the dialog box in the showDialog function in case Visualforce has updated the DOM during rendering, otherwise the box would have been centered by default as well.
In production, it would probably be best to have all the scripts and CSS in static resources - this example uses in-line code for easier cutting and pasting.
No comments:
Post a Comment