Skip to content

Application object

The Leap application object, referenced by using 'app', provides access to information relevant to the whole application. The object has several built-in functions.

Functions

getAppPage

Returns the user interface app page object for the provided appPage id.

Syntax 

app.getAppPage(appPageId)

Parameters

Parameter Description
appPageId Optional. The id of the app page to retrieve, if not supplied the current app page id is used.

Example 

var myAppPage = app.getAppPage("AP_Welcome");

getAppPageURL

Returns the URL for navigating directly to the app page for the provided app page id and application uid.

Syntax 

getAppPageURL(appPageId, appUid)

Parameters

Parameter Description
appPageId Optional. The id of the app page to retrieve, if not supplied the current app page id is used.
appUid Optional. The uid of the app to retrieve, if not supplied the current app uid is used.

Example 

var appPageUrl = app.getAppPageUrl('AP_Welcome', 'e09e7739-2214-4e64-88e3-9f54a47c3fdd');

getAppURL

Returns the URL for navigating directly to the application.

Note: The application will load the form or app page defined in the "Home Page" field on the Settings tab.

Syntax 

app.getAppURL()

Example 

var appUrl = app.getAppUrl();

getChartsURL

Returns the URL for navigating directly to the charts page of the form for the provided form uid and application uid.

Syntax 

app.getChartsURL(formId, appUid)

Parameters

Parameter Description
formId Optional. The id of the form to retrieve, if not supplied the current form id is used.
appUid Optional. The uid of the app to retrieve, if not supplied the current app uid is used.

Example: 

var url = app.getChartsURL(form.getId(), app.getUID());

getCurrentUser

Deprecated - Use app.getCurrentUserId()

getCurrentUserId

Returns the user's "identifier" - the identifying name of the currently logged in user.

The identifying name is the property as defined by the ibm.was.MemberManager.userProps.id property that is located in the Leap_config.properties file. For example, uid, cn, mail, displayName.

If the user is not authenticated, then the function returns the string "Anonymous Guest User".

Syntax 

app.getCurrentUserId()

Example:

To populate the current user's login name into a field in the form, place the following statement in the onLoad event of the form: 

// change F_SingleLine to the ID of the desired field 
BO.F_SingleLine.setValue(app.getCurrentUserId());

getCurrentUserEmail

Returns the user's email.

Syntax 

app.getCurrentUserEmail()

Example 

BO.F_UserEmail.setValue(app.getCurrentUserEmail());

getCurrentUserDisplayName

Returns the user's full display name. Ex. "Eduardo Ramírez López".

Syntax 

app.getCurrentUserDisplayName()

Example 

BO.F_UserName.setValue(app.getCurrentUserDisplayName());

getCurrentUserInfo

Returns the object containing the attributes of the current user.

Syntax 

app.getCurrentUserInfo()

Example: 

{
  id: "pflorez123", 
  email: "Pedro.Flores@example.com", 
  displayName: "Pedro Flores", 
  userType: "owner"
}
Note: Not all attributes are available in all deployments. In that case, some of the values will be null.

userType – possible values:

  • "owner" – if current user is the app owner
  • "guest" – if the current user is anonymous
  • "" (empty string) – in all other cases

getCurrentUserRoles

Returns a comma-separated list of all the roles for which the current user is a member.

Syntax 

app.getCurrentUserRoles()

Example: 

item.setValue(app.getCurrentUserRoles());

getFileBaseURL

Returns the relative URL to the current browser page where all files that are uploaded into the application at design time are stored. This does not include images and CSS files. All files are saved as anonymous resources that can be viewed by anyone.

An example url is ../../../../../anon/1/content/9.3.6.33/97eeb588-2fff-49a7-89c1-5000885dafb4/1421171344944-2/desktop/en/en/en/desktop/files/

Syntax 

app.getFileBaseURL()

Example

This example demonstrates how to create a link item in a form that refers to a file included in the Leap application.

  1. Attach a file (not image or CSS) to your Leap application. Go to Settings...Files and click the 'Add' button.
  2. Add a Link item to the form
  3. In the onShow event of the Link item add: 
    item.setLinkValue(app.getFileBaseURL() + "sampleAttachedFile");

getForm

Returns the user interface form object for the provided formID. If used to return a form that is not shown or loaded, then the object that is returned is not fully operational and should be used for hooking up dynamic event handlers only.

Syntax 

app.getForm(formID)

Parameters

Parameter Description
formId The id of the form to retrieve.

Example: 

// Register an event listener to a service in order to do something when it returns
var form = app.getForm('F_Form1');
var service = form.getServiceConfiguration('SC_ServiceConfig0');
service.connectEvent('onCallFinished', function(pSuccess)
{
  alert('call finished');
});

getFormLaunchURL

Returns the URL for navigating directly to the form for the provided application uid and form uid.

Syntax 

app.getFormLaunchURL(formId, appUid)

Parameters

Parameter Description
formId Optional. The form id, if not specified the current form id is used.
appUid Optional. The app uid, if not specified the current app uid is used.

Example: 

var url = app.getFormLaunchURL();
var url = app.getFormLaunchURL(form.getId());
var url = app.getFormLaunchURL(form.getId(), app.getUID());

getImageBaseURL

Returns the relative URL to the current browser page where all images that are uploaded into the application at design time are stored. All images are saved as anonymous resources that can be viewed by anyone.

An example url is ../../../../../anon/1/content/9.3.6.33/97eeb588-2fff-49a7-89c1-5000885dafb4/1421171344944-2/desktop/en/en/en/desktop/image/

Syntax 

app.getImageBaseURL()

Example

This example demonstrates how to create a link item in a form that refers to a file included in the Leap application.

  1. Attach an image file to your Leap application. Go to Settings...Files and click the 'Add' button.
  2. Add a Link item to the form
  3. In the onShow event of the Link item add: 
    item.setLinkValue(app.getFileBaseURL() + "sampleAttachedImageFile");

getLocale

Returns the current locale of the application, according to the application's settings or the current user's preferences. The returned value is a locale code, in accordance with Tags for the Identification of Languages (RFC 3066).

Syntax 

app.getLocale()

getLocation

Allows the form designer to get the current user's location.

Syntax 

app.getLocation(callbackFunction, highAccuracy)

Parameters

Parameter Description
callbackFunction the callback that occurs after the location request finishes.
highAccuracy Optional. The form id, if not specified the current form id is used.

callbackFunction - The designer must define the function to have one argument which will be assigned a Position object if the location request was successful, or null if the request was unsuccessful. Inside the function the designer can assign location attributes to different fields. Five values can be accessed:

  • position.coords.latitude
  • position.coords.longitude
  • position.coords.accuracy
  • position.coords.altitude
  • position.coords.altitudeAccuracy

More information at https://developer.mozilla.org/en-US/docs/Web/API/Position/.

Example: 

// Set the value of F_SingleLine1 to the current location
var highAccuracy = true;
var myCallbackFunction = function (position) {
  if (position !== null) {
    BO.F_SingleLine1.setValue(position.coords.latitude+", "+position.coords.longitude);
  } else {
    alert("Location request failed");
  }
};
app.getLocation(myCallbackFunction,highAccuracy);

getProductBaseURL

Returns the host and context of the Leap server.

Syntax 

app.getProductBaseURL()

Example: 

var url = app.getProductBaseURL();

getRecordURL

Returns the URL for navigating directly to the record.

Syntax 

app.getRecordURL(recordUid, formId, appUid)

Parameters

Parameter Description
recordUid The submitted record uid.
formId Optional. The form id, if not specified the current form id is used.
appUid Optional. The app uid, if not specified the current app uid is used.

Example: 

var url1 = app.getRecordURL('d1f6eb71-9483-479c-8d47-dd30bd7e9de9');
var url2 = app.getRecordURL('d1f6eb71-9483-479c-8d47-dd30bd7e9de9', form.getId());
var url3 = app.getRecordURL('d1f6eb71-9483-479c-8d47-dd30bd7e9de9', form.getId(), app.getUID());

