In this article I will discuss the potential issues of using using a Partial Refresh in XPages and how developer addiction and dependency on it is bad for users.

Introduction

This is the hardest blog post I have written – and I have written and destroyed it about 5 times before this one. Too many times I have come across what I consider to be poor design choices. I am always motivated to write when I am annoyed and rant and whine about how the over use of Partial Refresh is easy for XPages developers and bad for users.

Nathan Freeman’s wrote a remarkably thoughtful and well presented article on performance pro tips and I finally determined to write a constructive, helpful, positive on article on how partial refresh can be used destructively..

This is also written with the hope of triggering a discussion because I have my opinion and I want to find out everyone else’s as well.

The Partial Refresh

Partial refresh is a really powerful addition to the IBM Notes Domino developer’s toolbox. Coming from pre-XPages domino, refreshing a section of the page was always a manual task, you had to be extremely careful to manually retain front-end/back end synchronicity and it was just painful.

With the creation of the partial refresh XPages developers have a new tool which they did not have before – the ability to recompute virtually any section of the page, automagically retaining all field bindings and actually creating a better user experience for the user than the out of the box pre-XPages Domino experience.

Don’t get me wrong and I want to be clear on this, Partial Refresh is a phenomenal addition to Domino development and offers fantastic possibilities to developers.

It also offers the ability to use it as an excuse for poor development techniques and bad architecting of an application

Marky’s Rule of Thumb

“The more DOM elements you have to reload using Partial Refresh, the worse your user’s experience”

Think about it – the more DOM elements you have to refresh the more of this you have to do:

• Post all necessary field state data to the server to retain all the fields
• On the server:
  • Traverse through the JSF lifecycle (including nad not in order)
    • recomputing the rendering and loading properties of every control (not just the ones being refreshed)
    • recompute the values of every control (not just the ones being refreshed)
    • recompute all the scoped variables
    • run validation on all fields (unless you use partial execution)
    • Trigger and access any serverside events associated with the controls and which then go through the JSF lifecycle
    • Create the HTML to send back to the server
• Wait for the download of the returned data to the user
• Parse the response and then insert it back into the browser’s DOM
• Trigger all the stages of the dojo ajax model (overall)
• Give control back to the user

So we shouldn’t use Partial Refresh?

That is not what I am saying – but you absolutely should use it judiciously and sparingly. Better planning and better execution of the XPage application model will provide for a better user experience.

Partial Refresh allows the developer to make potentially bad design decisions which are only at the expense of the end user. Having access to server-side variables at all times is intoxicating and destructive.

** Here’s a perfectly good example: Hiding a field or section based on a separate combobox selection

You have two choices:

• Use some JavaScript (Dojo or jQuery) and write two or three lines of code. Never leaving the browser client.
  • and if you wanted to be really slick (!should do it!)  then you could use a jQuery .toggleClass() and actually make the transition aesthetically pleasing for the user
• Send to the user experience to the server, wait for all the necessary DOM elements to re-compute their rendered properties and then send it all back to the user

Your requirement might clearly state that you need to hide a field based on a user’s selection – but the developer has the choice how to execute it. “oo oo oo I can use a Partial Refresh” is not the appropriate answer in every case.

** Another example is: the need to update scoped variables based on a combobox selection

Don’t. Just don’t. Simple

If you are tracking the state of the web browser interface using server-side scoped variables you are doing it wrong. The browser DOM already knows the state of the page – why track it twice and double your code?? Unless you are running a google docs type approach to saving everything on the back end based on the user interaction on the front end, you do not need to keep scoped variables up to date in “real-time” with the user interface.

If you must, must, must update something small (like a scope variable) on the server – use a JSON-RPC service which will send values to the server with the minimum of effort, transport and should not affect the user.

** Final example: Because as a Java developer I must have my n-tier architecture and a full separation of UI and business logic

You know who you are……. 😉

For user experience your XPage is a web based platform and the back end technology you use is irrelevant to the user. Your job is to make their experience the best it can be and not the easiest you can program it. If that means you need to learn something new or involve someone else then you have a duty to your customer to do so.

Deep breath

I don’t really think there is  a perfect rule to determine if Partial Refresh is the right thing to do – but don’t assume it is the only thing you can do. Design decisions should always be considered from the perspective of the user experience 1st and ease of development 2nd, not the other way around.

Server-Side programming is a large part of XPages functionality and will continue to be so. There is nothing wrong with having a significant part of the application logic happen on the server.

User expectations are based around the slick interfaces they see, they couldn’t give two hoots what the back-end architecture is.

Good times to use Partial Refresh

Any time it enhances the user experience.

To recompute field (e.g. selectbox) values when a user exits a decision point on the application workflow (only refreshing the fields you absolutely need to).

It is necessary to use it if you want to create an application using the dynamic content control.

It is necessary if you have any dynamic data bindings happening on the page.

It is a good idea if you have a slow connection and want to keep the initial page size down and only show the users what they need to when they need it.

*insert discussion points here* <—– 🙂

I have intentionally left the last part of this short to garner comments and find out what everyone else thinks