Tuesday, August 5, 2008

Another Way to Enrich Your SharePoint Forms - JQuery

I'm still enjoying that honeymoon period with a new tool in my SharePoint developer "bag of tricks" - JQuery. Such a powerful library!

As an example of its usefulness, in a recent project I needed to modify the behaviour of search scope checkboxes on an advanced search page in SharePoint (enforcing that the 'All Sites' checkbox is ticked if the user clears all other checkboxes).

Here's the steps I took using JavaScript plus JQuery:
1. Encapsulate the minified JQuery library in a SahrePoint feature in order to deploy across the farm.
2. Add a script tag referencing the JQuery JS file in the 'PlaceHolderTitleAreaClass' content placeholder of the search page.
3. Add a Content Editor Web Part to the search page, and open the source view for that web part.
4. Add the following JavaScript function to the content editor source (to enable custom JavaScript to be called on page load):

    1 function addLoadEvent(func){

    2     var oldonload = window.onload;

    3     if (typeof window.onload != 'function') {

    4         window.onload = func;

    5     } else {

    6         window.onload = function () {

    7             if (oldonload) {

    8                 oldonload();

    9             }

   10             func();

   11         }

   12     }

   13 }

5. Call a click handler processing function on page load with the following:

6. Add a function to assign onclick handlers to the targetted checkboxes. This is where the power of JQuery shines through - notice the short expression in line 5 that retrieves references to only the checkboxes I am seeking (these checkboxes are contained in table cells attributed with the class 'ms-advsrchText')

    1 //Add an onclick event handler for each of the checkboxes in the search form

    2 //(the checkboxes are identified by the 'ms-advsrchText' class applied to their containing table cells)

    3 function AddOnClickHandlers() {

    4   //Get the checkboxes in the form

    5   var chks = $('td.ms-advsrchText').find(':checkbox').get();

    6   for(var i=0;i<chks.length;i++)  {

    7     chks[i].onclick = SetFormState;

    8   }

    9 }

7. Write the onclick event handler - this needs to find the check box labelled "All Sites" and check its status. I have not included all the code, just a few lines showing more use of JQuery. Line 12 builds a selection expression to get the next sibling for each check box; the next sibling is a label whose text contains the scope name (e.g. "All Sites").

    1 function SetFormState() {

    2   //... OTHER CODE ...


    4   //Get the scope checkboxes in the search form

    5   var chks = $('td.ms-advsrchText').find(':checkbox').get();


    7   //Enumerate through the check boxes

    8   for(var i=0;i<chks.length;i++) {


   10     //Get the next sibling to the checkbox, which is a label element that contains the descriptive text.

   11     //This text is assumed to always be 'All Sites' for the main search scope

   12     var lbl = $('#' + chks[i].id + ' ~ label').get(0);


   14     //Save the reference to the All Sites checkbox

   15     if (lbl.innerText == 'All Sites') {

So, the actual code to get at the required elements on the page is very brief, and the range of JQuery selectors makes getting to the elements easy.

One tip - notice the use of the Get() method call at the end of the JQuery expressions. This returns DOM elements that can then be manipulated with normal DOM scripting.

No comments: