Encompass Web Input Form Builder Developer’s Guidehelp.elliemae.com/.../18.4/EncompassWebInputFormBuilderDevelope… · Welcome to the Encompass Web Input Form Builder Developer’s

Encompass Web Input Form BuilderDeveloper’s Guide

For use with Encompass Loan Officer Connect

Last Revised On 11/15/2018

Copyright Statement© 2018 Ellie Mae, Inc. Ellie Mae®, Encompass®, AllRegs®, DataTrac®, Ellie Mae Network™, Mavent®, Millennial Tracker™, Mortgage Returns®, Prospect Manager®, Total Quality Loan®, True CRM®, TQL® and the Ellie Mae logo are trademarks of Ellie Mae, Inc. or its subsidiaries. All rights reserved. Other company and product names may be trademarks or copyrights of their respective owners.

Encompass Web Input Form Builder Developer’s Guide

Rev. 11/15/2018

i

Table of Contents

Chapter 1: Getting Started........................................................... 1Intended Audience .................................................................. 1What is the Form Builder? ........................................................ 1How This Guide is Organized ................................................... 1System Requirements ............................................................. 2Getting Help ........................................................................... 2

User’s Guide .................................................................. 2Developer’s Guide .......................................................... 2Online Help .................................................................... 2Guided Walk-Thrus ......................................................... 2

Logging In to the Form Builder .................................................. 2Asset Management ................................................................. 3Custom Input Forms ................................................................ 3Form Builder Components ....................................................... 3

The Elements ................................................................ 3The Form Workspace ..................................................... 3The Properties Panel ...................................................... 3

Chapter 2: Form Builder Code Basics...................................... 4Adding Code with the Code Editor ............................................ 4Adding External JavaScript Files .............................................. 5JavaScript File Sharing Best Practices ...................................... 5

Chapter 3: Creating Custom Event Handlers ......................... 6Types of Events ...................................................................... 6Ellie Mae – Secure Scripting Framework ................................... 7

Chapter 4: Object and Event Reference................................... 8Accessing Scripting Objects in a Guest ..................................... 8Invoking Scripting Object Functions .......................................... 8

Loan Object Methods ...................................................... 8Form Object ................................................................... 9

Supported Events for Field Elements ........................................ 9Event Handler Examples ....................................................... 10

Change Event .............................................................. 10

Click Event ................................................................... 11FocusIn Event .............................................................. 12

................................................................................... 12FocusOut Event ............................................................ 13Load Event ................................................................... 14Unload Event ............................................................... 15

Custom Form Element Functions Supported ............................ 16

Chapter 5: Advanced Topics ..................................................... 17Browser Compatibility and Transpilation ................................... 17

Asynchronous Programming Model ................................ 17Elli-CLI Command Line Tool for Transpiling JavaScript ...... 18

Debugging via Browser Tools .................................................. 18Invoking REST APIs .............................................................. 18

Index ................................................................................................ 20

Chapter 1

Getting StartedWelcome to the Encompass Web Input Form Builder Developer’s Guide. This guide contains information you need to understand the Web Input Form Builder environment and quickly begin to create and add JavaScript code to your custom input forms to meet your company’s requirements.

Important! The new Web Input Form Builder being introduced with this release does not replace the Encompass Input Form Builder that is provided with Encompass. Please review these important factors to consider:

• The Web Input Form Builder is a brand new feature for use with Encompass LOConnect only. (Future releases will enable you to use the Web Input FormBuilder with additional Connect products.)

• You must still use the Encompass Input Form Builder to create forms within yourcurrent Encompass system. (The new Web Input Form Builder is not compatiblewith Encompass.)

• Forms created using the new Web Input Form Builder will only be accessible inEncompass LO Connect.

• Forms created in the Encompass Input Form Builder cannot be imported orcopied over into the new Web Input Form Builder. Nor can new forms created inthe Web Input Form Builder be imported or copied over into the EncompassInput Form Builder for use with Encompass.

If you have additional questions about the Web Input Form Builder, please contact your Ellie Mae account manager.

NOTE: For the purposes of this guide, from this point on, the Encompass Web Input Form Builder will be referred to as Form Builder.

Intended AudienceThis guide is intended for experienced developers responsible for customizing Encompass Loan Officer (LO) Connect input forms. A knowledge and familiarity with coding in JavaScript is recommended.

