I was asked to put together a simple article on how to add jQuery to your XPages so here we go….

if you want to know “WHY” you should use jQuery go here Lotusphere 2012 speedgeeking – jQuery and Domino a RAD combination and here The basics of jQuery and definitely here  SInging jQuery’s praises in a Domino Environment

Problem

How can I add jQuery to my XPages?

There are multiple ways in which we can achieve this – you will have to make your mind up which is best for your own application/environment. These are not in any particular order, it really depends!

The Basics

Somewhere, somehow, you will need to add the various JavaScript/Image/CSS files to your XPage. In a similar way to dojo, jQuery has a core module with all the basic selectors. You can get the most up to date files from here http://docs.jquery.com/Downloading_jQuery. There are links which you can reference directly in your application or you can download them and use them in your environment. Any extra look and feel css/image files will need to be added as well if you are going to use them.

Where do the files live?

You can store the files in a number of places which may or may not be determined by your environment:

• Back on the CDN server (no local storage)
• On the server in the domino/html directory

  

• In a notes database (not a good choice if you are going to use jQueryUI due to the number of files involved). Download the latest jQuery file and rename it from jQuery 1.whenever.js to jQuery.js. Add the version number to the comments so that in the future when you want to upgrade jQuery you do not have to change all your code, but you at least know what version is loaded. (I don’t recommend this method…..)

• In an OSGI plugin

  

How to reference the files?

There are multiple ways (like everything Domino/XPages) to achieve the desired result. What works best is part personal preference, part skill and understanding level and part sheer experimentation.

1) Use a theme !

Include the files into your application using a theme.  Create a theme in your database and under the application properties/XPages tab select to use your theme.
In your theme use the following code to reference the jQuery code.

If you are referencing the CDN

<resource>
 <content-type>application/x-javascript</content-type>
 <href>http://code.jquery.com/jquery-1.7.1.js</href>
 </resource>

or

If you are referencing the files on the server

<resource>
 <content-type>application/x-javascript</content-type>
 <href>/.ibmxspres/domino/jQuery/jquery-1.7.1.js</href>
 </resource>

<!--
NOTE /.ibmxspres/domino/ refers to your server c:/lotus/domino/data/domino/html directory
you will see your oneuiv2 folder there as well - make a jQuery folder here and put your file in it
-->

2) Use a Custom Control to compute resource (jQuery.js file)

Via a custom control the jQuery js files can be added to your XPage as a computed resource in the beforePageLoad server side event. This assumes that the jQuery.js is attached to the database as a file.

<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
<xp:this.beforePageLoad>
<![CDATA[
#{javascript:var currLocation=context.getUrl();
        var webDBPath=@LeftBack(currLocation,"/");
        sessionScope.jQuery=webDBPath+"/jQuery.js"}]]>
</xp:this.beforePageLoad>
<xp:this.resources>
        <xp:script src="#{javascript:sessionScope.jQuery}" clientSide="true">
        </xp:script>
</xp:this.resources>
</xp:view>

3) Use an OSGI plugin <– My personal favorite

Declan Lynch posted a fantastic OSGI plug-in with all the jQuery and jQueryUI files contained within, on openntf. The plugin much be installed on the client and on the server. The installation is pretty much the same as the extension library (See here for instructions) because they too are an OSGI plugin.

Once installed you can just drag and drop from your palette to your Custom Control/XPage.

Why is the best? IMHO it is the easiest to use through the client, it is always there and not database specific. The files are also zipped into a jar file and stored on the server so you don’t have to worry about them. For a one off, just when I need to add it to a page cos I though of something I can do in jQuery – this can’t be beat.

That said – If you have a corporate intranet where every site is the same and every site has jQuery on it – then I will concede that doing it in a theme is probably a better idea.

Like I said at the start of this article – it really depends on what best solution works for you!!

This is what it looks like when you add all the references to the same page (don’t try this at home) but as you can see the files can be referenced from all over the place (literally)

PS (just noticed in review and left here to demonstrate hazard)
You might notice that Domino totally hosed the content-type for the jQuery.js file that I added as an “image” rather than a file apparently 😀
Adding a file directly to the database is the method I would least recommend !