Scripting for the Classic Mobile UI

[John Armstrong]

If you're using the Mobile UI for the first time, you'll want to make sure your custom scripts function the way you expect as part of your testing process.   There are some limitations in the Mobile UI that may require changes in any custom created scripts, or scripts that have been modified from their out of box versions.

Where to Look

The differences between the two UIs are on the client side (scripts running on your browser as opposed to the server).   The following elements make use of client side scripting, and may need changes to work as expected in the Mobile UI.

• Client Scripts (Including Catalog Client Scripts)
• UI Policies
• Navigator Modules
• UI Actions

Note that the out of box versions of these elements have either been updated to work in the Mobile UI, or marked to only run in the UI in which they function.   When you start using the Mobile UI, you'll be looking for customized   elements, which won't necessarily be compatible.

What to Look For

The first thing we need to do is find deprecated methods, unsupported methods,   and unsupported browser objects in the existing scripts.

Deprecated Methods

• getControl
• getElement
• getFormElement
• getOption

Unsupported Methods

• showRelatedList
• hideRelatedList
• showRelatedLists
• hideRelatedLists
• flash
• getSections
• enableAttachments
• disableAttachments
• setReadonly (Note that setReadOnly is available)
• getParameter

Unsupported Browser Objects

• Window
• jQuery or Prototype ($, $j, or $$)
• Document

Multiple Functions

The Mobile UI expects a single function within a client script.   Each Client script contains an onChange, onCellEdit, onLoad, or onSubmit function, depending on it's type.   All script in a client script needs to be contained within this function.   Additional functions are allowed, as long as they're contained within the top level script.

What To Do About It

Deprecated Methods

Deprecated methods are not available in the Mobile UI, but their functionality has been replaced with new methods.   Unsupported Methods and Objects do not have replacement methods, and should not be used in the Mobile UI.   For example, while getControl cannot be used, methods like g_form.hasField g_form.addDecoration can be used to achieve the same goals.

The complete list of methods added for use in the Mobile UI can be found in the Mobile GlideForm API Reference in the wiki.

Unsupported Methods

Unsupported are method that cannot be used due to the limitations of the Mobile UI.   When run in mobile, these methods will perform no action, so nothing will happen when they are run.   Unlike the deprecated methods, there are not mobile equivalents of these methods.

Unsupported Objects

Direct access to the Document and HTML elements are not allowed in the Mobile UI, as a result, the objects listed above are not supported.   Attempts to get values from these objects will return values of 'undefined'.

Multiple Functions

Functions of than the onLoad function (or whichever one is used) can be created, but need to be contained within the top level function.

Specifying Desktop or Mobile UI (or Both)

While the Mobile UI has it's own Navigator Modules and UI Actions, it shares it's Client Scripts and UI Policies with the Desktop UI.   Fortunately, you can specify which UI Type these execute in.   You can have these execute in both UI types, which will save you time when a script is valid in both Mobile and Desktop.     You can also set scripts only to run in one UI or the other.   That way you can have a script that uses the full functionality of the Desktop UI, and maintain a separate script for the Mobile UI that works within Mobile's limitations.

Client Scripts

Client scripts have a field called 'UI Type' which can be set to Desktop, Mobile, or Both.

UI Policies

UI Policies have a field called "Run scripts in UI type" which can be set to Desktop, Mobile, or Both.

Let's Take an example script that has been made usable in the Mobile UI.   The Example we're using is the out of box client script   "(BP) Set Location to User."   This script is triggered when the Caller field on the incident form is changed.   It checks the for the new Caller's location, and updates the Location field on the incident form to match.

This has already been fixed in Dublin and up, but here's how it originally looked in Calgary, back before the Mobile UI was introduced:

function onChange(control, oldValue, newValue, isLoading) {

    if (isLoading)

          return;

    if (newValue == '') {

          g_form.setValue('location', '');

          return;

    }

    if (!g_form.getControl('location'))

          return;

    var caller = g_form.getReference('caller_id', setLocation);

}

function setLocation(caller) {

    if (caller)

            g_form.setValue('location', caller.location);

}

There are a few things that needed to be changed to make this compatible with the Mobile UI.   Here's what we did.

Replace getControl

Our First issue is on line 10, we check to see if the location field is on the form using getControl.   This is one of those methods we can't use in mobile.   Fortunately there's a working alternate called hasField we can use instead.   So, we need to change line as shown below.   (Note that in instances Fuji, this has already been done).

From:

if (!g_form.getControl('location'))

To:

if (!g_form.hasField('location'))

Make getReference calls Asynchronous

The next issue is on lines 13-19.   On line 13, the script uses getReference to get the value of the caller_id field.   It a function called setLocation as a callback function.   This is good idea in general, but especially important in mobile, where it is required. The function itself is on lines 16-19.

While the asynchronous call is already handled, there's an issue, which is that the setLocation function is outside the onChange function, which is another thing that we can't do in Mobile.   The easiest solution is to just copy the setLocation function into the onChange function, so it appears after the place where it's called on line 13, but before the bracket that ends the onChange function on line 14.

Change the UI Type

Now that we've got a compatible script, we need to change the UI Type field.   By default, it's set to "Desktop," but now that we've made our changes we can set it to "Both" so it will run on either UI.

Here's how the script looks with the changes in place:

function onChange(control, oldValue, newValue, isLoading) {

      if (isLoading)

              return;

      if (newValue == '') {

              g_form.setValue('location', '');

              return;

      }

      if (!g_form.hasField('location'))

              return;

      var caller = g_form.getReference('caller_id', setLocation);

      function setLocation(caller) {

              if (caller)

                      g_form.setValue('location', caller.location);

      }

}

This is a simple example, but Illustrates a lot of the above points.   The links below provide additional information and instruction, as well as a few documented problems to be aware of.

Further Reading

Product Documentation

• Configuring the Smartphone Interface
• Mobile Client GlideForm (g form) Scripting
• Mobile GlideForm (g form) API Reference

Knowledge Base

• KB0551285:   Using Asynchronous Calls in Mobile UI Scripting
• KB0551074:   Mobile View Basics
• KB0549860:   Client Script or UI Policy is not running.
• KB0551212:   Mobile UI limitations

Community

• Debugging the Mobile UI from your Desktop
• Using Asynchronous Calls in the Mobile UI