What is the Form Builder?The Form Builder allows you to design and create new input forms.

With the Form Builder you can:

• Create forms to meet your company’s specific requirements.• Create new input forms for use in Encompass LO Connect and the Connect

family of products.*• Build forms using different elements, including text boxes, dropdown lists,

check boxes, images, hyperlinks, and responsive form layouts.• Build forms compatible for use on multiple devices, including desktop, tablet,

and mobile.• Add custom forms to your Encompass LO Connect forms list.*The ability to copy and modify standard Encompass forms like the 1003 and RegZ-LE willbe available in a future Form Builder release

How This Guide is Organized• This chapter provides an overview of the Form Builder and discusses the

resources available if you need assistance with JavaScript.• Chapter 2, “Form Builder Code Basics” on page 4 describes how to add code to

the Form Builder and the best practices in sharing JavaScript files.• Chapter 3, “Creating Custom Event Handlers” on page 6 describes how to

create custom events, and the types of events you can create.• Chapter 4, “Object and Event Reference” on page 8 provides object references

and examples of use cases and sample code for event handlers.• Chapter 5, “Advanced Topics” on page 17 explores advanced JavaScript topics.

Chapter 1: Getting Started 1

System RequirementsBefore using the Form Builder, verify the following system requirements:

• Recommended monitor resolution: 1680x1050 • Supported browsers:

• Chrome (desktop and mobile)• Safari (desktop and mobile)• Edge (desktop only)• IE (desktop only)• Firefox (desktop only)

Getting HelpIf you need assistance using the Form Builder, several resources are available.

User’s GuideYou can download the Encompass Web Input Form Builder User's Guide as a .pdf file from the Encompass LO Connect Guides & Documents page:

http://help.elliemae.com/documentation/lo-connect/Content/lo-connect/library/documents.htm

Developer’s GuideYou can download the Encompass Web Input Form Builder Developer’s Guide as a .pdf file from the Encompass LO Connect Guides & Documents page:

http://help.elliemae.com/documentation/lo-connect/Content/lo-connect/library/documents.htm

Online HelpThe online help contains complete documentation for all Form Builder features.

To Access the Online Help:• Click the Help button (question mark) located on the right side of the Encompass LO Connect site.

Guided Walk-ThrusWalk-thrus are step-by-step guides featuring on-screen instructions that help you to complete a task.

To Access a Walk-Thru:• Select the Need Help? widget located on the right side of the Form Builder.

Logging In to the Form BuilderThe Form Builder is accessed through the Encompass Web Admin Portal. When you log in, you will enter your Encompass LO Connect administrator credentials.

To Access the Encompass Web Admin Portal:1 Using your web browser, navigate to Encompass LO Connect.

• The URL for Encompass LO Connect will be provided to you as part of your initial set up and kick off of Encompass LO Connect.

2 On the login window, enter your assigned Encompass LO Connect administrator credentials in the Client ID, User ID, and Password fields.

3 Select Log In.The Encompass Web Admin Portal opens.

A Note About Two Factor AuthenticationAs an added security measure, Encompass LO Connect utilizes a process known as two-factor authentication. When logging into Encompass LO Connect you are prompted to install the Ping Identity app from the Apple App Store or the Google Play store. Once you pair a device with PingID, Encompass will authenticate your device automatically and you can then proceed to the next step to access the Form Builder.

For instructions to pair your device with PingID, refer to the Logging Into and Out of Encompass LO Connect help topic.


Asset ManagementThe Asset Management is where you can access a central repository of uploaded JavaScript files. These asset repositories are shared, meaning any change made to a file is universal and will impact the file across all products in which it appears. Changes made to file names could result in errors in input forms.

NOTE: Currently, files uploaded to the Asset Management cannot be deleted. This will be addressed in a future release.

To Access the Asset Management:• Log in to the Form Builder and select Asset Management., and then select

JavaScript Files.

Custom Input FormsThe Custom Input Forms page is where you can access a list of the forms that have been created in Form Builder and ways to manage them. You can create, refresh, import, export, and delete any custom forms. If this is your first time logging in, no forms will be listed here.

To Access Custom Input Forms:• Log in to the Form Builder and select Input Forms, and then select Custom

Forms.

