Skip to the content

eForms API functions & events

Form event functions

This custom event functions will be called only if exists.

Function
Description

OnProcessStart()

When code-behind is being hit this function is called. Inside this function can be specified what will happen on client side when renderer is loading or waiting for server response. Loading dialogue can be shown for example.

OnProcessEnd()

This function is being hit when server-side work (event handling) is done. This function can hide loading dialogue for example.

OnRendererError(msg, code)

Inside this function can be handled server side exceptions. Show default error message instead of whole error or do some log stuff etc.

OnFormRendererReady()

This function is being hit on hub connection done event. Inside this function can be decided what will happen or be loaded when client connection is established. Hub connection has been established and renderer is ready for the form load.

NOTICE: The form is NOT loaded when this event is fired, but the automatic form load can be performed there.

OnFormRendered()

The function will be loaded as soon as the form is loaded.

NOTICE: Called with each form refresh (event calls etc.)

OnJSLocalization(cultCode)

The function is called immediately after form culture has been changed. This function can be used for script localizations and logic that will happen after culture change.

Example: http://e-formsfactory.com/blog/posts/2019/march/calendar-script-localization/

 

Hub event functions

NOTICE: from version 1.0.5.29

This custom event functions will be called only if exists.

OnHubDisconnected This function is called when hub disconects.
OnHubReconnected This function is called when hub successsfully reconects.
OnHubReconnecting This function is called during hub reconnecting process.
OnHubConnectionSlow This function is called when connection with hub drops into slow connection state.

 

Form API functions

 

IsFormValid(cSLRenderObjectId, currentPageOnly, successHandler)

This function validates current form or current page of the form. This function has not return args and result is UI validation inside form.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

currentPageOnly

boolean

Validate form as a whole or validate current page only?

successHandler

function

Function handler call on DONE event. Bool as EventArgs

 

Example:

//validate form handler
function validateForm() {
  IsFormValid('formHolder', false, doneHandler);
}

//what to do when template load is done
const doneHandler = function () {
       if (e) {
            alert('Form is VALID');
        } else {
            alert('Form is NOT VALID');
        }
}

<a href="validateForm();">Validate!</a>

LoadExternalData(cSLRenderObjectId, xmlData, tampleteUid, templateVersion, targetSystemKey, successHandler)

This function loads external Xml data and shows it in selected template by transformation schema specified by targetSystemKey.

Name
Type
Description
cSLRendererObjectId string ID of the container for the form.

xmlData

string

String XML data for load

templateUid

string GUID

String GUID of the target form

templateVersion

int

Desired version of the target form. Nullable

targetSystemKey

string

Target system key. Nullable

successHandler

function

Callback function for DONE handler. No return value

 

Example:

function loadData() {
  //get current form data and than call handler that will handle what to do with the data
  GetTransformedData('formHolder', null, dataHandler)
};

//got xml data from GetTransformedData function! lets load them into form
const dataHandler= function (e) {
  LoadExternalData('formHolder', e, '643A9C69-9D8F-4CE6-963E-03D69CA062CD', null, null, doneHandler)
};

//final handler
const doneHandler = function () {
  //all is done! show info inside console
  console.log('DATA LOADED!');
};

<a href="loadData();">Load data!</a>

loadExternalDataViewPage(cSLRenderObjectId, xmlData, tampleteUid, templateVersion, viewName, targetSystemKey, page, successHandler)

Load external Xml data and shows it in selected template by transformation schema specified by targetSystemKey, view and page.

Name
Type
Description
cSLRendererObjectId string ID of the container for the form.

xmlData

string

String XML data for load

templateUid

string GUID

String GUID of the target form

templateVersion

null or int

Desired version of the target form. If set to null then last page will be loaded.

viewName

null or string

Name of the form view. 

targetSystemKey

string

Target system key. Nullable

page

null or int[]

Only for selected pages. If set to null then all pages will be selected.

successHandler

function

Callback function for DONE handler. No return value

 

Example:

function loadData() {
  //get current form data and than call handler that will handle what to do with the data
  GetTransformedData('formHolder', null, dataHandler)
};

//got xml data from GetTransformedData function! lets load them into form
const dataHandler= function (e) {
  LoadExternalData('formHolder', e, '643A9C69-9D8F-4CE6-963E-03D69CA062CD', null, 'someViewName', null, [5], doneHandler)
};

//final handler
const doneHandler = function () {
  //all is done! show info inside console
  console.log('DATA LOADED!');
};

<a href="loadData();">Load data!</a>