getSharedData

Returns a JavaScript™ object that can be easily accessed from all custom JavaScript code on the form, and is the suggested location to share data, or create reusable

Syntax 

functions.app.getSharedData()

Example: 

// Create a variable
app.getSharedData().titleToShow = 'Welcome Form';

// Create a function
app.getSharedData().addTwoValues = function(v1, v2)
{
  return v1 + v2;
};

// Referencing the variable
BO.F_SingleLine.setValue(app.getSharedData().titleToShow);

// Referencing the function
BO.F_Number.setValue(app.getSharedData().addTwoValues(5, 5));

getStyleBaseURL

Returns the relative URL to the current browser page where all CSS style files that are uploaded into the application at design time are stored. All css files are saved as anonymous resources that can be viewed by anyone.

An example url is ../../../../../anon/1/content/9.3.6.33/97eeb588-2fff-49a7-89c1-5000885dafb4/1421171344944-2/desktop/en/en/en/desktop/styles/

Syntax 

app.getStyleBaseURL()

Example

This example demonstrates how to create a link item in a form that refers to a file included in the Leap application.

  1. Attach a CSS file to your Leap application. Go to Settings...Files and click the 'Add' button.
  2. Add a Link item to the form
  3. In the onShow event of the Link item add: 
    item.setLinkValue(app.getFileBaseURL() + "sampleAttachedCSSFile");

getSuppressWarning

Gets the current set value for suppressing the warning. See setSuppressWarning for information.

Syntax 

app.getSuppressWarning()

Example: 

var suppressWarning = app.getSuppressWarning();
if(suppressWarning === false)
  app.setSuppressWarning(true);

getUID

The UID of the application

Syntax 

app.getUID();

Example: 

// Can be stored in a field
BO.F_AppUid.setValue(app.getUID());

// Can be used to create a link to another form.
page.F_StaticWebLink.setLinkValue(BO.F_ServerURL.getValue() + 
  '/apps/secure/1/app/' + app.getUID() + 
  '/launch/index.html?form=F_Form2');

getUrlParameter

Looks up a single URL query parameter. If the parameter does not exist then 'undefined' is returned. If the url parameter is repeated in the URL then all the values will be returned separated by a comma.

app.getUrlParameter(parm)

Parameters

Parameter Description
parm The name of parameter to retrieve from the url.

Example:

  1. Trigger condition if specific url parameter is passed 

    var param = app.getUrlParameter('debug')
if (param === 'true')
   alert('Shown only when debug param is present');

  2. Set url parameter values into fields on the form 

    var cityParam = app.getUrlParameter('city')

if (typeof cityParam !== 'undefined')
   BO.F_City.setValue(cityParam);

Given the URL 'http://myLeapServer.com/apps/secure/org/app/df102a80-fb5d-450b-8be2-9d3fde5f9b3d/launch/index.html?form=F_Form1&city=Atlantis', 'Atlantis' would be placed into the field.

Given the URL 'http://myLeapServer.com/apps/secure/org/app/df102a80-fb5d-450b-8be2-9d3fde5f9b3d/launch/index.html?form=F_Form1&city=Atlantis&city=Rome', 'Atlantis,Rome' would be placed into the field.

getUrlParameters

Returns an object with all URL parameters.

Syntax 

app.getUrlParameters()

Example: 

var params = app.getUrlParameters();
if(params.CustomWarning)
     alert(params.CustomWarning);

getViewDataURL

Returns the URL for navigating directly to the View Data page.

Syntax 

app.getViewDataURL(appUid)

Parameters

Parameter Description
appUid The uid of the app, if not specified the current app will be used.

Example: 

var url = app.getViewDataURL();
var url = app.getViewDataURL(app.getUID());

isCurrentUserInRole

Returns true if the current user is a member of the provided role, otherwise false.

Note: The function does not validate the role with the provided roleName, therefore if the role does not exist false is returned.

Syntax 

app.isCurrentUserInRole (roleName)

Parameters

Parameter Description
roleName The name of the role to inspect if the current user is a member.