Form Builder ComponentsThere are three main components on the Form Builder interface: elements, the form workspace, and the properties panel.

To Access the Form Builder:• Log in to the Form Builder and select Input Forms, and then select Custom

Forms.• Select an existing form or select New to start a new form.

The ElementsAll of the elements used to build a form appear at the top of the Form Builder workspace. Add an element to a form by using a simple drag- and-drop operation.

The Form WorkspaceThe Form Workspace is in the center of the Form Builder interface. Add elements to the workspace and then arrange them on the form.

NOTE: You can have only one form open at a time within the same browser.

The Form Workspace also provides a toolbar that enables you to manage the elements on the form.

The Properties PanelThe Properties panel displays on the right side of the Form Builder workspace. When you add an element to the workspace, you define its appearance and behavior by setting values in the Properties panel. These values are automatically saved. The available properties are based on the selected elements.

The Properties panel is also where you assign event handlers to elements. Events are triggered when a user performs an action on a form. For example, the user can click a button to trigger a click event or click a text box to trigger a change event. For information on how to create a new custom event handler, refer Chapter 3, “Creating Custom Event Handlers” on page 6.

To View an Element's Properties:• Click to select an element in the workspace. The Properties panel automatically

displays the element’s properties.

To View the Form Properties:• Click outside the workspace so that no elements are selected. The Properties

panel automatically displays the form’s properties.


Chapter 2

Form Builder Code BasicsThere are two ways an administrator can add JavaScript code to the Form Builder:

• Use the Code Editor to add code from directly within the Form Builder.• Upload an external JavaScript file and link it to the form.

Adding Code with the Code EditorAdministrators can use the Code Editor to create JavaScript code and save it as a JavaScript file from directly within the Form Builder. These newly created JavaScript files are automatically linked to the current form.

To Open the Code Editor1 Log in to the Form Builder and select Input Forms, and then select Custom

Forms.2 Select an existing form, or select New to start a new form.3 On the Form Workspace toolbar, select the Code Editor icon (</>) to open the

JavaScript Code Editor.

There are six components to the Code Editor:

• File Name: Select a JavaScript file from the dropdown to link to the form.When the JavaScript Code Editor is first accessed, it opens a blank JavaScriptfile that is automatically linked to the form. A default file name is assigned to the JavaScript file, which means it cannot be modified. If the file name already exists, you will be prompted to rename the file before saving.

The file name adheres to the following format: <form name>_default.js. For example, if the name of your form is Borrower Summary, the JavaScript file will be named Borrower Summary_default.js.

• Find & Replace: Select to expand the Find & Replace section, then search forcode text, or search and replace code text.

• Content Editor: Create or insert code in this section.• Cancel: Select to cancel any edits and exit the Code Editor without saving.• Save: Select to save the JavaScript file and any edits made to it.

The JavaScript file is saved to the central JavaScript repository, which isaccessed through Asset Management.

NOTE: Libraries in the Asset Management are shared asset repositories. Any edits made to files in the Asset Management section will impact the file in all products in which it appears. Changes made to file names could result in errors in input forms.

The JavaScript file is automatically linked to the current form. Linked JavaScript files can be viewed through the form properties.

NOTE: When saving a JavaScript file directly in the Code Editor, a default file name is given. If that file name already exists, you will be prompted to rename the file before saving.

Chapter 2: Form Builder Code Basics 4

To View Scripts in Form Properties:1 Click anywhere within the workspace, but do not click to select an element. 2 Click anywhere within the form workspace to display the form properties, but

do not click to select an element.3 On the Properties panel, select the Scripts tab.4 Linked displays the JavaScript files that are linked to the current form.

Adding External JavaScript FilesAdministrators can upload external JavaScript files to the JavaScript repository in the Asset Management.

To Upload a JavaScript File:1 From the Admin Settings, select Asset Management.2 Select Upload. 3 Select Browse to browse to and select the external JavaScript file, or drag and

drop the file to the file drop area.4 The file is uploaded to the JavaScript files central repository.JavaScript files stored in the central repository can be linked to one or more forms in the form builder.

To Link a JavaScript File to a Form:1 Open the desired form.2 Click anywhere within the form workspace to display the form properties, but

do not click to select an element.3 On the Properties panel, select the Scripts tab.4 Select a JavaScript file to link to the form, or press the CTRL key to select