Loads data into form '643A9C69-9D8F-4CE6-963E-03D69CA062CD' on page 5 and view name "someViewName".

LoadExternalDataByLabel(cSLRenderObjectId, xmlData, tampleteUid, versionLabel, targetSystemKey, successHandler)

Load external Xml data and shows it in selected template by transformation schema specified by versionLabel and templateUid.

Name
Type
Description
cSLRendererObjectId string ID of the container for the form.

xmlData

string

String XML data for load

templateUid

string GUID

String GUID of the target form

versionLabel

string

Template label

targetSystemKey

null or string

Target system key.

successHandler

function

Callback function for DONE handler. No return value

 

function loadData() {
  //get current form data and than call handler that will handle what to do with the data
  GetTransformedData('formHolder', null, dataHandler)
};

//got xml data from GetTransformedData function! lets load them into form
const dataHandler= function (e) {
  LoadExternalData('formHolder', e, '643A9C69-9D8F-4CE6-963E-03D69CA062CD', 'someLabel', null, doneHandler)
};

//final handler
const doneHandler = function () {
  //all is done! show info inside console
  console.log('DATA LOADED!');
};

<a href="loadData();">Load data!</a>

GetTransformedData(cSLRenderObjectId, targetSystemKey, successHandler)

This function prepares XML transformed data from current form template and currently filled data as string XML.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

targetSystemKey

null or string

Target system key.

successHandler

function

Function handler call on DONE event. String XML as EventArgs

 

//print function that calls done handler
function printDataIntoConsole() {
  GetTransformedData('formHolder', null, doneHandler)
}

//print handler -> xml data into console
const doneHandler = function (e) {
  //print data into console, call other function, push data into variable or anything else
  console.log(e);
}

<a href="printDataIntoConsole();">Show me XML data!</a>

GetTransformedDataId(cSLRenderObjectId, targetSystemKey, successHandler)

This function prepares XML transformed data from current form template and currently filled data as string GUID.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

targetSystemKey

null or string

Target system key.

successHandler

function

Function handler call on DONE event. String GUID as EventArgs

 

//print function that calls done handler
function printDataIntoConsole() {
  GetTransformedDataId('formHolder', null, doneHandler)
}

//print handler -> xml data into console
const doneHandler = function (e) {
  //Got guid print it into console, call other function, push data into variable or anything else
  console.log(e);
}

<a href="printDataIntoConsole();">Show me data guid!</a>

PageCount(cSLRenderObjectId, successHandler)

This function gets number of pages of the current form.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

successHandler

function

Function handler call on DONE event. Int page nuber as EventArgs

 

//open form template handler
function OpenLink () {
  //OpenFormTemplate(cSLRenderObjectId, templateUid, version, defaultLang,, successHandler, view)
  OpenFormTemplateOnPage('formHolder', '16A382FF-DC26-46AF-A7BE-DA15C3B44287', null, null, 
  doneHandler , 'Wizard')
}

//what to do when template load is done
const doneHandler = function () {
  //load current poage
  CurrentPage('formHolder', currentPageSuccessHandler);
  //load number of pages
  PageCount('formHolder', pageCountSuccessHandler);
}

//current page handler
const currentPageSuccessHandler = function (e) {
  //get current page label and set it's value incremented by one (starts from 0)
  const lbl = document.getElementById('lblCurrentPage');
  lbl.textContent = e +1;
}

//page count handler
const currentPageSuccessHandler = function (e) {
  //get page count label and set value
  const lbl = document.getElementById('lblPageCount');
  lbl.textContent = e;
}

<a href="OpenLink();">OPEN</a>

CurrentPage(cSLRenderObjectId, successHandler)

This function returns number of the current form page.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

successHandler

function

Function handler call on DONE event. Int page number as EventArgs.

NOTICE: page number starts with 0!

 

Example:

//open form template handler
function OpenLink () {
  //OpenFormTemplate(cSLRenderObjectId, templateUid, version, defaultLang,, successHandler, view)
  OpenFormTemplateOnPage('formHolder', '16A382FF-DC26-46AF-A7BE-DA15C3B44287', null, null, 
  doneHandler , 'Wizard')
}

//what to do when template load is done
const doneHandler = function () {
  //load current poage
  CurrentPage('formHolder', currentPageSuccessHandler);
  //load number of pages
  PageCount('formHolder', pageCountSuccessHandler);
}

//current page handler
const currentPageSuccessHandler = function (e) {
  //get current page label and set it's value incremented by one (starts from 0)
  const lbl = document.getElementById('lblCurrentPage');
  lbl.textContent = e +1;
}

