Thursday, March 12, 2009

Using the jQuery JavaScript Library in SharePoint

By now you have probably heard about jQuery, the “write less, do more” JavaScript Library. If not I would recommend a trip to their site, http://jquery.com/. jQuery makes finding and manipulating elements on a page much easier and much less painful than writing plain JavaScript.

You may be thinking “why is he talking about JavaScript on a SharePoint blog?” Well, jQuery can be used to easily enhance and modify the SharePoint user interface without having to use Visual Studio or even SharePoint Designer for that matter. This is extremely beneficial when customizing sites in a hosted environment or when you do not have remote desktop access to the SharePoint server for some other reason.

In this blog I will walk you through several ways to load the jQuery Library onto your SharePoint site or server and set up a simple hello world script. Then over several more posts I will walk through examples that show just how powerful jQuery and SharePoint can be when used together. Some examples are: hiding page elements, automatically collapsing and expanding the Quick Launch menu, enhancing the picture gallery, and the best of all… editing web part properties and content with just one mouse click.

There are several ways to get the jQuery Library onto your SharePoint page or site. I’m not going to make any claim to which method is the best; you should use the method that works best for you in your environment.

Using a document library and a Content Editor web part

This method is great for quickly adding the jQuery library to a page when you do not have SharePoint Designer.

1. Upload the jQuery Library to a document library

2. Add a Content Editor web part to your page

3. Add the following script reference to the web part using the Source Editor, making sure to change the src URL to the path of the uploaded jQuery library

<SCRIPT language=javascript src="http://<site>/<page>/<document library> /jquery-1.3.1.min.js" type=text/javascript></SCRIPT>

Spoiler: In an upcoming blog, I will show you how to use jQuery to add edit icons to all web parts on a page, making the source editor much easier to get to.

clip_image002

Using SharePoint Designer on a web page

This method is good when you want to store the library in a more permanent location that is not visible on the site or want to place the script directly in the page and not in a web part.

1. Open the site in SharePoint Designer

2. Copy the jQuery Library to the site in the same location as the default.aspx file

3. Add the jQuery reference in the page header by adding

<SCRIPT language=javascript src="jquery-1.3.1.min.js" type=text/javascript></SCRIPT>

under the following line:

<asp:Content ContentPlaceHolderId="PlaceHolderAdditionalPageHead" runat="server">

4. Script can then be added to any Content Editor web part on the page or directly into the page in designer

I like to use this method to add the jQuery Library under the root web of the site. You can then reference the that jQuery file from any page by simply adding the following script in a Content Editor web part.

<SCRIPT language=javascript src="http://<site>/jquery-1.3.1.min.js" type=text/javascript></SCRIPT>

Using SharePoint Designer on the master page

This method is very similar to the one above, except that by adding the jQuery reference to the master page you will be able to use jQuery on any page in that site. Just remember that each subsite will have its own master page.

1. Open the site in SharePoint Designer

2. Navigate to the _catalogs/masterpage directory and copy the jQuery Library into the site

3. Open the default.master file

4. Add the following script to the <HEAD> section of the page

<SCRIPT language=javascript src="jquery-1.3.1.min.js" type=text/javascript></SCRIPT>

5. You will then be able to use jQuery in the master page or in any site that uses the master page

Installing a feature that adds the JQuery reference on all sites

This is a good method to add jQuery to every page in a site collection if you have the ability to install a feature on the site. Jan Tielens has created just such a feature which is available at http://smarttools.codeplex.com/ . I will not plagiarize from his blog but the basic idea is to create a web control which contains the script reference. This control is included with a feature which adds the jQuery files to the layouts directory and the jQuery reference to all SharePoint pages for which the feature is scoped.

Once you have completed one of these four methods it is time to actually use jQuery to do something on our SharePoint page. The simplest way is to create a new Content Editor Web Part on a page to which the jQuery reference was added. Or add it to the existing Content Editor Web Part if you used the first method.

Start by adding the following script using the Content Editor Source Editor:

<SCRIPT type=text/javascript>
$(document).ready(function(){
alert(“Hello”);
});
</SCRIPT>

The ready() function instructs jQuery to wait until the document is loaded and ready to be manipulated.

When you refresh your page you should now see the “Hello” alert. If so, congratulations you have successfully added jQuery to your SharePoint page. If not, try viewing the source html of the page and verifying that the jQuery reference is present and points to the correct location. Also, if you copied and pasted the code above, it is also a good idea to make sure the quotes copied correctly into the Source Editor.

Replacing the alert(“Hello”); with $("A").css("color","green"); . Will turn all links on the page to green, this is a very simple example but should give you a glimpse of just how powerful jQuery can be.

clip_image004

Before

clip_image006

After

One other thing to remember when playing with JavaScript inside of a Content Editor web part is that adding ?Contents=1 to the page URL will display the Web Part Page Maintenance page. This is helpful because it is fairly easy to break a page by entering bad JavaScript into the Content Editor Web Part, this page allows you to easily delete the web part so your page will display properly again.

In my next post I will show you additional ways to enhance the SharePoint user experience using jQuery. Until then, take a look at the examples at http://docs.jquery.com/Main_Page and think of ways to make your SharePoint experience even better.

1 comment:

Jeroen said...

If you want to insert code in every web page, including JQuery, then you can also use our free SharePoint Infuser.

See http://www.muhimbi.com/blog/2009/07/massage-sharepoint-into-submission.html