multiple JavaScript files.NOTE: The JavaScript files listed for selection are all the files in the Asset Management’s JavaScript repository.

JavaScript File Sharing Best PracticesThe following are the recommended best practices for sharing JavaScript files across multiple forms, and for editing existing JavaScript files linked to a form.

Sharing JavaScript Files Across Multiple Forms• JavaScript files should contain generic code across forms.• When editing JavaScript files, keep in mind that these files exist in a shared

asset repository. Any edits made to these files will impact the file in all products in which it appears. Please apply caution.

• To avoid unintended consequences to other forms when editing JavaScript files, create a unique JavaScript file for each form.

Editing Existing Linked JavaScript FilesIt is recommended that these steps are followed when making changes, especially if on a large scale, to an existing JavaScript file.

1 Before editing the JavaScript file, disable the form.2 Make your edits.3 Test the code.4 Enable the form.

Chapter 2: Form Builder Code Basics 5

Chapter 3

Creating Custom Event HandlersFrom the time a form is first displayed to the user, to the time the user navigates to another form or closes the loan, the system provides opportunities, called “events,” to execute custom code. For example, an event occurs whenever the user clicks a button element or modifies the contents of a text box. By adding your own custom functionality to these events, you can add significant functionality to your form beyond the simple fill-in-the-blanks default behavior.

Within the Form Builder, different elements provide different events. The button element provides a click event while a text box element provides a change event.

In order to add your custom code to any event you must author an “event handler.” An event handler is the code that the system will execute at the time the associated event occurs. For example, you can create an event handler for a button's click event that instructs the system to copy the value of one loan field into another.

Custom code for event handlers are written in JavaScript programming language.

To create a new custom event handler, you should first know the element on which the event will occur.

To Write Code To Trigger an Event:1 Select the element for the desired event in the workspace.2 On the Properties window, select the Events tab.3 Select the Code Editor icon (</>) next to the event dropdown to add new code

or edit existing JavaScript code.4 When finished, select Save, and then select Close.NOTE: When saving event handler code directly from the Code Editor, a default file name is given if no files are linked to the form. If a file name already exists, you will be prompted to rename the JavaScript file before saving.

Types of EventsYou can create event handlers for the following events using the Editor:

• Change Event - Triggered whenever data within the element has changed. Itgenerally occurs when the user leaves the field after making a modification.When this event is called, the data in the element has already been committedto the underlying loan.

• Click Event - Triggered when the user clicks a element, typically a button.• FocusIn Event - Fired on a element any time the element gains the input focus.

This can happen by virtue of the user clicking the element or by tabbing to theelement.

• FocusOut - Triggered any time the input focus leaves the field. The focusleaves a field when the user clicks another field or tabs out of the field.

• Load Event - Fires on the Form object when all elements on the form arepopulated and the form is ready for user input.

• Unload Event - Raised to notify the form that it is about to be closed. The usermay have elected to open a new input form or may be closing the loan. Thisevent cannot be used to prevent the form from being unloaded and you shouldavoid using functionality that displays a user interface.

Chapter 3: Creating Custom Event Handlers 6

Ellie Mae – Secure Scripting FrameworkCustom Input Forms allows for injection of custom functionality by using Ellie Mae technology framework known as the Secure Scripting Framework (SSF). The SSF isolates the third-party's customizations away from the host application (e.g., LO Connect) by loading the custom HTML/JavaScript into a "sandboxed" container. When custom code/UI is loaded in a sandbox, we refer to that as a guest of the application, and the terms host and guest will be used in this document.

Besides isolation, the SSF provides a communication channel for all interactions between the host and its guest. To enable communication, the host application publishes a set of scripting objects that can be invoked by JavaScript within the guest:

• Functions: Each scripting object provides a set of functions that can be invoked by the guest to retrieve or modify the state or behavior of the host application. For example, a host may expose a function to retrieve the data of the loan currently being edited by the logged-in user.

• Scripting Object Function Example:

EM—SSF also limits Custom Code access to the rest of the application in the sandboxed environment. When running inside the SSF sandbox, the guest script/application cannot:

• Access or use sessionStorage or applicationStorage.• Access or use cookies.• Directly access any DOM elements or JavaScript objects from the parent

window (indirect access may be gained via Scripting Objects published by the host application).

• Access the Session ID/Access Token from the host application.