//page count handler
const currentPageSuccessHandler = function (e) {
  //get page count label and set value
  const lbl = document.getElementById('lblPageCount');
  lbl.textContent = e;
}

<a href="OpenLink();">OPEN</a>

SetPage(cSLRenderObjectId, pageNum, successHandler)

This function jumps to desired page number. Function will call OnProcessStart custom event function (if exists) automatically.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

pageNum

int

Number of the page to jump.

successHandler

function

Function handler call on DONE event. No return value

 

Example:

//open page
function OpenPage(pageNum) {
  SetPage('formHolder', pageNum, doneHandler)
}

//what to do when page load is done
const doneHandler = function () {
  //call hide modal/loading dialogue by the custom form event function
  OnProcessEnd()
}

<a href="OpenPage(10);">OPEN</a>

SetNextPage(cSLRenderObjectId, successHandler)

The form will move to the next page. Function will call OnProcessStart custom event function (if exists) automatically.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

successHandler

function

Function handler call on DONE event. No return value

 

Example:

function nextPage() {
  SetNextPage('formHolder', doneHandler)
}

//what to do when page load is done
const doneHandler = function () {
  //call hide modal/loading dialogue by the custom form event function
  OnProcessEnd()
}

<a href="nextPage();">NEXT</a>

SetPrevPage(cSLRenderObjectId, successHandler)

The form will move to the next page. Function will call OnProcessStart custom event function (if exists) automatically.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

successHandler

function

Function handler call on DONE event. No return value

 

Example:

function prevPage() {
  SetPrevPage('formHolder', doneHandler)
}

//what to do when page load is done
const doneHandler = function () {
  //call hide modal/loading dialogue by the custom form event function
  OnProcessEnd()
}

<a href="prevPage();">Previous</a>

OpenFormTemplate(cSLRenderObjectId, templateUid, templateVersion, defaultLang, successHandler, view)

The form will load specified form template.

Name
Type
Description
cSLRendererObjectId string ID of the container for the form.
templateUid string Guid String guid of the form to load.
templateVersion null or int Version of the form to load.
defaultLang null or string Null or String culture code to load as default.

successHandler

function

Function handler call on DONE event.

view

null or string

Name of the form view. OPTIONAL No return value

Example:

//open form template handler
function OpenLink () {
  //OpenFormTemplate(cSLRenderObjectId, templateUid, version, defaultLang,, successHandler, view)
  OpenFormTemplateOnPage('formHolder', '16A382FF-DC26-46AF-A7BE-DA15C3B44287', null, null, 
  doneHandler , 'Wizard')
}

//what to do when template load is done
const doneHandler = function () {
  console.log('Form loaded successfully!');
}

<a href="OpenLink();">OPEN</a>

This example loads form template after html link click event. Example will print message into console after load of the form template is done.

OpenFormTemplateOnPage(cSLRenderObjectId, templateUid, templateVersion, defaultLang, page, successHandler, view)

Opens form template on the desired page number and form view.

Name
Type
Description
cSLRendererObjectId string ID of the container for the form.
templateUid string Guid String guid of the form to load.
templateVersion null or int Version of the form to load.
defaultLang null or string Null or String culture code to load as default.
page int Page number to starts with.

successHandler

function

Function handler call on DONE event.

view

null or string

Name of the form view. OPTIONAL No return value

Example

//open form template handler
function OpenLink () {
  //OpenFormTemplate(cSLRenderObjectId, templateUid, version, defaultLang,, successHandler, view)
  OpenFormTemplateOnPage('formHolder', '16A382FF-DC26-46AF-A7BE-DA15C3B44287', null, null, 10, 
  doneHandler , 'Wizard')
}

//what to do when template load is done
const doneHandler = function () {
  console.log('Form loaded on page 10 successfully!');
}

<a href="OpenLink();">OPEN</a>

This example loads form template on page 10 after html link click event. Example will print message into console after load of the form template is done.

GetCurrentFormCulture(cSLRenderObjectId, successHandler)

Returns currently loaded form culture.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

successHandler

function

Function handler call on DONE event. String culture code as EventArgs.

 

Example:

function getCurrentCulture() {
  GetCurrentFormCulture('formHolder', doneHandler)
}

//what to do when page load is done
const doneHandler = function (e) {
  //got culter code from designer (like en-US etc.)
}

<a href="getCurrentCulture();">Print Culture</a>

GetCurrentTemplateCultures(cSLRenderObjectId, successHandler)

Returns supported cultures for current template.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

successHandler

function

