Nov 28, 2012

Enhancing MT user experience with JavaScript; Part 2

This is a repost from : https://communities.bmc.com/communities/docs/DOC-21818
If you are a BMC Remedy AR System user/admin/developer, you really should participate to Communities, there are many things to learn, fast.

This is the second part 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.
In the first part, we saw how to call a JS function from active link, how to call active links from a JS function, and then how we could use that to provide a simple client-side form validation.

Binding extra event handlers to fields

Active links can be set to be executed on return, gain/loose focus, menu select ... It already covers a lot of usual needs.

Now, with what we saw in the first part, we have all we need to add more events.

For example, the "run process" command below adds a handler function for the "onkeyup" event of the field 700000002, which calls "TheGuideName" guide :
javascript document.getElementById('arid_WIN_0_700000002').onkeyup=function(){ arInvokeGuide(0,"$SERVER$","TheGuideName");}

The list of events you can handle is on the w3c page for scripts.

Second example : on-the-fly regular expression validator

Let's use this to create a better client-side validation.

We want the validation to be done as the user types. It shouldn't display any indicator if the tested value is null. Oh, and the users like round corners and shadows.



Yay, that looks better !
The .def file is available here.
Simply import it and open the "_TUT:JavaScript2" form.

So, how does it work ? 

Remember the "checkValue" function we defined in the web header view in the first part of this document ?
Let's change it just a little, to get the tested value back into an AR System field.
Why do we want the value back ?
First, because it demonstrates how you can set a field from JS. Simply setting the <field selector>.value with JS won't do because the MT keeps a record of fields and their values. You need to call the "S" function to update it.
Second, because if you don't, you won't be able to check if the value is null or not (just test it ).
To make it look a little prettier than the standard AR System forms, the field is customized via CSS, still in the web header content property of the view :
The checkValue function is called when the "onkeyup" occurs. To do it, we execute this javascript in a "Run Process" action, when you select the field format in the menu.
javascript document.getElementById('arid_WIN_0_700000002').onkeyup=function(){ checkValue(this.value,"i","$RegExp$","$SERVER$","_TUT:JavaScript2_ResultOK","_TUT:JavaScript2_ResultKO");}
It says, Ok get me the field 700000002. It has a "onkeyup" property. Assign it with a value that happens to be a function (that's a fun thing in JS). The function calls "checkValue". The first parameter is the value of the field that it's attached to.

The downside

As you see, we can do a lot of things if we start to put a little JS in our AR System forms.
BUT
  • it requires non-Remedy skills to maintain
  • your code is expecting very specific things from the HTML generated by the MidTier : the ID for the fields, the F & S functions, arInvokeGuide, ... They all could be dropped in the next MT version 
  • the documenting programs like ARInside won't know about your JavaScript, just like when you execute Direct SQL commands

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.