This conceptual documentation is designed to let you quickly setup your own application form with the Connexys Application form API. You will learn about how to add a form on your website without the use of an iFrame.
This documentation is designed for people familiar with Javascript programming and object-oriented programming concepts. You should also be familiar with application forms from a user's point of view. There are many Javascript tutorials available on the web.
This API is available in version 7+ of the resource manager.
Before you get started
- The page the application form will be placed in must run under HTTPS.
- You need the public site URL of your ORG. This URL can be found in the "Setup" menu. Navigate to "Sites". You need the HTTPS site URL.
- Setup your salesforce org for the salesforce API
Step 2 and 3 require access to the Connexys application. If you don't have access to the Connexys application, ask your Connexys administrator to do this for you and to send you the public site URL. Also keep in mind that some of the setup of the form is done in the Connexys application. Without access to system you will be able to add the application form to your website, but your Connexys administrator will need to finalize the setup process.
Contents
Chapter | Content |
Hello world |
Helps you get started with the API |
Form options | Specifications for the different form options |
Passing analytics information to the Connexys application | Explains you how to pass analytics information to the Connexys application. |
Adding your own javascript logic to the form | Explains you how you can add your own javascript function to events happening on the form. |
Using URL parameters |
Explains how to use url parameters instead of javascript function options. |
Available functions for use in custom javascript code. | Explains which functions you can use in your own custom functions. |
Fileupload and how to style them. | A short explanation of a possible method to style the fileupload fields. |
Using a location prefill field. | Use a simple location search box to prefill the address information of the candidate. |
Full example | This chapter contains example code for all of the above possibilities. |
The easiest way to start learning about the Connexys Application Form JavaScript API is to see a simple example.
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale="1.0">
<link rel="stylesheet" href="https://MyCompany.force.com/resource/cxsrec__cxsFormStyle">
<script src="https://MyCompany.force.com/resource/cxsrec__cxsForm" type="text/javascript"></script>
</head>
<body>
<div id="cxsFormHolder"></div>
<script>
cxsForm.init({
target:"#cxsFormHolder",
server:"https://MyCompany.force.com/"
});
</script>
</body>
</html>
Even in this simple example, there are a few things to note:
- In the head section we set a few meta tags that will ensure that the page will be responsive for mobile devices.
- We load the Connexys Application Form JavaScript API using a script tag.
- We create a div element named "cxsFormHolder" to hold the application form.
- We define a JavasScript function that creates an application form in the div.
These steps are explained below.
1) Meta tags
The meta tag charset="utf-8" will make sure that the browser renders characters correctly.
The second meta tag is used to improve the responsiveness of the page.
2) Load the Connexys Application Form Javascript API
To load the Connexys Application Form Javascript API, use a script tag like the one in the following example. You must get this script library from the public site URL of your own ORG. So you should replace the "https://MyCompany.force.com/" with your own public site url.
Also notice that we get it from the secure (HTTPS) version of the site. This is also very important.
<head>
<script src="https://MyCompany.force.com/resource/cxsrec__cxsForm" type="text/javascript"></script>
</head>
3) Use a HTML container to place the cxsApplyform in.
For the application form to display on a web page, we must reserve a spot for it. Commonly, we do this by creating a named div element and obtaining a reference to this element in the browser's document object model (DOM).
In the example above, we used CSS to set the height of the cxsApplyForm div to "100%". This will expand to fit the size on mobile devices. You may need to adjust the width and height values based on the browser's screensize and padding. Note that divs usually take their width from their containing element, and empty divs usually have 0 height. For this reason, you must always set a height on the <div> explicitly.
<div id="cxsFormHolder"></div>4) Initialize the application form
<script>
cxsForm.init({
target:"#cxsFormHolder",
server:"https://MyCompany.force.com/"
});
</script>
4.) Add jQuery to the page
Optionally add jQuery to the page. If the page has no jQuery library available it will add jQuery v1.10.2 from your org (from Connexys version 17, this will be jQuery 1.12.3).
5.) Add styling to the page
You will want to add your own style to the form using CSS. To give you a headstart on this you can optionally use one of our premade style. Simply include one of these lines to the head of your page, either as an example or as a start to build your own CSS upon.
Responsive styling:
<link rel="stylesheet" href="https://MyCompany.force.com/resource/cxsrec__cxsFormStyle">
Basic styling:
<link rel="stylesheet" href="https://MyCompany.force.com/resource/cxsrec__cxsFormStyleBasic">
6.) Fallback for users without javascript
Extend your formHolder to show a loading spinner or a message for users without javascript.
<div id="cxsFormHolder">
<script>document.write('<img src="https://myCompany.force.com/resource/cxsrec__ajaxloader"/>');</script>
<noscript><br/>Javascript is required to show this form, please enable javascript or lower your security settings and try again.</noscript>
</div>
Please keep in mind that you need to change the "https://myCompany.force.com/" with your own public site URL.
7.) Questionnaires
When using questionnaires with the javascript form use the following article:
Javascript API for questionnaires
8.) Hardcriteria autocomplete
More about this feature ( release 9+) Javascript API Hardcriteria autocomplete .
9.) FAQ
Required parameters
Option | Type | Explanation |
target | String |
The HTML container the form will be placed in. Usually the ID of a DIV that will hold the application form. In case of multiple results we will add the form to the first element. <script> Example: "#cxsFormHolder" |
server | String |
The public site URL of your ORG. This URL can be found in the "Setup" menu. Navigate to "Sites". You need the HTTPS site URL. (including the "/" at the end of the URL. Example: "https://MyCompany.force.com/" |
Optional parameters
Option | Type | Explanation |
jobId | String |
In most cases you will use the application form in the context of a candidate applying for a specific job. You can specify the job by passing the ID of the job to the optional parameters. <script> Normally you will get the list of open jobs with their ID from the positionWebservice. |
eventId | String | The application form can also be used as a registration form for campus events that are published. This will allow students to register themselves to participate in a campus event.<script> Normally you will get the list of events with their ID from the eventWebservice. This parameter should not be combined with the jobId parameter, since the form is either in a "register for campus event" mode or in a "apply for a job" mode. |
lang | String |
The application form is multi-language by nature. You can specify the language in which you want to show the form by submitting the right language code. Languages must be available in the Connexys application. In most cases a subset of the following language codes is supported:
You can find the available languages for your Connexys ORG in the Connexys setup menu. They are also listed in a div called "cxsLanguages" in the form that is returned by the API. If this parameter is not available the value from the application settings is used: Connexys Resource Manager Setup > Application settings > Application form > Default language. Example code <script> |
mediaChannelId | String |
Jobs are published on mediachannel. A published job is called a job advert. A job advert has a start- and an end date. An example of a job advert is a job being published on your own website. When a candidate applies for a job, the form automatically checks if the job advert has not reached the end date yet. If the job is no longer active on the specified mediachannel, the candidate will see an error message that the job is no longer open. The default mediachannel is usually your own website. But sometimes you are implementing the form on another website (for example the intranet). In that case you should specify the mediachannel parameter with the ID of that mediachannel. You can find the ID in the Connexys application when you open the mediachannel. The ID is in the URL of the page. Example code <script> |
formId | String |
The content of forms can be maintained in the Connexys application. For example; in the form object you can specify:
If you don't specify a formId, the form that is linked to the mediachannel will be applied. You can override this form by specifying another formId. Example code <script> |
placeholders | true/false |
Show the label of the field as placeholder in the field. (default false) <script> |
errorHeader | true/false |
Show the list of field errors on top of the page after a submit. (default false) <script> |
textareaRows | Integer | Determines how many rows a textarea should have. This amount can be overridden by a field specific amount, the default amount is 8 rows. <script> Note. To prevent the textarea to be resized horizontally, you may want to use the following CSS style override. <style> |
scrollMargin | Integer | When a field error is found after a submit the page will scroll to that error. The field and label will normally be place at the very top of the page. For some sites this can be too close to the top of the page. (especially when using position:fixed headers bars). This option will allow you to put a margin between the top of the page and the field to scroll to. The amount is the number of pixels from the top of the screen. <script> cxsForm.init({ target:"#cxsFormHolder", server:"https://MyCompany.force.com/", scrollMargin: 25 }); </script> |
reset | true/false |
This forces the initialisation of the form to destroy all current fields on the form. (default false) This is useful when switching from an application form to a questionnaire form. <script> |
spinnerImg | URL |
This is an override on the spinner image shown while waiting for a file upload or a submit of the form. Best use a image that is hosted under HTTPS. <script> |
accessKey | To allow a candidate to update his information, an accessKey is required for security reasons. Accesskey is always used in combination with a candidateId. <script> cxsForm.init({ |
|
jobAppId | String | When using the Form to update a candidate, a jobApplication Id can be added optionally. This allows the candidate to update information for that jobapplication too. Obviously is this only allowed for jobapplications made by that candidate. <script> |
candidateId | String |
To allow a candidate to update his information, a candidateId is required for security reasons.
<script> |
googleMapsApiKey | String |
To access the Google Maps Javascript API, a Google maps api key is required. <script> |
Passing analytics information to the Connexys application
Usually some analytics tool like Google Analytics is active on the website. It is wise to pass visitor information from the analytics tool on to the Connexys application. This information will be stored in the job application object. And if you do so, this is of great value for reporting purposes.
The following parameters can be passed on to the Connexys application. They will have no effect on the way the form is shown, but they will be stored with the created jobapplications.
More information on the UTM parameters can be found here.
Option | Type | Explanation |
referer | String |
Example code <script> |
visitorId | String |
Example code <script> |
UTM_Campaign | String |
Example code <script> |
UTM_Content | String |
Example code <script> |
UTM_Medium | String |
Example code <script> |
UTM_Source | String |
Example code <script> |
UTM_Term | String |
Example code <script> |
Instead of setting a parameter in the javascript init function you can also set them as a URL parameter.
When the same parameter is set in both URL and javascript init function, the javascript init parameter is used.
For example: https://www.myWebsite.com?jobId=a0L2400000DbOqL&errorHeader=true
The following parameters can be set in the URL.
accessKey
accountId
candidateId
contactId
errorHeader
eventId
formId
googleMapsApiKey
jobAppId
jobId
lang
mediaChannelId
placeholders
questionnaireId
referer
scrollMargin
UTM_Campaign
UTM_Content
UTM_Medium
UTM_Source
UTM_Term
visitorId
Adding your own javascript logic to the form
We allow you to add your own javascript functions to some events that can happen on the form. It works with callback parameters. These parameters refer to a custom javascript function on your page. These functions can be used to perform changes to the HTML of the page, giving you more control over what is happening on the page.
You can add callback functions to the following events:
Option | Format | Explanation |
onInit | function(Boolean firstTime) |
This callback function is called each time the form is rendered or rerendered. The function will be called with 1 parameter:
Example code <script> |
onLanguageSwitch | function(String languageCode) |
Triggers just before the form language is switched. (the onInit will trigger once the form is rerendered in the new language). The function will be called with 1 parameter:
Example code <script> |
onFileUpload | Function(String status, String fieldey, Boolean textkernelUpload) |
Triggers when a file is uploaded
error : The request has been given an error response.
Example code <script>NOTE: The fieldkey is created by combining <object name>.<field name> in lowercase. |
onBeforeSubmit | Function(JsonString formData) | Triggers just before the form is submitted to the server. The function will be called with 1 parameter:
Example code <script> |
onAfterSubmit | Function(Boolean succesful, JsonString) | Triggers when the server has responded to the form submit. The function will be called with 2 parameters:
Example code <script> NOTE: If your custom function return false the normal error and success handling won't be executed. (In case of success this can be used to not show a thank you message on the page but do a redirect to another page instead.). |
onAfterValidation | Function(json fieldInfo, languageCode) |
This function will be triggered each time a field is validated. It allows you to add additional field checks to your fields. Example code <script>
function myFieldValidator(fieldInfo,language) { |
Available functions for use in custom javascript code.
When referring a field these function can use either a field ID or a field Key.
The field ID's are calculated on runtime and can change when for instance a field is added to the form.
To consistently reference a field it is best to use the field key.
The field key is of the format: <ObjectName>.<FieldName> (in lowercase).
Please do not use the ID's on the form in custom function code, as these ID's may change when a field is added/removed.
NOTE: Only the following functions are supported.
Option | Format | Explanation |
post() |
Calling this function will force a validation of all fields on the page followed by a post of the form to the server. If errorHeader is enabled it will show a list of all errors on the page. |
|
switchLanguage() | languageCode |
Force the page to switch to a new language. This function accepts the language codes defined in the Connexys settings. In most cases a subset of the following language codes is supported:
cxsForm.switchLanguage(); }
|
getLanguage() | Returns the languageCode of the currently active language. function myCustomFunction() { cxsForm.getLanguage(); } |
|
next() | This function allows you to go to the next page in the form. This currently only used when having placed Textkernel on a seperate page. function myCustomFunction() { cxsForm.next(); } |
|
getFieldKeyList() | return an array fieldkeys of all the fields on the form. function myCustomFunction() { cxsForm.getFieldKeyList(); } |
|
getFieldData() | fieldKey | Use a field key to retrieve all the data of the field. Some to the returned attributes are: value id (integer) error (boolean) errorCode (String) errorMessage (String) type (String) name (String) readOnly (String) function myCustomFunction() { cxsForm.getFieldData('cxsrec__cxscandidate__c.cxsrec__date_of_birth__c'); } |
setFieldValue() | fieldKey,value | This function allows you to set the value of the given field. The field will immediately be checked for errors too just as with cxsForm.checkField(fieldKey) To use this function with a file the value parameter should be an url. Date values must always be in the format yyyy-mm-dd function myCustomFunction({ cxsForm.setFieldValue("cxsrec__cxscandidate__c.cxsrec__date_of_birth__c","1970-10-20") } |
Fileupload and how to style them.
The fileupload buttons on the form are actually small iframes used to send files to server. Javascript filereaders are not used to remain compatible with older browsers.
Using the small CSS example below allows you to style the span.cxsFileUpload as a button.
span.cxsFileUpload {
cursor: pointer;
position: relative;
display: inline-block;
}
iFrame.cxsFileUploadFrame {
height: 100%;
width: 100%;
opacity: 0;
-ms-filter: "progid:DXImageTransform.Microsoft.Alpha(Opacity=0)";
filter: alpha(opacity=0);
position: absolute;
top: 0px;
left: 0px;
}
Or use the full CSS example in the cxsFormStyle.
Using a location prefill field
In the form, you can use a geolocation field als shown in the image below.
The field can be added to the form, by placing a field called "Geolocation" to your forms candidate fieldset. It will try to prefill the 'cxsrec__Address_line_1__c' (with street and house number), cxsrec__Town_city__c, cxsrec__Postcode__c and cxsrec__Country__c.
It will only prefill fields which are actually on the form, but the fields may be hidden using CSS in the page on which the form is.
Notes:
- The geolocation field can also be used in an update situation.
- When the geolocation has to be calculated automatically, but the autocomplete field is not part of the form. But the geolocation field should be in the fieldset and hidden with CSS. Make sure as many of the following address fields are in the fieldset (and feel free to change their labels in the translation workbench):
- Address line 1
- Town / City
- Zipcode
- Country
- And of course the hidden geolocation
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="https://MyCompany.force.com/resource/cxsrec__cxsForm" type="text/javascript"></script>
<link rel="stylesheet" href="https://MyCompany.force.com/resource/cxsrec__cxsFormStyle">
<title>CXSappy Test page</title>
</head>
<body>
<div id="cxsFormHolder">
<script>document.write('<img src="https://AnotherServer.com/img/spinner.gif"/>');</script>
<noscript><br/>Javascript is required to show this form, please enable javascript or lower your security settings and try again.</noscript>
</div>
<script>
cxsForm.init({
target:"#cxsFormHolder",
server:"https://MyCompany.force.com/",
jobId:"a0y24000000CWec",
lang:'nl_NL',
mediaChannelId :"a0q24000000CdLY",
placeholders:true,
errorHeader:true,
onInit:myInit,
onAfterSubmit:myDoneFunction,
onlanguageSwitch:switchLang,
onFileupload:myFileUpload,
onAfterValidation :myFieldValidator,
UTM_Campaign:"UTM_Campaign test",
UTM_Content:"UTM_Content test",
UTM_Medium:"UTM_Medium test",
UTM_Source:"UTM_Source test",
UTM_Term:"UTM_Term test",
visitorId:"visitorId test",
referer:"referer test",
textareaRows:10,
spinnerImg:"https://AnotherServer.com/img/spinner.gif"
});
function myInit(firstTime) {
console.log('init',firstTime);
}
function switchLang(newLanguage) {
console.log('switching to language:',newLanguage);
}
function myFieldValidator(fieldInfo,language) {
// example extra date validations on date of birth
if(fieldInfo.key == 'cxscandidate__c.date_of_birth__c') {
if(fieldInfo.error == false && fieldInfo.value && fieldInfo.value != '') {
var isoDate = new Date(fieldInfo.value);
var currentDate = new Date();
if(isoDate > currentDate ) {
switch(language) {
case 'nl_NL':
case 'nl': return 'Deze datum ligt in de toekomst.';
default: return 'This date is in the future.';
}
}
var newestDate = new Date();
newestDate .setYear(newestDate.getFullYear()-18);
if(isoDate > newestDate) {
switch(language) {
case 'nl_NL':
case 'nl': return 'Deze datum is te recent.';
default: return 'This date is too recent.';
}
}
var oldestDate = new Date();
oldestDate.setYear(oldestDate.getFullYear()-100);
if(isoDate < oldestDate) {
switch(language) {
case 'nl_NL':
case 'nl': return 'Deze datum is te ver in het verleden.';
default: return 'This date is too far in the past.';
}
}
}
}
return null;
}
function myDoneFunction(isSuccess, results) {
console.log('success',isSuccess);
console.log('result',results);
if(isSuccess) {
//document.location = 'https://www.google.com';
console.log(' SUCCESS !!!!');
}
}
function myFileUpload(status,fieldKey,isTextKernel) {
console.log(status,fieldKey,'TK:',isTextKernel);
}
</script>
</body>
</html>
Important
- Do not enable referer hiding on the customer's web server, since the referer is necessary in order to check whether the form is actually used by a website of the customer. When referer hiding is enabled it throws an error on the application form and applying is not possible.