var loan = await elli.script.getObject("loan");

loan.setFields({ "1109": 200000 });

Chapter 3: Creating Custom Event Handlers 7

Chapter 4

Object and Event ReferenceThis chapter contains object references and examples of use cases and sample code for event handlers.

Accessing Scripting Objects in a GuestIn order for a guest application or script to interact with a scripting object provided by the host, it must first retrieve a reference to the object through the SSF scripting utilities:

Each Scripting Object available to the guest has a unique Object ID: a string value that uniquely identifies the object being retrieved based on the current context. For example, in the case above, the identifier "loan" is used to retrieve the current Loan object from the host application. Note that, as with all Scripting Object calls, the elli.script.getObject() call is asynchronous and requires that we “await” the result (or use the Promise.then() function).

The elli.script object is the core, global scripting object available to all SSF guest scripts.

Returns the Scripting Object with the specified Object ID from the host application

The next sections go through the details of how to invoke the functions of a Scripting Object retrieved thru the getObject() function.

Invoking Scripting Object FunctionsOnce you have a reference to a Scripting Object via the elli.script.getObject() call, you are ready to invoke functions on the object to interact with it. Functions may be used to retrieve or modify the state of the Scripting Object, depending on the use case. All function calls on Scripting Objects are asynchronous; thus, you must either "await" the result of the function call or use the Promise.then() function to invoke a callback when the function is completed.

Scripting Object Function Call Example

The SSF has one further optimization that can be leveraged to simplify your code: the framework will automatically await on any Promise-valued parameter to a function exposed by a ScriptingObject. As a result, the function call:

can be shortened to:


elli.script.getObject("<objectId>")

async function setTextboxColor(textBox) {

// Sync the text color with the button color

var button = await elli.script.getObject("button1");

textBox.fontColor(await button.color());

}

textBox.fontColor(await button.color());

textBox.fontColor(button.color());

Chapter 4: Object and Event Reference 8

Loan Object MethodsThe Loan object provides methods for interacting with an open loan in the application's editor screen(s).

Custom Form elements are used to display data from the underlying loan file, and for the user to input or modify loan data.

Form ObjectThe Form Builder supports the following two events on the form object:

• Load - This event fires on the form object when all elements on the form are populated, and the form is ready for user input.

• Unload - This event is raised to notify the form that it is about to be closed, e.g. the user could be opening a new input form, or could be closing the loan itself.

Supported Events for Field ElementsThe following field elements and its supported events are available in the Form Builder:

Method Description

all() Returns the entire Loan object in the v3 Loan Object model.

getField("<fieldId>") Returns the value of a single field using its field ID.

setFields(<fieldMap>) Sets the values of one or more fields on the Loan. The <fieldMap> is a JSON object with Field IDs as the object's proeprties, e.g.{

"1109": 400000,

"1172": "FHA",

"762": "2018-03-04"

}

Elements Supported Events

Category Box N/A

Group Box N/A

Text Box • Change• FocusIn• FocusOut

Multi-line Text Box • Change• FocusIn• FocusOut

Dropdown • Change• FocusIn• FocusOut

Radio Button • Change

Button • Click

Checkbox • Change

Hyperlink • Click

Calendar • Change

Contact Button • Change• FocusIn• FocusOut

Rolodex • Change• FocusIn• FocusOut

Image • N/A


Event Handler ExamplesThe following are examples include event handler use cases, sample code, and any relevant screenshots.

Change Event• Example Use Case:

The administrator creates a form where, depending on if “Own” or “Rent” is selected on the dropdown, the “Rent Information” group box is either hidden or displayed. Selecting “Own” hides the group box and selecting “Rent” displays it.

• Sample Code (in ES5 and ES6/ES2017 formats):

ES5

