QAS Typedown Client JavaScript API for Salesforce
Table of Contents
1.Introduction .................................................................................................................................. 1
2. API libraries and dependencies ................................................................................................... 2
2.1. Libraries.............................................................................................................................. 2
2.2.
Dependencies .................................................................................................................... 2
3.Integration ................................................................................................................................... 3
3.1 Integration using the settings configured via the QAS administration interface ...................... 4
3.2. Integration with hard-coded Typedown settings for a custom Visual force page .................... 5
4. Typedown client settings ............................................................................................................. 6
QAS Typedown Client JavaScript API for Salesforce
1. Introduction
The QAS Typedown JavaScript API is designed to allow third parties to integrate the
QAS Typedown engine in custom Visualforce pages and web pages.
2. API libraries and dependencies:
1.1. Libraries:
-
system.js – contains generic functions like isNull, isFunction etc.
-
typedownClient.js – contains Typedown client logic independent of Salesforce. If
you would like to integrate Typedown with HTML pages outside of Salesforce you
should use this library if you are appropriately licensed.
-
typedownClientSFDC.js – extends typedownClient.js and contains Typedown
client logic which is specific to Salesforce. You should use this library to integrate
Typedown with Salesforce Visual force pages.
-
xd.js – this is a Salesforce specific library which facilitates cross domain
communication.
-
console.js – this is a Salesforce specific library which contains logic for making
the interactive validation work in the “Console” (i.e. the regular console, not
Service Cloud Console).
-
all_sf_without_jQuery-2.0.min.js - contains all of the above libraries and all of
the dependencies excluding jQuery. You should use either this or the
“all_sf_with_jQuery-2.0.min.js” library in production. You have to use this library if
you are already including jQuery on the page. This library excludes jQuery to
avoid including the library twice.
-
all_sf_with_jQuery-2.0.min.js - contains all of the above libraries and all of the
dependencies including jQuery. You should use either this or the
“all_sf_without_jQuery-2.0.min.js” library in production. You have to use this
library if you are not including jQuery on the page. This library contains the jQuery
library which is required for QAS Typedown to be able to work correctly.
1.2. Dependencies:
-
jQuery v 1.4 and above.
SimpleModel jQuery plugin
http://www.ericmmartin.com/projects/simplemodal/
-
Salesforce's ajax.js
Salesforce's integration.js
QAS Typedown Client JavaScript API for Salesforce
3. Integration
The API is designed to give you maximum flexibility and provides many different ways
to integrate Typedown into your Visual Force and HTML pages. On the high level the
steps for integrating Typedown are:
1. Include the necessary JavaScript libraries;
2. Set the Salesforce’s connection API Session Id;
3. Set the QAS Typedown settings indicating at least your proxy page URL;
4. Create your Typedown configuration objects which describe your input mappings,
output mappings and general Typedown settings (upper case addresses, session
key etc.);
5. Create a Typedown object and call the initialize method which will hook up the
necessary events to your HTML fields;
6. After initialization is complete hook up the “Validation status” correction logic on
before form submit or on the onclick events for your “Save” buttons. The
“Validation status” correction logic makes sure that the addresses on your HTML
page are checked to make sure that they were not modified after Typedown was
used. If they were modified after Typedown provided a valid address the validation
status for the address will become “User Preferred”;
7. Create a custom Visualforce page to act as a proxy page for cross domain
communication between Typedown and your Visualforce page;
There are two different ways of integrating Typedown into custom Visual force page
described below:
3.1 Integration using the settings configured via the QAS administration interface
For this type of integration you configure the Typedown settings for a particular
layout via the QAS administration interface as you would do for standard pages
(please refer to the QAS Installation Guide for more information). When you do the
integration in you have to tell the JavaScript API library which settings to use and
call the initialize function on the typedownClient object as shown below.
Follow the steps below to integrate Typedown:
Paste the code below somewhere on your custom Visual force page and set the
correct values for the settings.
QAS Typedown Client JavaScript API for Salesforce
<apex:includeScript value="/soap/ajax/25.0/connection.js" />
<apex:includeScript value="/soap/ajax/25.0/apex.js" />
<script src="https://online.qas.com/SalesForceV3/Scripts/all_sf_without_jQuery-2.0.min.js"> </script>
<script>
(function () {
//Configuration
var settings = {
xdomainProxyPageUrl: "URL_TO_PROXY_PAGE",
layoutId: 'LAYOUT_ID',
sfdcDomain: "SF_DOMAIN",
packagePrefix: “QAS_NA”,
done: function (success) {
if(success !== true) { return; };
//Code to subscribe to the save buttons on click event.
}
};
//End Configuration
}());
</script>
Let’s break the above script into snippets:
<apex:includeScript value="/soap/ajax/25.0/connection.js" />
<apex:includeScript value="/soap/ajax/25.0/apex.js" />
<script src="https://online.qas.com/SalesForceV3/Scripts/all_sf_without_jQuery-2.0.min.js"> </script>
This part includes the Salesforce dependencies as well as all the necessary
libraries for Typedown and the jQuery dependencies bundled together in the
all_sf_without_jQuery-2.0.min.js script.
The following lines:
var settings = {
xdomainProxyPageUrl: "URL_TO_PROXY_PAGE",
layoutId: 'LAYOUT_ID',
sfdcDomain: "SF_DOMAIN",
packagePrefix: “QAS_NA”,
done: function (success) {
if(success !== true) { return; };
//Code to subscribe to the save buttons on click event.
}
};
//End Configuration
Initialize the settings object to pass settings to the Typedown client.
For full description of all available settings please see section 4.
QAS Typedown Client JavaScript API for Salesforce
3.2. Integration with hard-coded Typedown settings for a custom Visualforce page
For this type of integration you configure the Typedown settings via JavaScript on
the page. The settings you configure in the QAS administration area are
disregarded by the Typedown JavaScript API client.
Follow the steps below to integrate Typedown:
Paste the code below somewhere on your custom Visual Force page and set the
correct values for the settings.
<apex:includeScript value="/soap/ajax/25.0/connection.js" />
<apex:includeScript value="/soap/ajax/25.0/apex.js" />
<script src="https://online.qas.com/SalesForceV3/Scripts/all_sf_with_jQuery-2.0.min.js"> </script>
<script>
$(document).ready(function () { //Make sure that the DOM is loaded
var sys = QASNA.system;
var td = QASNA.typedown;
var xd = QASNA.typedown.XD;
var sfdc = QASNA.typedown.sfdc;
td.jQuery = jQuery;
//Tell typedown which jQuery to use.
sforce.connection.sessionId = '{!$Api.Session_ID}'; //Initialize the sforce connection session
var settings = {};
settings[xd.Proxy.ProxyUrlParameterKey]
= "URL_TO_PROXY_PAGE"; //Url to the Salesforce
proxy page.
settings[xd.PostMessage.TargetDomainParameterKey] = “SF_DOMAIN”;
packagePrefix: “QAS_NA”,
settings[xd.ISDTP] = "mn";
//Tell Typedown to load the proxy page without home page
components on the left.
var configurations = getConfigurations(); //Create configuration.
window.typedownClient = new sfdc.Client(configurations, settings); //Create and initialize the
typedown object.
window.typedownClient.initialize(true);
//Code to subscribe to the save buttons on click event and which calls
window.typedownClient.fixValidationStatus();
});
function getConfigurations () {
var td = QASNA.typedown;
var config = new td.Configuration();
config.isUpperCase = false;
QAS Typedown Client JavaScript API for Salesforce
config.defaultCountry = 'USA';
config.addressValidationKey = "{!QASTypedownSessionToken}"; //You have to supply this parameter
from your controller.
var idPart = '{!$Component.accountDetail}';
idPart = idPart.replace(':', '_');
config.addOutputMapping('acc17' + idPart + 'street', td.DeliveryLine1);
config.addOutputMapping('acc17' + idPart + 'city', td.City);
config.addOutputMapping('acc17' + idPart + 'state', td.StateOrProvince);
config.addOutputMapping('acc17' + idPart + 'zip', td.ZIPPlus4OrPostalCode);
config.addOutputMapping('acc17' + idPart + 'country', td.TwocharacterISOcountrycode);
config.addOutputMapping('00NQ0000000 pNpR' + idPart, td.ValidationStatus);
config.addOutputMapping('00NQ0000000pNpM' + idPart, td.LastValidated);
return [config];
}
</script>
Let’s break the above script into snippets:
<apex:includeScript value="/soap/ajax/25.0/connection.js" />
<apex:includeScript value="/soap/ajax/25.0/apex.js" />
<script src="https://online.qas.com/SalesForceV3/Scripts/all_sf_with_jQuery-2.0.min.js"> </script>
This part includes the Salesforce dependencies as well as all the necessary QAS
libraries for Typedown and the jQuery dependencies bundled together in the
all_sf_without_jQuery-2.0.min.js script.
After that we instruct jQuery to execute our code when the DOM is fully loaded with
this line:
$(document).ready(function () { //Make sure that the DOM is loaded
//OUR CODE IS HERE
});
The following lines:
var sys = QASNA.system;
var td = QASNA.typedown;
var xd = QASNA.typedown.XD;
var sfdc = QASNA.typedown.sfdc;
Assign the Typedown namespaces we are going to use into variables for ease of
QAS Typedown Client JavaScript API for Salesforce
use.
The following lines:
td.jQuery = jQuery;
//Tell Typedown which jQuery to use.
sforce.connection.sessionId = '{!$Api.Session_ID}'; //Initialize the sforce connection session id
Tell the Typedown library which jQuery to use and initialize the session id for
Salesforce connection object
The following lines:
var settings = {};
settings[xd.Proxy.ProxyUrlParameterKey]
= "URL_TO_PROXY_PAGE"; //Url to the Salesforce proxy page.
settings[xd.PostMessage.TargetDomainParameterKey] = “SF_DOMAIN”;
packagePrefix: “QAS_NA”,
settings[xd.ISDTP] = "mn";
//Tell Typedown to load the proxy page without home page components.
Initialize the settings object to pass settings to the Typedown client.
For a full description of all available settings please see section 4.
The following lines:
var configurations = getConfigurations(); //Create configuration.
window.typedownClient = new sfdc.Client(configurations, settings); //Create and initialize the typedown object.
window.typedownClient.initialize(true);
Call a method which creates all Address Configurations for the page, create a
Typedown Client object and call initialize. The value “true” is passed to the initialize
function to indicate that this is a custom initialization and that the Typedown client
should not try to handle the save button click event handlers.
The following lines:
function getConfigurations () {
var td = QASNA.typedown;
var config = new td.Configuration();
config.isUpperCase = false;
QAS Typedown Client JavaScript API for Salesforce
config.defaultCountry = 'USA';
config.addressValidationKey = "{!QASTypedownSessionToken}"; //You have to supply this parameter from
your controller.
config.addOutputMapping('detailAddressCellIDstreet', td.DeliveryLine1);
config.addOutputMapping('detailAddressCellIDcity', td.City);
config.addOutputMapping('detailAddressCellIDstate', td.StateOrProvince);
config.addOutputMapping('detailAddressCellIDzip', td.ZIPPlus4OrPostalCode);
config.addOutputMapping('detailAddressCellIDcountry', td.TwocharacterISOcountrycode);
config.addOutputMapping('ID', td.ValidationStatus);
config.addOutputMapping('ID', td.LastValidated);
return [config];
}
Implement the “getConfigurations” function which returns an array of configuration
objects. In the above example it is only one configuration.
One important aspect when creating the configuration object is to set the
“addressValidationKey “property to a valid address validation session token. The
easiest way to do this is to create a property in your controller class and pass the
session token that way. In the example above the property declaration in the
controller is:
public String QASTypedownSessionToken {get; private set;}
The initialization of the “QASTypedownSessoinToken” property is done in the
controller's constructor. The code snippet which does the initialization is:
QAS_NA__QAS_CA_Account__c [] accountSObject = [SELECT QAS_NA__ValidationSessionToken__c FROM
QAS_NA__QAS_CA_Account__c];
if(accountSObject != null || accountSObject.size() > 0) {
QASTypedownSessionToken = accountSObject[0].QAS_NA__ValidationSessionToken__c;
}
Another very important aspect when creating configuration objects manually is the
rules on how to find the ids which need to be passed to the “addOutputMapping”
function. Please use the below rules to find the IDs:
3.2.1 For pages in detail mode - where you have to double click on the field before
you can edit
it - the ids are taken in the following way:
For addresses - the ids are equal to the “address field base id” + the
“address suffix for the address element”. The “address field base “id” is the id
which results from taking the HTML id of the “td” tag which contains the
address “div” element and removing the “_ilecell” suffix.
QAS Typedown Client JavaScript API for Salesforce
For example if the “td” containing an address has an id of
“acc17j_id0_j_id4_ilecell“, the street id will be: “acc17j_id0_j_id4street”, the
city id will be “acc17j_id0_j_id4city”, the state id will be
“acc17j_id0_j_id4state”, the zip id will be “acc17j_id0_j_id4zip”, the country id
will be “acc17j_id0_j_id4country”.
For regular fields the id is equal to the id which results from taking
the HTML id of the “td” tag which contains the field's “div” element and
removing the “_ilecell” suffix. For example if the “td” containing an element
has an id of “00ND00000050zIvj_id0_j_id4_ilecell” the id will be
“00ND00000050zIvj_id0_j_id4”
3.2.2 For pages in edit mode the id is the HTML id of the editing input element.
4. Typedown client settings:
The settings object is a JavaScript object or literal object and it is used to configure the
Typedown client.
The following are the possible settings. The settings which are mandatory are marked
in bold:
-
xdomainProxyPageUrl – this is the URL to the proxy page you have created as
described in section 4.
-
layoutId - this is the 15 character id of the layout which settings you would like to
use. The setting is mandatory only if you initialize Typedown as described
in section 3.1.
-
sfdcDomain – this is your salesforce.com primary domain without the trailing /.
For example: https://na12.salesforce.com. The parameter accepts a value of either a
function or a string. If a function is passed the function is called without passing parameters and its
return value should be the domain name.
-
sfdcUrlRewritenDomain – this is your urlRewriteDomain. In the case where
you are using URL rewriting you have to set this parameter to the URL
rewriten equivalen of the sfdcDomain
-
packagePrefix – the package prefix for the installed QAS package. Valid values
are “QAS_NA” for QAS Annual or “QAS_NA_LT” for QAS transactional.
-
recordId – the record id for the currently edited record. If you do not specify a
recordId QAS tries to find it by taking the value of the “id” URL GET parameter.
For new object creation the recordId parameter is ignored.
-
isNew – indicates whether this page is for editing an existing record or it is for
creating a new record.
QAS Typedown Client JavaScript API for Salesforce
-
done – specifies the callback function which will be called after the Typedown
initialization process completes. The function has one parameter of type boolean
which indicates whether the initialization is successful or not. You may use this
function to register to your record's save buttons click events and call the
“typedownClient.fixValidationStatus” function before the record is saved. The
“fixValidationStatus” function verifies that the address was not edited after
Typedown was used. It the address was edited after Typedown was used it
corrects its status to “User Preferred”.
Please refer to sections 3.1 and 3.2 for examples of how to use the settings object.
5. Create Proxy Visualforce page to facilitate cross domain communication
Because the Typedown server component sits on the QAS server the browser's cross
domain security policy disallows communication between the Typedown client and the
server. The proxy page you will create has to sit on the same domain as the domain
of the page you are integrating Typedown with. The page is used by the Typedown
server side component to communicate the address validation results back to your
page.
To create a proxy page go to Setup => Develop => Pages, click on the “New” button
to create a new page, enter: “QASTypedownProxy” for the label and the name and
paste the following for the page's markup:
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.js"> </script>
<script src="https://online.qas.com/SalesForceV3/Scripts/system.js"> </script>
<script src="https://online.qas.com/SalesForceV3/Scripts/xd.js"> </script>
<script>
var xd = QASNA.typedown.XD;
var xdReceiver = xd.createReceiver();
xdReceiver.receiveMessage();
</script>
The above script includes the jQuery library from Google’s CDN and system.js and
xd.js from QAS' server. It then creates a cross domain receiver object and calls the
“receiveMessage” function.
6. Registering your primary Salesforce domain as a remote site.
If you are integrating Typedown as described in section 3.1., the Typedown client
needs to call a REST webservice which comes as part of the QAS package. In order
for the package to be able to call the service your primary Salesforce domain has to
be in the list of allowed remote sites.
To add your Salesforce domain to the list of remote sites follow the procedure below:
1. Go to Setup => Security Controls => Remote Site Settings.
2. Click on “New Remote Site”.
QAS Typedown Client JavaScript API for Salesforce
3. Enter “salesforce” in the Remote Site Name textbox.
4. Enter your Salesforce 's primary domain (for example https://na12.salesforce.com)
in the Remote Site URL textbox.
5. Finally click “Save”.
© Copyright 2024 ExpyDoc
