Nov 16, 2012

Enhancing MT user experience with JavaScript; Part 1

This is the first part (hopefully) of a series dedicated to demonstrate how JavaScript can be used to enhance user experience on AR System forms. Provided examples are all designed for MidTier 7.6.04 or 8.0.0.

The Mid-Tier and AR System in general are great pieces of software, excellent toolboxes to create apps and workflows real fast.
Sometimes though you can stumble upon a requirement that is very complicated, or simply impossible, to answer with basic active links. In this case you have two options :
  • drop the requirement
  • use JavaScript

The basics

You probably already know how to execute a JavaScript function. If not, you may want to take a look here.
To do this, you execute a "run process" command starting with "javascript".
javascript alert("Hello world");

Now, maybe you also know how to get back into AR System workflow from JavaScript. If not, you can read this.
The core JS code of the MidTier exposes 3 functions for you to call from your own JS code :
  • arInvokeEntryPoint ("windowID","serverName","guideName") — Executes the specified entry point guide as long as the application list field (ID 1575) is also available and visible on the same form that contains the view field.
  • arInvokeGuide ("windowID","serverName","guideName") — Executes the specified guide.
  • arInvokeForm ("windowID","serverName","guideName","mode") — Executes the specified form in New or Search mode. Valid values for mode are New and Search.

Finally, did you know you can add some HTML, JS or CSS in your views ?
In DevStudio, display the properties of a view. You can see the "web header content" and the "web footer content" properties. You can insert your JS code here, or import an external .js file hosted on your MTs.

First sample : simple regular expression validator

We now have a complete access to JavaScript to make our users' work a little easier.
The example I chose to show you is something that is often asked : client-side form validation.
As you may already know, there are some nice AR plugins out there that allow you to validate user inputs. But this is done on the server side, and requires a round trip.

The attached .def is to be imported on any 7.6.04+ AR System server.
You will find a display-only form named "_TUT:JavaScript1", with 3 fields.
The first one is a selection field with a label. It has only one value, "email", but you can add more if you want to test your own regular expressions.
When you select "email", a regular expression is written in the RegExp field. I know it is not strictly correct for an email validation, but hey it's just an example.
Then write something in the 3rd field, and press enter to test it against a regular expression above.

So, how does it work ?

The magic is stored in the web header property of the view :
What does this do ?
When the "checkValue" function is called, it very basically tests the "value" parameter against the "regexp" regular expression.
If the test is positive, it calls the guide "positiveGuide".
Else, it calls the guide "negativeGuide".
Nothing too complicated here.
The only thing you have to be aware of is the recent first parameter of the arInvokeGuide function, that will hold the Window ID. This parameter is required starting version 7.6.04. Before this version only the two last parameters, server and guide name, were required. Beware if you are in a pop-up, a pop-in, or an inline form.
On return in the "Value" field, an active link executes this run process action :
javascript checkValue("$Value$","i" ,"$RegExp$","$SERVER$","_TUT:JavaScript1_ResultOK","_TUT:JavaScript1_ResultKO");

What's next ?

This still looks 2000ish.
In the next part, I will explain how to bind new event handlers to AR System fields. Using this, the example will show you how to make an "on-the-fly" validation of user input.

2 comments:

Unknown said...

Great stuff. Can't wait for part 2!

Unknown said...

Dear Unkown, it's done ;) It's a repost from BMC Communities though.