function Dropdown1_OnChange(ctrl) {elli.script.getObject("Dropdown1").then(function (ctrl1) { ctrl1.value().then(function (DDvalue){ if (DDvalue === "Rent") { elli.script.getObject("GroupBox1").then(function (ctrlDP) { ctrlDP.visible(true); })//end get object function }// end ifelse if (DDvalue === "Own") { elli.script.getObject("GroupBox1").then(function (ctrlDP) { ctrlDP.visible(false); })//end get object function}//end else ifelse { elli.script.getObject("GroupBox1").then(function (ctrlDP) { ctrlDP.visible(true); })//end script object}//end else

})// end elli function

ES6/ES2017

async function Dropdown1_change(ctrl) { var loan = await elli.script.getObject("loan"); var RentOwn = await loan.getField('FR0115'); var RentGroupBox = await elli.script.getObject("GroupBox1"); var OwnGroupBox = await elli.script.getObject("GroupBox2");

if(RentOwn == "Rent") { RentGroupBox.visible(true); OwnGroupBox.visible(false); } else if(RentOwn == "Own") { RentGroupBox.visible(false); OwnGroupBox.visible(true); }

}


• Screenshots:The administrator’s view of the form

The user’s view of the form when “Rent” is selected on the dropdown

The user’s view of the form when “Own” is selected on the dropdown

Click Event• Example Use Case:

The admin creates a custom form where he would like to use JavaScript logic on a “Copy from Borrower” button to copy over some borrower specific fields from Borrower group box to Co-borrower specific group box elements.

• Sample Code (in ES6/ES2017 format):

ES6/ES2017

async function Dropdown1_change(ctrl) { var loan = await elli.script.getObject("loan"); var RentOwn = await loan.getField('FR0115'); var RentGroupBox = await elli.script.getObject("GroupBox1"); var OwnGroupBox = await elli.script.getObject("GroupBox2");

if(RentOwn == "Rent") { RentGroupBox.visible(true); OwnGroupBox.visible(false); } else if(RentOwn == "Own") { RentGroupBox.visible(false); OwnGroupBox.visible(true); }

}


FocusIn Event• Example Use Case:

The administrator creates a form where, if both the “FHA” radio button is selected and the “Loan Amount” text box is “focused in” (the user has selected inside the text box), the “Down Payment” text box automatically populates with a value of “3.500.”



The user’s view of the form

ES5

function TextBox2_focusin(ctrl) {

elli.script.getObject('loan').then(function(loanObj) {

loanObj.getField('1172').then(function (value1) {

if (value1 === 'FHA'){

return elli.script.getObject('loan').then(function(loanObj) { loanObj.setFields({ '1771': '3.5'}) });

}

})

})

}

ES6/ES2017

async function LoanAmount_focusin(ctrl)

{


var LoanType = await loan.getField('1172');

if (LoanType === 'FHA')

{

loan.setFields({ '1771': '3.5' });

}

}


FocusOut Event• Example Use Case:

The administrator creates a form where, if both the “FHA” radio button is not selected and the “Loan Amount” text box is “focused out” (the user has not selected inside the text box), the “Down Payment” text box automatically populates with a value of “0.000.”




ES5

function TextBox1_focusout(ctrl) {


loanObj.getField('1172').then(function (value1) {

if (value1 !== 'FHA') {

return elli.script.getObject('loan').then(function(loanObj) { loanObj.setFields({ '1771': '0'}) });

}

})

})

}

ES6/ES2017

async function LoanAmount_focusout(ctrl)

{



if (LoanType != 'FHA')

{

loan.setFields({ '1771': '0' });

}

}


Load Event• Example Use Case:

The administrator creates a form with three group boxes: “VA Data,” “Conventional Data,” and “FHA Data.” Upon loading the form, the group boxes will be hidden or displayed depending on the value in the “Loan Type” text box. If the value in the “Loan Type” text box is “VA,” then the “Conventional Data” and “FHA Data” group boxes are hidden and the “VA Data” group box is displayed.

Sample Code:

ES5

function form_load(ctrl) {


loanObj.getField('1172').then(function (value) {

if (value === 'FHA') {

elli.script.getObject("GroupBox1").then(function (gb) { gb.visible(true); })

elli.script.getObject("GroupBox2").then(function (gb) { gb.visible(false); });


}// end if

else if (value === 'VA') {

elli.script.getObject("GroupBox1").then(function (gb) { gb.visible(false); })

elli.script.getObject("GroupBox2").then(function (gb) { gb.visible(true); });


}// end else if

})// loanObj

}) //elli

}//end function

ES6/ES2017

npm install --global @elliemae/elli-cli

async function form_load(ctrl)

