When should you use jQuery in your XPage?

For full disclosure, I used jQuery with Domino long before v8.5 at a time when the dojo documentation sucked big ones and it was nearly impossible to figure anything out. Today though that is much improved and the dojotoolkit website and the work done by sitepen have done a lot to catch up.

I am more familiar with jQuery syntax and the core library capabilities and I think I will always prefer to use jQuery than dojo given a choice and even playing field. In traditional Domino it is a level playing field as neither library is loaded by default. But that all changed with XPages and I am forcing myself to have to learn dojo because it just doesn’t make sense to use jQuery “just cos dojo sucks”.

jQuery does not conflict with dojo and can be used very successfully in tandem with each other. But there are some things to consider before you do.

jQuery selectors are IMHO easier to read and more intuitive to understand. jQuery uses a combination XPath/CSS query selection process and dojo uses a CSS3 selector paradigm

So why shouldn’t I use jQuery?

If you are going to add jQuery there has to be a good reason/purpose other than “‘cos I like jQuery and dojo sucks”. If you add a jQuery library you are:

  • adding additional overhead to the database
  • adding potential maintenance issues down the road
  • adding to the download size of every XPage which already has the dojo overhead by default.
    • (Yes you can turn dojo off but why would you? If you not going to use the XPage functionality don’t use an XPage design element……)

So if you are just doing a basic selector to get a page element or a basic animation, there is really nothing dojo can’t do any worse than jQuery. If you want to see a simple comparison between dojo selectors and jQuery selectors check this out

Dojo & jQuery side by side. Part 1: DOM Basics

Dojo & jQuery side by side. Part 2: Animation

So when should I use jQuery?

When you can’t do something you need to in dojo, or just just does not make sense to re-invent the wheel. jQuery is now more popular than Flash in terms of web usage for the most popular sites. dojo isn’t even on the map when it comes to web usage tracking. In terms of community size and usage jQuery dwarfs dojo everything else and because of that there is a lot of libraries to chose from.

In an XPages environment, the real benefit is not so much using jQuery itself, but in taking advantage of the thousands of plugins available which other people have written. There are plugins for everything from:

  • Menus
  • Calendars
  • Embedded video players
  • Photo galleries
  • Page Design libraries
  • Effect libraries
  • MVC Framework design libraries

I think I am going to start a series of weekly jQuery plugin examples (in XPages) to show what can be achieved very easily with the minimum of code. Let’s see how far it takes me before I run out of the over 4000 jQuery plugins and jQuery mobile

Using jQuery to add table interactivity to your XPage

Very quickly and easily we can create a pretty good looking data view as an XPage – drag and drop a view control onto your page and your off in under 60 seconds – very simple, very functional.

Simple XPages view of data
Simple XPages view of data

However, for many users though (especially “older” corporate users, who are usually the ones making decisions on your projects and paycheck) it is simply not enough to be “functional”, it needs to be EASY. For example:

  • On a large table it is difficult to scan across from one side to the. Especially as screens get larger and resolutions get higher we are putting more and more data onto a page
  • Which link opens the data set? The only indication we have is the blue link on the left – not obvious to all

User’s expectations are based on their experience with the internet and everyday that gets higher and higher. As developers we are always looking for ways to make our pages look snazzier and also easier to user at the same time.

Here are some simple tricks using jQuery and my x$ function.
Add all the following to the onClientLoad event of the XPage.

  1. To make the table rows alternating colors :
    The jQuery is selecting every “even row” within the viewPanel and applying the “alt” class to it

    x$("#{id:viewPanel1}", " tr:even").addClass("alt")
    
    Adding Alternating Lines using jQuery
    Adding Alternating Lines using jQuery

     

  2. To make the table rows highlight with a mouseover
    The jQuery adds a listener to each row in the viewPanel1 which toggles the “active” class when the row is hovered over.  I also added a hand pointer to make it look selectable.

    x$("#{id:viewPanel1}").delegate("tr", "hover", function(){
        $(this).css('cursor', 'pointer' ).toggleClass("active");
    });
    
    Adding a mouseover color to a table row using jQuery
    Adding a mouseover color to a table row using jQuery

     

  3. Make the entire row selectable with the 1st column’s href 
    The jQuery is selecting the “href” on the “first a” that it finds in the row and is binding it to the click event of the whole row. This is currently going to open a new page.
    Note: ” tr:gt(0)” selects all rows index greater than 0, that ignores the title row at the top which does not have the links in we are looking to use

    x$("#{id:viewPanel1}", " tr:gt(0)").bind('click', function(){
        window.location = $('a:first',this).attr('href');
    });
    
    Binding the first anchor tag to the whole row using jQuery
    Binding the first anchor tag to the whole row using jQuery

    And we could stop there – 7 lines of code and we have made major improvements to the data table. But to complete the transformation we will bring the data to the user rather than opening up another window.

  4. Make the page link appear in a nice looking dialog
    The jQuery is opening a dialog box on the page and displaying the content using the url of the row. Having to click back and forth from information is distracting and tedious. This way it helps the user never leave the page of information they are looking for. This is a little more complicated, but not really if you step through it.

    • We bind to the click event of the first row
    • We trap the page offset of the row which was clicked.
    • We open the travelDetails dialog (where id=travelDetails is just a blank label at the bottom of the page)
    • The position of the dialog, the height, width and the fact that it is modal are set.
    • As we saw before we can get the anchor href from the first column and with that we ajax in the contents of that form
    • The HTML returned is then inserted into the travelDetails and displayed to the user.
    x$("#{id:viewPanel1}", " tr:gt(0)").bind('click', function(e){
      var offset = $(this).offset();
      e.stopPropagation();
      x$("#{id:travelDetails}").dialog({
        close: function(event, ui) {
        $(this).empty();},
        position: [100, (offset.top)-100-$(window).scrollTop()],
        resize: false,
        width: 400,
        height: 250,
        modal: true
      });
      x$("#{id:travelDetails}").dialog('open');
      $.ajax({
        type: 'GET',
        url: $('a:first',this).attr('href'),
        context: document.body,
        success: function(html){
          x$("#{id:travelDetails}").html(html)
        }
      });
    });
    
