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
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!
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
If you are referencing the files on the server
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.
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 !
7 thoughts on “3 methods for adding jQuery to your XPages”
The trick to getting the correct mime type is to add the files to the WebContent folder via Package Explorer instead of importing them as File Resources. Another advantage of this approach is that you can drag entire folders directly to Designer and it preserves all the relative pathing. At runtime, the WebContent folder is treated as the “root” of the NSF.
Thanks Tim that’s a great tip!
Thanks for your tip. This is applicable only for Server based application but not for Local copy. Correct?
Great tip. Thanks.
When I try installing it, i get ‘Selected archive does not contain an update site.’
Ideas on why that is? I’m on 853.
Great article, but one thing worth mentioning that took me a while:
WOW – it has been there all this time – thank you !!