Form objects

The form object (form) provides access to a number of functions that affect the entire form.

addClasses

Adds a list of custom class names to the form for dynamic CSS styling. The classes parameter can be a single class name, multiple class names separated by spaces, or an Array of class names. If any of the given class names are invalid CSS class names, then no classes are added and false is returned.

Syntax

form.addClasses(classes)

Example

form.addClasses('emphasized error');

backwardPage

Return the form to the previous page in navigation order. If the first page is reached, then nothing happens.

Syntax

form.backwardPage()

Example

The following could be used to turn a regular button into a navigation button. In the onClick event of a button:

form.backwardPage();

connectEvent

Connects a function to an event on the form. This is useful for utility functions defined in external JavaScript™ files to hook behavior into the form dynamically. Returns a handle object that represents the connection of the function to that event name. The handle can be used to disconnect this same event using form.disconnectEvent.

Syntax

form.connectEvent(eventName, callbackFunction)

Example

If there is a F_CurrentUser field, then populate the currentUser:

var hndl = form.connectEvent('onLoad', function()
{
   var currentUserField = form.getBO().F_CurrentUser;
   if (currentUserField) {
      currentUserField.setValue(app.getCurrentUser());
   }
});

disconnectEvent

Disconnects the event handler specified by the passed-in event handle object that was returned by a form.connectEvent call. To avoid duplicate event handlers being connected, connect to events from within the application onStart or form onLoad events. If you connect to an event outside of these two events, you should explicitly disconnect from the event using this method.

Syntax

form.disconnectEvent(eventHandle)

Example

var hndl = form.connectEvent('onLoad', function()
{
   var currentUserField = form.getBO().F_CurrentUser;
   if (currentUserField) {
       currentUserField.setValue(app.getCurrentUser());
   }
   form.disconnectEvent(hndl);
});

forwardPage

Advance the form to the next page in navigation order. If the last page is reached, then nothing happens.

Syntax

form.forwardPage()

Example

The following could be used to turn a regular button into a navigation button. In the onClick event of a button:

form.forwardPage();

getApp

Returns the application object: app. Not a commonly used function, because within the form scope the app variable is also available.

Syntax

form.getApp()

getBO

Returns the object that contains the Business Object data for the entire form.

Syntax

form.getBO()

Example

This is commonly used in the application onStart, since at this scope the form variable is not defined.

var myForm = app.getForm('F_Form1');
var formBO = myForm.getBO();
formBO.F_SingleLine.setValue('setting the value using code!');

getClasses

Returns an Array of custom class names currently applied to the form.

Syntax

form.getClasses()

getCurrentPage

Gets the currently shown page. If there is no page shown, then null is returned. It is possible, though rarely desirable, to have all pages hidden.

Syntax

form.getCurrentPage()

Example

var pageShown = form.getCurrentPage();
if (pageShown === 'F_Page1')
   pageShown.F_Text.setContent('Changing the text of this text item when this page is shown.');

getId

Returns the unique ID within the application of this form. For example, 'F_Form1'.

Syntax

form.getId()

getPage

Returns the page object, page, for the page specified. Returns null if the pageId is invalid.

Syntax

form.getPage(pageId)

Parameters

Parameter	Description
pageId	The id of the page.

Example

// Get the specified page
var thePage = form.getPage('F_Page1');

// If the page exists then, navigate to that page
if(thePage !== null) 
  form.selectPage('thePage')

getServiceConfigurationIds

Returns an array of all the IDs for services mapped in this form.

Syntax

form.getServiceConfigurationIds()

Example

var serviceConfigs = form.getServiceConfigurationIds();

getPageIds

Returns an array of the page IDs for the pages in this form.

Syntax

form.getPageIds()

getServiceConfiguration

Gets the service object for a particular service ID.

Syntax

form.getServiceConfiguration(serviceId)

Parameters

Parameter	Description
serviceId	The id of the service configuration.

Example

// Lookup and execute a service from JavaScript
var service = form.getServiceConfiguration('SC_ServiceConfig');
service.callService();

getStageActions

Returns an array of all the action buttons for the current stage. This includes any hidden action buttons as well.

Syntax

form.getStageActions()

Example

// Trigger a specific action using JavaScript
var actions = form.getStageActions():
for (var i=0; i<actions.length; i++) {
  if(get(actions,i).getId() === 'S_Submit')
  {
    get(actions,i).activate();
    break;
  }
}

/*
* Hides all the stage buttons that are specified.
* 
* USAGE:
* app.getSharedData().hideStageButtons(form, ["S_Submit", "S_Submit1"]);
*/
app.getSharedData().hideStageButtons = function(theForm, btnList) {

 var actionButtons = theForm.getStageActions();
 for(var i=0; i<actionButtons.length; i++){
  for(var j=0;j<btnList.length;j++) {
    if(get(btnList, j) === get(actionButtons, i).getId())
       get(actionButtons, i).setVisible(false);
   }      
 }
}

getType

Returns a string identifying the object type. For example, 'form'.

Syntax

form.getType()

removeClasses

Removes a list of custom class names from the form for dynamic CSS styling. The classes parameter can be a single class name, multiple class names separated by spaces, or an Array of class names.

Syntax

form.removeClasses(classes)

Parameters

Parameter	Description
classes	List of CSS classnames separated by spaces, or an array of class names.

Example

form.removeClasses('emphasized error');

removePageFromNavigation

Removes the specified page from the navigation list for the form. The page navigation item no longer visits that page when next, or previous is selected, nor can you switch to that page programmatically.

Syntax

form.removePageFromNavigation(pageId)

Parameters

Parameter	Description
pageId	The id of the page.

Example

// If the check is selected, remove page 2 from the navigation
if(BO.F_Check.getValue())
  form.removePageFromNavigation('P_Page2');

restorePageNavigation

Restores a previously removed page back into the navigation list for the form.

Syntax

form.restorePageNavigation(pageId)

Parameters

Parameter	Description
pageId	The id of the page.

Example

// If the check is not selected, restore page 2 into the navigation
if(!BO.F_Check.getValue())
  form.restorePageNavigation('P_Page2');

selectPage

Switches to the specified page. If the page is removed from navigation by Stages, Rules, or JavaScript, then you cannot select it.

Syntax

form.selectPage(pageId)

Parameters

Parameter	Description
pageId	The id of the page.

Example

// Get the specified page
var thePage = form.getPage('F_Page1');

// If the page exists then navigate to that page
if (thePage !== null) 
  form.selectPage('F_Page1');

Parent topic: Interface objects