Javascript Application Form API: Basic Setup

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.

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.

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.

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

The application form must be initialized to show it on the page. The initialization works with form options. There are two required options for every form: target and server.

The example above shows an open application using the default mediachannel.

There are much more settings you can use to include the right application form More detailed explanation of the available form options can be found below.

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.

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.

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.

Note. To prevent the textarea to be resized horizontally, you may want to use the following CSS style override.

<style> #cxsWrapper textarea {resize: vertical;}</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.

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.

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.

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.accessKeyaccountIdcandidateIdcontactIderrorHeadereventIdformIdgoogleMapsApiKeyjobAppIdjobIdlangmediaChannelIdplaceholdersquestionnaireIdrefererscrollMarginUTM_CampaignUTM_ContentUTM_MediumUTM_SourceUTM_TermvisitorId

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:

Boolean : true if this is the first time the form is rendered, otherwise false.

Triggers when the server has responded to the form submit. The function will be called with 2 parameters:

Boolean : true if the submit was successfully saved, otherwise false.

JsonString : The format of this json string depends on the result. In case of success the json will contain candidateId, jobId, eventId, formId, mediaChannelId, questionnaireId, applicationId.

The server can return either "error" in the case of required field not being available, or "errors" in the case that a server error is triggered while saving to salesforce (for instance caused by custom field checks on the server).Examples: { "error": "<errorLabel>", "fields": ["<field Key>"]}

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.The function will be called with 2 parameters:fieldInfo : A json containing all the information about the current field (read only)String : The language code of the active language.

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.

function myCustomFunction() { cxsForm.post();}

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:

de (German)

nl_NL (Dutch)

fr (French)

en_US (English)

sk (Slovak)

pl (Polish)

function myCustomFunction() { 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:valueid (integer)error (boolean)errorCode (String)errorMessage (String)type (String)name (String)readOnly (String)

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.

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):

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.