Pragmatic Patterns: Ajax - Architecting Your Code

[sabell2012]

I do a lot of ServiceNow architecture work for my company.   Every now and then a particular coding practice pattern consistantly drops out of that work.   So I thought I would pass one of these along to you:   How to best organize Ajax code for reusability, and maintainability.

As an architect I look for patterns.   What is a pattern?   It is best described as a way to organize a system to be at its best in efficiency, maintainability, and reusability.   Systems are best described as components of an application.  

Architecting Rules

1. The solution must be maintainable (read: simple).   Try to keep the number of "moving parts" as small as you can.   Reduce duplicate code to the absolute minimum.   In my book duplicate code equals a refactoring (a fancy coding term for simplifying) opportunity.
2. The solution must utilize reusable (read: generic data-driven) components.   Being able to reuse components from one solution on another is a time/money/life saver!   Sometimes this will violate rule number one just a bit as you may be forced to add components to achieve reusability.
3. The solution must be efficient (read: fast-baby-fast!).   The user experience must be as little-impacted as possible.

I am a huge proponent of maintainable code.   The old adage of:   "If it was hard to write it ought to be hard to read!" simply does not work as a software engineering practice!   If you can refactor an application so that it is easy to recognize what is being accomplished with the code, AND make it reusable then you have won the battle!   Now if you can go on to make this a standard in the way coders do the work then that becomes a "pattern"!

Now that we have gotten some of the definitions out of the way let's talk about the Ajax pattern I use.

The Ajax Pattern

This pattern organizes code and communication between the ServiceNow browser-side application, and the ServiceNow server-side.

Consider the following diagram:

Here I describe a pattern that seems to be more work than you would want to do.   Why would I bother with a UI Script on the front-end?   Why not just have the UI Action use Ajax to call the server-side?   Why would I then bother to have the server-side Ajax Script Include call yet another Script Include?

1. The UI interface components (Client Script, UI Action, UI Policy) all contain minimal code, and call data-driven functions in a UI Script.
2. The UI Script contains the minimal data-driven code to communicate with the server-side.   This is for maintainability, and reusability.
3. The Ajax Script Include contains the minimum code necessary to work with Ajax while calling data-driven functions in either a Script Include Class or Function Library.

So, back to the architecting bit.   We need to keep in mind some of the basic rules of interface programming:

1. Do not impact the user experience: The wait-cursor is your enemy!
2. Thin out your browser-side code.   Make the server do as much work as possible.   This has the benefit of reducing the browser footprint in memory, AND helping you to think in terms of reusability.   Generic coding means that the data is the "customization"; not the code.   You want, if possible, data to cause the code to react in certain ways.   To begin to make code reusable do so by "thinning" out your Client Scripts, UI Actions, UI Policies, etc., and pushing the code to UI Scripts.   At which point you may find that some of that code can be pushed further to the server-side.
3. Use asynchronous Ajax calls to the server, if possible, to free up the user experience.   Don't hold up the user and make them wait while the browser is communicating with the server across the web (synchronous).   Asynchronous good.   Synchronous bad.   Synchronous has its uses, but they should be rare!  
4. And the final rule: Refactor, Refactor, Refactor.   You want your code to be easy to maintain.   Do NOT have multiple copies of the same code floating around.   You might miss one if you find a bug; at which point the nightmare of finding the bug begins!   I hate nightmares.

With the server-side code it becomes a judgement call:

1. If the code is really simple then there is no reason to try to extract functions out of the Ajax Script Include into a Script Include function library.   I mean there is a minimum point; use common sense. 🙂
2. If the code is specific to only that Ajax Script Include, but can be refactored into a function, then keep it in the Ajax Script Include, and turn it into a function.
3. If the code can be refactored into a set of generic data-driven functions then look at using a Script Include class or perhaps a function library.   Again, I try to envision generic functions that are data-driven and can be reused by future scripts.

Remember: Engineer your code.   Think through the process.   The best code is maintainable, flexible, and well organized.   Don't be afraid of doing a bit of extra work to achieve clean code.

Steven Bell

If you find this article helps you, don't forget to log in and "like" it!

Also, if you are not already, I would like to encourage you to become a member of our blog!