{



var VAGroupBox = await elli.script.getObject("GroupBox1");

var ConvGroupBox = await elli.script.getObject("GroupBox2");

var FHAGroupBox = await elli.script.getObject("GroupBox3");

if(LoanType === "VA")

{

VAGroupBox.visible(true);

ConvGroupBox.visible(false);

FHAGroupBox.visible(false);

}

else if(LoanType === "Conventional")

{

VAGroupBox.visible(false);

ConvGroupBox.visible(true);

FHAGroupBox.visible(false);

}

else if(LoanType === "FHA")

{

VAGroupBox.visible(false);

ConvGroupBox.visible(false);

FHAGroupBox.visible(true);

}

}




Unload Event• Example Use Case:

The adminstrator creates a form where, upon closing the form, the text boxes “field ID 4000” and “field ID 52” are populated with the values “Test Borrower” and “Married,” respectively.

• Sample Code:

function form_unload() {return elli.script.getObject('loan').then(function(loanObj) { loanObj.setFields({'4000':'TestBorrower', '52':'Married'}) });

}


Custom Form Element Functions Supported

Element API Set Value Get Value Comment

All colorvisible

elli.script.getObject("GroupBox2").then(function (gb) {

gb.visible(false);

});

elli.script.getObject("GroupBox2").then(function (gb) {

if(gb.visible()) {

// Post processing when GroupBox1 is visible

};

})

All elements with data binding enabled

value elli.script.getObject("TextBox1").then(function (tb) {

tb.value(‘First Name’);

});

elli.script.getObject("TextBox1").then(function (tb) {

if(tb.value() == ‘First Name’){

// Post processing when TextBox1 is set to FirstName

};

})

Will fire change event if value is changed

Text Box text Same as value Same as value

Label text Same as value Same as value

Label fontColor elli.script.getObject("Label1").then(function (lb) {

if(lb.fontColor() == colorVal) {

};

});

elli.script.getObject("Label1").then(function (lb) {

lb.fontColor(colorVal);

});

Check BoxRadio Button

checked elli.script.getObject("CheckBox1").then(function (cb) {

cb.checked(false)

});

elli.script.getObject("CheckBox1").then(function (cb) {

if(cb.checked() == true) {

};

});

Check Box GroupRadio Button Group

value elli.script.getObject("CheckBox1").then(function (cb) {

cb.value(‘Conventional’);

});

elli.script.getObject("CheckBox1").then(function (cb) {

if(cb.value() == ‘Conventional’) {

};

});


Chapter 5

Advanced Topics

Browser Compatibility and TranspilationThe SSF is compatible with all browsers/versions supported by the Encompass web applications, which is made possible by the use of a polyfill. A polyfill is a JavaScript library that provides support for modern JavaScript objects (e.g., the Promise object) in legacy web browsers, such as Internet Explorer. The most popular polyfill is provided as part of the Babel open source project, and it is with this polyfill that the SSF is tested.

This chapter section will show you how to automatically include the Babel Polyfill in your project to provide effortless compatibility, or you can substitute this with a different polyfill library.

NOTE: Ellie Mae cannot ensure compatibility between SSF and any non-Babel polyfill library.

When writing custom JavaScript that runs within an SSF guest, the author is responsible for any browser compatibility issues that may be relevant to their use case. In particular, your JavaScript must conform to the ES5 specification in order to support all browsers under which it may run. The code examples in the next section make liberal use of ES6 and ES2017 syntax, which are not supported in Internet Explorer. To compensate, Ellie Mae provides a command-line tool, the Elli-CLI, that allows for transpilation of code written using ES6/2017 into ES5-compatible JavaScript. More information on this tool is provided in the Elli-CLI topic later in this chapter.

The following links contain a complete list of browser compatibility for:

• ES5 - ECMAScript 5• ES6 - ES6 classesSome browsers do not support all of ES6 functionality, which is why it is best to transpile your code to ES5 compatibility. ES5 is supported without any extra required efforts; ES6 support requires transpilation. To handle transpilation, use the Elli-CLI tool provided later in this chapter.

NOTE: Before using our transpilation tool, you must have node.js installed on your computer. NPM, the package manager, can then be used.

Asynchronous Programming ModelAll interactions your custom code performs using functions or events published by the Scripting Objects are performed asynchronously. The JavaScript asynchronous programming model is based on the notion of a Promise: an object that represents the eventual completion of an asynchronous task or function invocation. All functions exposed by Scripting Objects return a Promise to the caller, which can then be used to register a callback that will be invoked when the function has been completed.

