Registration JavaScript API: Functions

Need to, say, retrieve client settings? Turns out there's an app (or, at least, a function for that).

Below are the functions available in the Registration JavaScript APIs.

activateCaptureControl

janrain.capture.ui.activateCaptureControl(controlName);

Activates a Control action defined in the flow. Typically this is used to trigger emails.

applySettings

janrain.capture.ui.applySettings(clientSettings);

Accepts an object containing client settings that can be used by the Registration widget to populate dynamic information within registration forms.

createCaptureSession

janrain.capture.ui.createCaptureSession(accessToken);

Creates a Registration session from an access token returned from the Registration API. In general the Registration service handles session creation for you, so you don’t need to call this manually. See Managing Sessions with Registration for information on when you would need to call createCaptureSession.

endCaptureSession

janrain.capture.ui.endCaptureSession();

Invalidates the current login session.

getClientSettings

janrain.capture.ui.getClientSettings();

Returns a copy of the client settings.

getEngageCookie

janrain.capture.ui.getEngageCookie(name);

Returns a piece of the return experience data stored after a successful social login by name. Name can be one of the following:

  • 'expected_tab' - This is the last tab that the user clicked on in the Social Login widget.
  • 'welcome_info_name' - This is the display name reported by the identity provider, used to greet the user upon returning to the site.
  • 'login_tab' - This is the tab with which the user logged in.

getFailedLogins

janrain.capture.ui.getFailedLogins();

Returns the number of failed login attempts. This number resets when a successful login is made.

getProfileCookieData

janrain.capture.ui.getProfileCookieData(propertyName);

Returns the specified property from the JSON string stored in the localStorage key janrainCaptureProfileData. This data disappears after the user closes their browser. See an example in Customizing Registrations.

getPublicProfile

janrain.capture.ui.getPublicProfile(publicProfileScreenName,profileUuid);

Renders the public profile screen. The name of the public profile screen as well as the UUID of the profile are required.

getReturnExperienceData

janrain.capture.ui.getReturnExperienceData(propertyName);

Returns the specified property from the JSON string stored in the localStorage key janrainCaptureReturnExperienceData. This data persists even after the user closes their browser. See an example in Customizing Registrations.

hasActiveSession

janrain.capture.ui.hasActiveSession();

Returns true if the registration widget has an access token, false otherwise.

linkSocialAccount

janrain.capture.ui.linkSocialAccount(providerName);

Note: This function requires that Social Login is also configured.

Starts the link account flow and prompts the user to log in to the provider specified. providerName can be the name of any provider configured in your Social Login settings.

modal.close

janrain.capture.ui.modal.close();

Closes the Registration widget login modal.

modal.closeConfirm

janrain.capture.ui.modal.closeConfirm();

Closes the Registration widget login modal, but first prompts the user to confirm.

modal.open

janrain.capture.ui.modal.open();

Opens the Registration widget login modal.

modal.setBorder

janrain.capture.ui.modal.setBorder(width);

Sets the Registration widget login modal border width.

modal.setBorderColor

janrain.capture.ui.modal.setBorderColor(hexColor);

Sets the Registration widget login modal border color. Accepts a string with a hex value.

modal.setBorderOpacity

janrain.capture.ui.modal.setBorderOpacity(opacity);

Sets the Registration widget login modal border opacity. Accepts a numeric value between 0 and 1.

modal.setBorderRadius

janrain.capture.ui.modal.setBorderRadius(radius);

Sets the Registration widget login modal border radius. Accepts an integer.

modal.setOverlayZIndex

janrain.capture.ui.modal.setOverlayZIndex(index);

Sets the Registration widget login modal background overlay z Index. Accepts an integer.

noop

janrain.capture.ui.noop();

A noop function.

postCaptureForm

janrain.capture.ui.postCaptureForm(formName[,fieldValues]);

Posts a form to the Registration service and executes any server-side validation defined in the flow. formName must be the name of a form that exists in the flow.

Optionally takes an object containing key-value pairs to populate the form with data. The key names must match the field names in the form. If fieldValues is omitted, the Registration widget extracts the field values from the specified form on the page.

Here is an example of how to programmatically submit a form with user-entered data:

varformName = 'editProfileForm';
janrain.capture.ui.postCaptureForm(formName);

Here is an example submitting the same form, but this time we will also provide the values to submit:

varformName = 'editProfileForm';
varfieldValues = {
  firstName:'Jake',
  lastName:'Anders'
};
janrain.capture.ui.postCaptureForm(formName,fieldValues);

registerFunction

janrain.capture.ui.registerFunction(functionName,validationFunction);

Registers a validation function that can be used for custom client-side validation. The custom validation must be added to the field definition in the flow in order for the registered function to actually be invoked.

The function registered with janrain.capture.ui.registerFunction should return true or false, and will be passed the following arguments:

  • elementName - the name of the form element being validated
  • elementValue - the value of the form element being validated
  • validation - a validation object from the Registration widget with some methods for manipulating the element being validated

Below is an example of a custom validation function that enforces a minimum length of 12:

function mustBeAtLeastTwelve(elementName,elementValue){
  returnelementValue.length >= 12;
}
janrain.capture.ui.registerFunction('mustBeAtLeastTwelve',mustBeAtLeastTwelve);

renderScreen

janrain.capture.ui.renderScreen(screenName[,noScreenHistory]);

Renders a screen with the Registration widget. screenName must be the name of a screen defined in the flow. If noScreenHistory is set to true, the current screen will not be available via the back button within the new screen.

scriptLoader

janrain.capture.ui.scriptLoader(scriptSource[,callbackFunction]);

A lightweight utility for loading additional scripts after initial page load that provides functionality for callbacks and timeouts. scriptSource should be an absolute URL. The callbackFunction can be specified initially or later via the setCallback method. The script will not be loaded until the load method is called.

Below is a full example illustrating how scriptLoader can be used to load somelib.js, but times out after 500 milliseconds:

functioncallbackSuccess(){
  console.log('Success!');
}
functiontimeoutCallback(errorEvent){
  console.error('Oh no! A bad thing happened:',errorEvent);
}
varscriptSource = 'https://www.somecdn.com/somelib.js'
janrain.capture.ui.scriptLoader(scriptSource)
  .setCallback(callbackSuccess)
  .setTimeoutCallback(timeoutCallback)
  .setTimeoutLimit(500)
  .load();

setCustomHtml

janrain.capture.ui.setCustomHtml(builtInScreenName,htmlString);

Allows you to overwrite the default inner HTML content of the built-in Registration widget screens. The following built-in screens can be overwritten:

  • accessDenied
  • dialog
  • retrievingUserData

setFieldAttribute

janrain.capture.ui.setFieldAttribute(fieldName,attributeName,attributeValue);

Sets a specified attribute on a field. This method can be called before the form is rendered, and the Registration widget will set the attribute appropriately.

setNoReturnExperience

janrain.capture.ui.setNoReturnExperience();

Disables the greeting for returning customers that re-authenticate.

setValidator

janrain.capture.ui.setValidator(validationName,validatorFunction);

Allows you to override one of the built-in validator functions. Below is a list of valid values for validationName:

  • hasValue
  • isDate
  • isValidMinYears
  • isValidMinLength
  • isValidMaxLength
  • isValidMaxNumericLength
  • isValidFormat
  • isValidMatch
  • isUnique

start

janrain.capture.ui.start([flowUrl]);

Initializes the Registration widget. It should be called once within the janrainCaptureWidgetOnLoad function defined on your page. Optionally accepts an absolute URL for the flow (used only in complex configurations).