Metastorm BPM allows for client side scripting using JScript and VBScript. Since at the moment, IE is the only fully supported browser for the web client, I tend to utilize JScript as the language of choice (it’s a personal preference as I lean towards the C# like syntax). Client side scripting can assist in form validation, loading dynamic text into labels, working with local Active X Objects and of course DOM object manipulation as well as a number of other useful client side ‘tweaks’. You can obviously go mad with client scripting and get as creative as you need, but always remember that some techie somewhere will need to support your deployed Metastorm project once its been put into production and a script heavy process on either side (server or client) can become a support nightmare.
Client Scripting
So what do your client side scripts have access to? Client scripts execute on, well… the client so variables or functions are not available to the scripts, however the values of fields on the currently loaded form are available (since they are within the scope of the client, i.e. the data that the client browser is currently hosting). Grids and fields on the form are holding values away from the Metastorm engine and so these values are accessible by the client. Client side methods provide access to these ‘temporary’ field values, what follows is a quick summary of the methods you can access in your scripts:
eworkSetField(“<field name>”,”<attribute>”,”<value>”) – Sets the value of a named field
eworkGetField(“<field name>”,”<attribute>”) – Gets the value of a named field
eworkGetCell(“<name of grid>”,”<column index>”,”<row index>”) – Gets the value of the specified cell
eworkSetCell(“<name of grid>”,”<column index>”,”<row index>”,”<value>”) - Sets the cells value
The above allows you to pull the values of metastorm fields into your scripts for calculation or other manipulation and then set those values back to the client fields. The client side scripts are called from the client extensions of buttons, grids and forms and support the client events OnLoad, OnBlur, OnClick, OnFocus and OnCellBlur. In other words, client side scripts can be executed from button clicks, entering a field, exiting a field, loading a form, entering a grid cell and exiting a grid cell.
OnSubmit / OnCancel
You are able to specify a client side script, usually on form load that hides or shows the Submit and Cancel buttons of a standard Metastorm BPM form. This is a very simple client side function that looks something like the following (the same applies for eworkShowSubmit) :
function hideCancel() {
eworkShowCancel(0) //This is a boolean parameter
}
On your forms ‘OnLoad’ event you can simply reference this parameterless script, like so (in client extensions) : OnLoad=hideCancel() & Language=JScript
On Submit
Whenever you create a client side script that is to be executed from an ‘OnSubmit’ event, you will want to return a boolean value as to whether the submit should be processed by the Metastorm BPM Engine. Lets take a simple validation script, if the script validates the forms field values correctly, then a true value should be returned and the form will submit, else the script should return false, meaning that the submission will not occur, giving the user an opportunity to correct field values (an alert() should be used as a prompt to the user regarding what exactly needs correcting on the form). An important point to note is that the ‘OnCancel’ event will ignore true or false returns as a client script cannot prevent the form from being cancelled.
The Document Object Model
Since Metastorm forms are represented in the browser, fields are subject to the document object model, therefore they are subject to standard DOM and JScript manipulation. Lets take the document.getElementById method for example, this can be used to reference a metastorm field object within the client, as follows:
var MyData = document.getElementById(“myMetastormTxtField”).value //returns the value of the object being referenced, in this case a forms text field.
For fields such as a label caption, that references an html div (i.e. writing <div id=”MyDiv”></Div>) you can populate the innerHTML property like so:
document.getElementById(“MyDiv”).innerHTML = “<b>My HTML Content</b>”
Most HTML fields have a common set of properties and methods that can be used in client side scripting. Common field properties, that apply to text, check boxes, memo etc:
field.value – sets or returns the value of the field object
field.size - sets or returns the size in characters of the field
field.name - sets or returns the name of the field (document.getElementByName used to refer to the field)
field.id - sets or returns the name of the field (document.getElementById used to refer to the field)
field.innerHTML - gets or sets the string HTML content of an element (normally used for the DIV object).
… and common methods:
field.click() – simulates a button or checkbox mouse click
field.blur() - removes focus from the field
field.focus() - sets focus on the field
field.select() - selects the contents of the field (e.g. text contents of a text field of comments field)
Style
Lastly, I want to touch on style, since you may wish to manipulate a Metastorm form fields style characteristics. The style object is applied to other document objects in order to apply style characteristics. They are accessible by referencing the object the style is applied to:
document.getElementById(‘MyTextField’).style.property = ‘value’
Examples:
document.getElementById(‘MyTextField’).style.color = ‘red’;
document.getElementById(‘MyTextField’).style.font=”italic bold 12px arial,serif”;
document.getElementById(‘MyTextField’).style..textAlign=”right”;
document.getElementById(‘MyTextField’).style.visibility = “hidden”;
As you can see, client side manipulation can be useful to your Metastorm design needs, but be warned that making your procedure overly complex with client side scripts when Metastorm is quite capable of providing certain functionality is a bad move.
sites (plus my additional comments):
