Wednesday, August 8, 2012

Navigation Rules: Need to go somewhere?

The JSF Navigation rules functionality embedded within XPages is not terribly useful for most applications but I am working on an application where I feel they are just the ticket.


Navigation rules are used to externalize the target page of a particular action.  An example would be that you always want the client to go to the "Thank You" page after saving a document. Chances are you have been using navigation rules already even if you did not know it.  For instance, when you indicate what should happen when an XPage is updated either successfully or not.




You can globalize the rules by adding them to your faces-config.xml using the following simple format:


<!--  Rule used to take users back to the thank you page screen-->
<navigation-rule>
<from-view-id>*</from-view-id>
<navigation-case>
<from-outcome>goToThanks</from-outcome>
<to-view-id>/thankyoupage.xsp</to-view-id>
<redirect/>
</navigation-case>
</navigation-rule>

If there is a rule like this configured, then any action that returns the string "goToThanks" will whisk the client to the thankyoupage.xsp.  The "<redirect/>" tells the rule to show the page name in the URL address space.  Without it the user will be taken to the page but the URL address will not change.

The big benefit to implementing global rules is ease of maintenance but this is where the rub comes in.  If your XPage application does normal kind of navigation then there is not a big need to implement these rules to ease your maintenance.

Example:
  1. Your page goes to thankyoupage.xsp if it is saved.
  2. You want a new thank you page.
  3. You either a) update the existing one and you're done or b) create a new one and then update your XPage to go to the new page or c) rename the old and new thank you pages as needed when you are ready.

It don't get much more low maintenance than that my fellow XPagers.

But what if you have to go to the thankyoupage.xsp from several different places (links, buttons, managed beans) and you need to implement a new thank you page?  What about if you're developing something that you know you will be updating pretty regularly over time?  What happens if you want to be able to selectively phase in those newly updated XPage targets?  What happens if all of the sudden you want to go to an entirely new page but only from certain buttons which are peppered throughout your application?

In that case you need to have something a little better or else you are going to be doing a lot of updating after you add a new page here and there.

For instance, consider an application where an application uses separate XPages to rename a user, remove a user, change their email or password.  After each of those pages you want them to go back to the main user management screen.  Fine.  You hook up all of those pages using OpenPage commands or SSJS redirect commands.  No problem.

Now you make a new User Management page.  Well if you aren't using navigation rules you need to go and find and update every single place where you told the client to go to the original User Management page and now go to the new page.  Time consuming for sure and depending on how much you have embraced the "Java lifestyle" in your XPage development, you may be likely to miss on occurrence here or there.

If instead you configured a global navigation rule and everywhere you needed the client to be redirected to that page you simply did a 'return"goToThanks" then when it comes time to update all of that code all you need to do is update the navigation rule and you're done.  And yes, these changes are "hot" so the server does not need to be restarted or any such craziness.  You change it, it is done.

Is this a good thing to use in every application?  Certainly not.

Is this the only way to minimize maintenance going forward?  Nope.

But if you find yourself working on a project like the one I am working on with a small circus of navigation paths through the application plus a guaranteed level of continued modification over time, you might just find that adding navigation rules, global or local (they can be added to individual XPages as well), is just the ticket to get you where you want to go.