For example, the following code reads the value of a TextBox control from an Custom Input Form by first retrieving a reference to the control (via elli.script.getObject()) and then invoking the TextBox's value() function. Note that both functions are async and require the use of the Promise.then() function to achieve the desired behavior:

Async Programming Using ES5

function displayTextValue() {

// The call to getObject() returns a Promise that,

// when completed, returns a

// reference to the TextBox control

elli.script.getObject("TextBox1").then(function(textBox) {

// Once the TextBox reference is received,

// we call the value() function.

// This returns a new Promise that,

// when completed, returns the value inside the box

textBox.value().then(function(val) {

alert('The textbox contains the value: ' + val);

});

});

}

Chapter 5: Advanced Topics 17

https://caniuse.com/#search=es6

The prior code example is written using ES5 syntax which, although compatible with all supported browsers, can be difficult to write, read, and debug. Alternatively, the same logic can be written using ES6/ES2017 syntax is a much more compact and readable way:

By using the "async" and "await" keywords introduced in ES2017, the code is greatly simplified and follows a more conventional flow. However, because ES2017 language features are not supported in Internet Explorer, this code will need to be transpiled to ES5-compatible syntax prior to being uploaded into the Ellie Mae Asset Library. Transpilation is performed using the Elli-CLI tool, which is described in the next section. The result of running the tool is a new JavaScript file which can be used with your Custom Input Form and supports legacy browsers.

Elli-CLI Command Line Tool for Transpiling JavaScriptThe Elli-CLI is an NPM-based command-line tool that automatically includes and configures the Babel transpiler in a manner compatible with Ellie Mae Secure Scripting (EM-SSF). You can install the CLI either globally or as a "dev dependency" in the project that will require it:

Once installed, developers can transpile their ES6/ES2017 JavaScript files by invoking the elli command at the command line:

For each script on the command line, a new, transpiled script will be produced in the same folder as the source file. The new files will have the name “<source>-es5.js.” These transpiled scripts can then be uploaded to the Asset Management’s JavaScript repository and linked to input forms, or exposed as Plugins.

NOTE: The Ellie Mae system will not transpile code automatically. Code must be transpiled before being submitted to the server.

Debugging via Browser ToolsThe following online tutorial is available for understanding how to use Chrome’s DevTools:

• Get Started with Debugging JavaScript in Chrome DevTools

Invoking REST APIsNOTE: Currently, only a non-Ellie Mae REST API can be invoked. The feature for invoking an Ellie Mae based REST API will be made available in a future release.

The simplest way to make API calls is to import a library, such as jQuery, and use the Ajax utilities. To make API calls without loading an external library, you can use the native XMLHttpRequest.

The following online resource is available for learning how to make API calls:

• Making API Calls with JavaScript - An online lesson using ES6 terminology

Async Programming Using ES6/ES2017

// Note that the function is prefixed by the "async" keyword

async function displayTextValue() {

// Retrieve the TextBox control by awaiting the result of

// the getObject() call

let textBox = await elli.script.getObject("TextBox1");

// Retrieve the value of the control using another await

let val = await textBox.value();

alert('The textbox contains the value: ' + val);

}

Global Install

npm install --global @elliemae/elli-cli

Local Install

npm install --save-dev @elliemae/elli-cli

Elli Command

elli build <script1.js> <script2.js>


https://github.com/getify/You-Dont-Know-JS


https://developers.google.com/web/tools/chrome-devtools/javascript/







https://eloquentjavascript.net/

https://eloquentjavascript.net/



https://developers.google.com/web/tools/chrome-devtools/javascript/

https://www.learnhowtoprogram.com/javascript/asynchrony-and-apis-in-javascript/making-api-calls-with-javascript

https://www.learnhowtoprogram.com/javascript/asynchrony-and-apis-in-javascript/making-api-calls-with-javascript

• Sample Code:

function UserAction() {

var xhttp = new XMLHttpRequest();

xhttp.onreadystatechange = function() {

if (this.readyState == 4 && this.status == 200) {

alert(this.responseText);

}

};

xhttp.open("POST", "Your Rest URL Here", true);

xhttp.setRequestHeader("Content-type", "application/json");

xhttp.send("Your JSON Data Here");

}