Example: 

if (!app.isCurrentUserInRole("Manager")) {
  page.F_Instructions.setVisible(false);
}

isSingleFormView

Returns true if the form is shown by itself in the browser and false if it is shown in view data.

Syntax 

app.isSingleFormView()

Example 

if (app.isSingleFormView())
{
  // do something
}

openApp

Opens the home page of an application. The current app is used if you do not supply an app id. If newTab is true, the app is presented in a new browser tab. The default behavior is for the application to be opened in a new tab.

Syntax 

app.openApp(appUid, newTab)

Parameters

Parameter Description
appPageId The title to display in the dialog title bar.
appUid The message text to display.
newTab Optional. Can be one of "info", "success", "warn", or "error" and results in appropriate icon being displayed. If type is absent or not one of these values, then no icon will be displayed.

Example: 

app.openApp('d1f6eb71-9483-479c-8d47-dd30bd7e9de9');
app.openApp ('d1f6eb71-9483-479c-8d47-dd30bd7e9de9', true);
app.openApp (app.getUID(), false);

openAppPage

Opens the app page of an application that matches the provided appPageid.

Syntax 

app.openAppPage(appPageId, appUid, newTab)

Parameters

Parameter Description
appPageId The id of the app page.
appUid Optional. The app uid, if not specified the current app uid is used.
newTab Optional. True or False. If true, the app page will be opened in a new browser tab. Default is True.

Example: 

app.openAppPage('AP_Page1');
app.openAppPage ('AP_Page1', true);
app.openAppPage ('AP_Page1', 'd1f6eb71-9483-479c-8d47-dd30bd7e9de9', false);

openForm

Opens the form of an application that matches the provided formId.

syntax 

app.openForm(formId, appUid, newTab)

Parameters

Parameter Description
formId The id of the form.
appUid Optional. The app uid, if not specified the current app uid is used.
newTab Optional. True or False. If true, the form will be opened in a new browser tab. Default is True.

Example: 

app.openForm('F_Form1');
app.openForm('F_Form1', true);
app.openForm ('F_Form1', false);

openRecord

Opens the record of a form that matches the provided recordId and formId.

Syntax 

openRecord(recordUid, formId, appUid, newTab)

Parameters

Parameter Description
recordUid The submitted record uid.
formId Optional. The form id, if not specified the current form id is used.
appUid Optional. The app uid, if not specified the current app uid is used.
newTab Optional. True or False. If True, the record will be opened in a new browser tab. Default is True.

Example: 

// open in new tab, only supply the record id
app.openRecord('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx');

// open in a new tab, specify record uid and form id
app.openRecord('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', 'F_Form2');

// open form in a new tab, specify the record uid and app uid
app.openRecord('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', 'yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy', true);

// open form in same tab, specify record uid, form id and app uid
app.openRecord('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', 'F_Form2', 'zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz', false);

setSuppressWarning

If a user interacts with a form, or JavaScript, they are prompted with a warning message whenever the current browser page tries to navigate to a different URL. This function allows the suppression of that warning. When set to true the message is suppressed until it is set to false again.

Syntax 

app.setSuppressWarning (pSuppress)

Parameters

Parameter Description
pSuppress True or False. When true, message is suppressed.

Example: 

// Can be used at any scope, for example in the application onStart, form onLoad, onItemChange, etc.
app.setSuppressWarning(true);

showMessage

Allow usage of a built-in dialog for end-user messages.

Syntax 

app.showMessage(title, message, type, subtitle)

Parameters

Parameter Description
title The title to display in the dialog title bar.
message The message text to display.
type Optional. Can be one of "info", "success", "warn", or "error" and results in appropriate icon being displayed. If type is absent or not one of these values, then no icon will be displayed.
subtitle Optional. Heading text for the message.

Example

if (BO.F_BookingDate.getValue() > BO.F_EventDate.getValue())
{
  app.showMessage (
  "Error found in data",
  "The booking date cannot be after the event.",
  "error",
  "Please change the booking or event date, then re-submit."
  );
}

Parent topic: Interface objects