Displaying the travel details in a simple dialog with jQuery
Displaying the travel details in a simple dialog with jQuery

This process is just as applicable to any normal Domino webpage (non-XPage) with an embedded view in it.

 

Update 1 March 2012

I have been asked to add the style sheet which you will need to add to see the effects. Ideally you should add it to a Stylesheet and add it to the XPage as a resource, but for the sake of demonstration just copy and paste this into the source code at the top under the <xp: view tag

<style>
.alt{ background: #ecf6fc; }
.active { color: red; background:#CCCCCC; }
</style>

Adding Teamstudio Configurator – Alternate method

Update March 2014

See the comment at the bottom of the page for updated links and/or contact your Teamstudio rep to find out the most up to date links

————————

I LOVE TeamStudio configurator – always have, probably always will

For some reason though (probably permissions or firewall related) I am unable to do the installation via Drag and drop from the website. I drag and drop it – and nothing happens…

Add Configurator 29 Problem

So I figured out a work around and here’s how I did it – might not work for everyone but it might. This also provides an interesting insight into the process and how everything is interwoven in this process.

Right clicking on the Configurator icon and copying the link address gives me this

http://ftp.teamstudio.com/Edition29/en/update/widgets/extension_configurator.xml

Looking at the file I find the ftp root for the 29 update

http://ftp.teamstudio.com/Edition29/en/update

Going there I found the site.xml and that is the one I was looking for

http://ftp.teamstudio.com/Edition29/en/update/site.xml

In the Notes Client

Tools—>Widgets—>Getting Started with Widgets

Adding a Widget
Adding a Widget

 

Select Features and Plugins and hit Next

Add Configurator 29 Step1
Add Configurator 29 Step1

 

Enter the site.xml URL and hit Load

Add Configurator 29 Step2
Add Configurator 29 Step 2

Select Configurator and hit Next – You will see it start to download

Add Configurator 29 Step3
Add Configurator 29 Step 3

Once it is complete

Add Configurator 29 Step4
Add Configurator 29 Step 4

Next

Add Configurator 29 Step5
Add Configurator 29 Step 5

Next

Add Configurator 29 Step6
Add Configurator 29 Step 6

Finish

Add Configurator 29 Step7
Add Configurator 29 Step 7

Restart and we’re done

I am assuming it is the same steps for any of the other products which appear in the site listing but I have not yet tried them.

– Productive

Show heap status shortcut(s)

For those of you who don’t know, Domino R8 now runs in Eclipse. Eclipse is a Java based application and can be rather memory intensive. You can see the allocated Java Virtual Machine space (heap size) in your designer by going to:

File –>Preferences—>General

Show heap size
Show heap size

And this shows you the heap size and allows you to clean it up and speed up your designer client.

Domino Designer Heap Size
Domino Designer Heap Size

The problem is when you check and save this open it is not remembered from one designer session to the next – even though it remains checked it is not displayed.

Here is way for us lazy/productive people to turn this link on with the minimum of effort:

Keyboard only

  1. Alt+F
  2. F
  3. (Type) General
  4. Enter
  5. Enter

Gaming Keyboard (Productivity Enhancer)

Even better when you can program your gaming keyboard to do a single button push for you 🙂

Creating a shortcut to show heap size using Logitech G15 gaming keyboard
Creating a shortcut to show heap size using Logitech G15 gaming keyboard

StrokeIt

StrokeIt is a Windows Mouse Gestures program or in their words “an advanced mouse gesture recognition engine and command processors”. It can be programmed to perform almost any shortcut task – here is the Show Heap

Strokieit Show Heap shortcut
Strokieit Show Heap shortcut

Anything else?

  • There is AutoHotKey which is another shortcut program
  • There is Ben Poole’s SendKeys replacement but I have had timing issues with that and cannot get it to work consistently.
  • I’d like to do it in @Formula and add it to a toolbar button
  • Let me know what you’ve come up with…!