Why using XPages Partial Refresh is sometimes easy for developers and bad for users

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

part1

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

Why “we need to reduce clicks” is sometimes a fallacy.

In this article i will discuss why I believe the phrase “we need to reduce clicks” is a fallacy (at times).

Introduction

The plain statement of “we need to reduce clicks” really does not tell the whole truth about an application when it comes to modernization. I believe the true statement is that “We need to reduce clicks that annoy us“. There is a very clear distinction in my mind and I will try and explain.

It is all about design and the user experience.

When a user has to select a piece of information and then “action” it, that is probably at least two clicks.

Two clicks is two clicks right?

In the first scenario (lets say) – Looking at a view of data which needs actioning (circa 1998) to get the job done the user needs to:

  1. Click on the URL to open the document
  2. Moves their mouse to, and click the “Approve” butto

In the second scenario (circa 2005) a user is able to:

  1. Select a checkbox next to a list of document
  2. Move their mouse to and click the “Approve” button

In the final scenario (2013) the user:

  1. Right clicks on a document
  2. Selects “Approve” from the context menu with only a minor mouse movement

In all of these situations the user only has two clicks – but in a decreasing level of annoyance the User Experience gets better and better.

I grant you that if the user has to:

  1. click on a document
  2. click the edit button
  3. change the status combo to edit
  4. click the save button

that is two clicks too many and we could reduce the number of clicks (but how long does that REALLY take? less than 30 seconds at best).

But is too many clicks really the problem? No I don’t think it is. The problem lie at the heart of efficiency, expectation and patience.

So what’s the real problem here?

The user perceives that they only has a fixed amount of time to dedicate to “having to do their job” and if Approval of something is their responsibility they want to get it done as quick as possible. In today’s business when local LANs are lightning fast the pages refresh quickly. Time itself to do the approval is in the order of seconds, even in the worst case scenario.

But the perception of time taken to achieve the necessary “action” is verbalized as “need to reduce the number of clicks”.

I believe it is better verbalized as “need to reduce the number of clicks that annoy me”, which translates to “make me the least annoyed to have to do this.”

Conclusion

“Reducing the number of clicks” is sometimes a fallacy, improving the user experience of the same number of clicks they have to do to get their job done should be the real goal.

Bonus Scenario

Just for giggles…

One actual way of reducing the number of clicks by 50% (from two to one) would be to add “drag and drop” to the document and have the user drag the document to an “Approved” landing area – I am not sure that would improve the experience though.

Text formatting power

I am working on a demonstration database for doing field editing via the web (more to come later) and I needed a list of random data for my example. I got some Super hero data from a website but the formatting was not good…

Sample Super Hero Data

Many Many records of varying length/number of power parameters. I need to get them all on a single line if I have any chance of importing them into Notes.

Over to my least favorite text tool – favorite text formatting tool – MS Word….

If you didn’t know you can manage New Lines (^p), Tabs (^t) and all sorts of other hidden characters very easily in Word.

So we replace all NewLines followed by a comma, with just a comma

Text replacing in MS Word
Text replacing in MS Word

And there we go simple as that

Formatted Text
Formatted Text

 

Now imagine you wanted to create a string out of that in LotusScipt – I don’t know why you would but hopefully you can make an analogy to something to would need to do

I want to turn

Professor X,Telepathy,Extra-sensory perception,Eidetic memory

into

Print {Professor X,Telepathy,Extra-sensory perception,Eidetic memory}

simple

Take the New Line (^p) and add a } before it, ending the row and then immediately after it on the next line insert Print { before the text

Converting to Lotus Script
Converting to Lotus Script format

which creates something we can copy and paste into the Lotus Script editor without causing errors

Final Lotus Script
Final Lotus Script

 

– Productive

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