Callback function for DONE handler.

Object {Items: [{

  Code"en-US"

  Name"English (United States)"

  NativeName"English (United States)"

}]} as EventArgs

 

Example:

function getCultures() {
  GetCurrentTemplateCultures('formHolder', doneHandler)
}

//what to do when page load is done
const doneHandler = function (langs) {
  if (langs != null) {
            //foreach languages and paste them into combobox
            $.each(langs.Items, function (i, item) {
                $('#cbxLanguage').append($('

SetCulture(cSLRenderObjectId, sCulture)

Changes current form culture.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

sCulture

string

Culture code. (en-US)

 

Example:

function setCulture(culture) {
  SetCulture ('formHolder', culture);
}

<a href="setCulture('en-US');">English</a>

PrintForm(cSLRenderObjectId, fileType, overrideDefault)

Prints current form into PDF or XPS

Name
Type
Description
cSLRendererObjectId string ID of the canvas

fileType

'PDF' or 'XPS'

Ouptut file type.

overrideDefault

function(e)

OPTIONAL - Callback function to override default behaviour. Url string as EventArgs.

 

Example:

//call pdf print
function printToPdf() {
  //print form as PDF and call printHandler when data are prepared to be printed
  PrintForm('formHolder', 'PDF', printHandler);
}

//override default behaviour and print it in different way
const printHandler = function (e) {
    //got string file url like ‚https://xxx.xx/xxx.pdf‘
    //TODO: create dummy html link and trigger fake click on it
};

<a href="printToPdf();">PDF Print</a>

printFormPages(cSLRenderObjectId, fileType, pagesToPrint, overrideDefault)

Prints selected pages only.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

fileType

'PDF' or 'XPS'

Ouptut file type.

pagesToPrint

null or int[]

Array of page numbers that will be printed. If parameter is null than all pages will be printed.

overrideDefault

function(e)

OPTIONAL - Callback function to override default behaviour. Url string as EventArgs.

 

Example:

//call pdf print
function printToPdf() {
  //print form as PDF and call printHandler when data are prepared to be printed
  PrintForm('formHolder', 'PDF', [1,5], printHandler);
}

//override default behaviour and print it in different way
const printHandler = function (e) {
    //got string file url like ‚https://xxx.xx/xxx.pdf‘
    //TODO: create dummy html link and trigger fake click on it
};

<a href="printToPdf();">PDF Print</a>

Ouptut pdf file will contain only page 1 and page 5.

PrintMultipleForms(cSLRenderObjectId, templateData, overrideDefault)

NOTICE: from version 1.0.5.39

Print with multiple options. This function combines all previous print functions. Can print to a different tamplete.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

templateData

Object 

{

  string DataUidOrXml;

  public int[] Pages;

  string Uid;

  string Version;

  string ViewName;

}

DataUidOrXml - can be XML or teporary data UID from FormServer

Pages - desired pages to print – Print ALL if null

Uid - UID of form to print

Version - Version of form to print

ViewName - View of form to print

overrideDefault

function(e)

OPTIONAL - Callback function to override default behaviour. Url string as EventArgs.

 

Example:

//call pdf print
function printToPdf() {
  //get temporary data UID of current form
  GetTransformedDataId('formHolder', null, function (e) {
    //got data => print them inside another form
    PrintMultipleForms('formHolder', { Items: [{ DataUidOrXml: e, Pages: null, Uid: '643A9C69-9D8F-4CE6-963E-03D69CA062CD', Version: null, View: null }] });
});

}

//override default behaviour and print it in different way
const printHandler = function (e) {
    //got string file url like ‚https://xxx.xx/xxx.pdf‘
    //TODO: create dummy html link and trigger fake click on it
};

<a href="printToPdf();">PDF Print</a>

First of all this function needs to have XML data or temporary data ID.  This example uses callback handler of GetTransformedDataID function to get temporary data ID and places it into print function. Result of this example:

- data are printed inside form '643A9C69-9D8F-4CE6-963E-03D69CA062CD'

- all pages are printed

- with latest version of the form tempalte

GetFormMetadataValue(cSLRenderObjectId, metadataKey, successHandler)

Returns value of a single metadata value.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

metadataKey

string

Name of param

successHandler

function

Function handler call on DONE event. String metadata value as EventArgs

 

Example:

function gettadataValue() {
  //call get function with handler
  GetFormMetadataValue('formHolder', 'someMetadataName', returnMetadata)
}

//handler for getMetadata
const returnMetadata = function (e) {
    console.log('Value of someMetadataName is: ' + e);
};

<a href="gettadataValue();">Show Value!</a>

GetFormMetadata(cSLRenderObjectId, successHandler)

Returns all metadata values from the current from.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

successHandler

function

Function handler call on DONE event. Object {string Key; string Value} as EventArgs.

 

Example:

function getFormMetadata() {
  //call get function with handler
  GetFormMetadata('formHolder', returnMetadata)
}

//handler for getMetadata
const returnMetadata = function (e) {
    const items = e.Items;
        if (items.length > 0) {
            let w = window.open();
            let html = '';
            for (var i = 0, len = items.length; i < len; i++) {
                html += '<p>' + items[i].Key + ': ' + items[i].Value + '</p>';
            }
            $(w.document.body).html(html);
        }
};

<a href="getFormMetadata();">Show Metadata!</a>

This example will print ALL metadata of the current form into new window.

GetTemplateMetadata(templateUid, templateVersion, successHandler)

Returns all metadata values from a template.

Name
Type
Description
templateUid string ID of the canvas
templateVersion int Number of the form version. If null than last version of form will be used.

successHandler

function

Function handler call on DONE event. Object {string Key; string Value} as EventArgs.

 

Example:

function getTemplateMetadata() {
  //call get function with handler
  GetTemplateMetadata('8655F819-2AE3-4F67-B326-26B681476EEB', null, returnMetadata)
}

//handler for getMetadata
const returnMetadata = function (e) {
    const items = e.Items;
        if (items.length > 0) {
            let w = window.open();
            let html = '';
            for (var i = 0, len = items.length; i < len; i++) {
                html += '<p>' + items[i].Key + ': ' + items[i].Value + '</p>';
            }
            $(w.document.body).html(html);
        }
};

<a href="getTemplateMetadata();">Show Metadata!</a>

LoadTemplateMetadataSync(templateUid, templateVersion)

Load template metadata synchronously.

Name
Type
Description
templateUid string ID of the canvas
templateVersion int Number of the form version. If null than last version of form will be used.

 

Example:

//TODO

GetFormsVersion(successHandler)

Gets version list of all form libraries. This function is used by script function "scriptsVersion"

Name
Type
Description

successHandler

function

Function handler call on DONE event. string as EventArgs.

 

SetSessionData(dataType, data, successHandler)

Set security token.

Name
Type
Description
dataType any  

data

any

 

successHandler

function

Function handler call on DONE event.

 

Example:

//TODO

LoadFormInstance(cSLRenderObjectId, templateUid, templateFormat, defaultLang, isPartialUpdate)

Loads existing instance of the form.

Name
Type
Description
cSLRendererObjectId string ID of the container for the form.
templateUid string Guid String guid of the form to load.
templateFormat 'html5v2' Format of the script output.
defaultLang null or string Null or String culture code to load as default.
isPartialUpdate boolean Full or partial update

Example:

//TODO

GetControlsInfo(cSLRenderObjectId, nameFilter, successHandler)

NOTICE: from version 1.0.5.21

Gets control's info as JSON that corresponds to regex input.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

nameFilter

string regex

Find control inside form by regex

successHandler

function

Function handler call on DONE event.

Example: http://e-formsfactory.com/blog/posts/2018/november/find-page-by-control-id/

ValidatePages(cSLRenderObjectId, successHandler)

NOTICE: from version 1.0.5.30

Validates form by canvas ID and return pages with unvalid controls.

Name
Type
Description
cSLRendererObjectId string ID of the canvas

successHandler

function

Function handler call on DONE event.

 

Example:

//TODO

GetSessionID()

Returns current session GUID.

Name
Type
Description
Without parameters    
//call function
GetSessionID();

//returns GUID as string "34c30529-d409-46be-ab75-6c8aaa90446b"

LoadExternalDataViewPageEx(cSLRenderObjectId, xmlData, tampleteUid, templateVersion, viewName, targetSystemKey, page, successHandler)

NOTICE: from version 1.0.10.101

Load external Xml data and shows it in selected template by transformation schema specified by targetSystemKey, view and page.

NOTICE: Works for form DRAFT

Name
Type
Description
cSLRendererObjectId string ID of the container for the form.

xmlData

string

String XML data for load

templateUid

string GUID

String GUID of the target form

templateVersion

null or int

Desired version of the target form. If set to null then last page will be loaded.

viewName

null or string

Name of the form view. 

targetSystemKey

string

Target system key. Nullable

page

null or int[]

Only for selected pages. If set to null then all pages will be selected.

successHandler

function

Callback function for DONE handler. No return value
//TODO