Understanding: Lightbox API

Use this guide to add custom Javascript to this Experience. This will be output inline in the page rendering the Experience.

The most common use cases include:

• Tracking and analytics

• Combined use with custom HTML page components

• Bespoke interactive elements

The system platform uses PreactJS and therefore you should not attempt to modify the DOM directly for any system page components (instead, use the provided Customization API methods where available).

Note: Additions made here will only apply to this Experience and will not appear on or affect other Experiences.

You MUST include the opening and closing <script> tags

Available libraries

New Experiences do not currently expose any JS libraries as public, and you may not rely on libraries or versions used by the platform itself. Please include any libraries you need explicitly using a CDN reference.

Namespace

All client side Experience functionality is exposed via the NGX namespace.

For custom code executing directly in the Experience window, this will be available immediately for use.

For custom code executing in a parent window, the NGX namespace will not be available until our Embed script is included and loaded by the browser. We provide a callback function so that logic relying on the NGX object being available can be executed as soon as our namespace is ready.

Example:

window.ngxReadyMicro = function() {
// NGX namespace is ready, execute any dependent code now.
}

Version

New and Legacy format Experiences expose a different version of the NGX API. In order for account wide custom code to interact accordingly we provide a way to check which version is currently running via:

NGX.isVersion(<version>);

Example:

if(NGX.isVersion('2')) {
// Interact with New experience API here.
} else if(NGX.isVersion('1')) {
// Interact with Legacy experience API here.
}

API

In new Experiences, all interaction with our supported custom functionality happens via the API. All API methods are accessed via the following syntax:

NGX.isVersion(<version>);

Events API

Event methods allow you to be notified of specific system events.

• event:listen

  Register a callback function to be executed when a given system event occurs.

  NGX.api('event:listen', <event signature>, <callback>)

  Supported arguments:

  event signature

  One of our supported system events. Please see the Event List section for a complete list.

  callback

  A function to execute when the event occurs.

  Example:

  Copy

  NGX.api('event:listen', 'navigate:before', function(e) {
  console.log('Navigation will occur!');
  console.log(e);
  });

Navigation API

Navigation methods allow you to programatically jump between slides and pages.

• navigation:navigate

  This method allows navigation directly to a given slide or page id (intelligently based on experience display type).

  NGX.api('navigation:navigate', <options>)

  Supported arguments

  Options

  Copy

  {
  id: <slide or page id> (type:number)
  }

  Example:

  Copy

  NGX.api('navigation:navigate', {
  id: 5
  });
  

• navigation:next

  This method navigates to the next slide or page (intelligently based on experience display type).

  NGX.api('navigation:next')

  Supported arguments

  none

  Example:

  Copy

  NGX.api('navigation:next');

• navigation:previous

  This method navigates to the previous slide or page (intelligently based on experience display type).

  NGX.api('navigation:previous')

  Supported arguments

  none

  Example:

  Copy

  NGX.api('navigation:previous');

• navigation:first

  This method navigates to the first slide or page (intelligently based on experience display type).

  NGX.api('navigation:first')

  Supported arguments

  none

  Example:

  Copy

  NGX.api('navigation:first');

• navigation:last

  This method navigates to the last slide or page (intelligently based on experience display type).

  NGX.api('navigation:last')

  Supported arguments

  none

  Example:

  Copy

  NGX.api('navigation:last');

• navigation:set:mode

  This method sets the slide navigation mode to either 'carousel' or 'custom' movement.

  NGX.api('navigation:set:mode', <options>)

  Supported arguments

  options

  Copy

  {
    mode: <specify mode name> (type:string, value: 'carousel' or 'custom', default: 'carousel')
  }

  Example:

  Copy

  NGX.api('navigation:set:mode', { mode: 'custom' });

• navigation:set:axis

  This method sets the slide navigation direction axis to either 'horizontal' or 'vertical'.

  NGX.api('navigation:set:axis', <options>)

  Supported arguments

  options

  Copy

  {
    axis: <specify axis direction> (type:string, value: 'horizontal' or 'vertical', default: 'horizontal')
  }

  Example:

  Copy

  NGX.api('navigation:set:axis', { mode: 'vertical' });

• navigation:cycle:start

  This method initiates an automatic cycle through all slides in the experience.

  NGX.api('navigation:cycle:start', <options>)

  Supported arguments

  options

  Copy

  {
    interval: <time to display each slide in milliseconds> (type:number, default:5000 // 5 seconds),
    direction: <direction to cycle> (type:string, value:forward|reverse, default:forward),
    loop: <enable/disable/define precisely looping behaviour> (type:boolean|number, value:true|false|integer, default:true),
    step: <handler function called at each step> (type:function, arguments:[slide // Current slide id, loop // Current loop iteration]),
    complete: <handler function called when looping completes> (type:function, arguments:[slide // Current slide id, loop // Current loop iteration])
  }

  Example:

  Copy

  // Basic usage, defaults will be used.
  NGX.api('navigation:cycle:start');
  // Simple usage, show each slide for 2 seconds, loop twice.
  NGX.api('navigation:cycle:start', {
  interval:2000,
  loop:2
  });
  // Advanced usage, define custom handler functions for each step and completion.
  NGX.api('navigation:cycle:start', {
  interval:2000,
  direction:'forward',
  loop: 2,
  step: function(slideId, loop){
  console.log('step function called:');
  console.log(loop);
  console.log(slideId);
  },
  complete: function(slideId, loop){
  console.log('complete function called:');
  console.log(loop);
  console.log(slideId);
  }
  });
  

• navigation:cycle:stop

  This method stops the current cycle (if executing).

  NGX.api('navigation:cycle:stop')

  Supported arguments

  none

  Example:

  Copy

  NGX.api('navigation:cycle:stop');

• navigation:get:total:slides

  Returns the total number of slides.

  NGX.api('navigation:get:total:slides')

  Supported arguments

  none

  Example:

  Copy

  var totalSlides = NGX.api('navigation:get:total:slides');
  console.log(totalSlides); // eg. 10

• navigation:get:current:slide:id

  Returns the current slide id.

  NGX.api('navigation:get:current:slide:id')

  Supported arguments

  none

  Example:

  Copy

  var currentSlideId = NGX.api('navigation:get:current:slide:id');
  console.log(currentSlideId); // eg. 5

• navigation:get:current:page:id

  Returns the current page id.

  NGX.api('navigation:get:current:page:id')

  Supported arguments

  none

  Example:

  Copy

  var currentPageId = NGX.api('navigation:get:current:page:id');
  console.log(currentPageId); // eg. 54321

• navigation:get:current:page:name

  Returns the current page name.

  NGX.api('navigation:get:current:page:name')

  Supported arguments

  none

  Example:

  Copy

  var currentPageName = NGX.api('navigation:get:current:page:name');
  console.log(currentPageName); // eg. 'details'

Form API

Form methods allow certain aspects of form behaviour to be customized.

• form:set:field

  This method allows programatic setting of an existing form field.

  NGX.api('form:set:field', <options>)

  Supported arguments

  options

  Copy

  {
  name: <name of the form input> (type:string),
  value: <desired value> (type:string)
  }

  Example

  Copy

  // Here we set an email address.
  NGX.api('form:set:field', {
  name: 'email', // must match the name attribute of the email field
  value: 'joe.bloggs@example.com'
  });
  // Here we set a country field to one of its available options.
  NGX.api('form:set:field', {
  name: 'country', // must match the name attribute of the select field
  value: 'GBR' // must match one of the defined options for the select field
  });
  // Here we set a radio field to one of its available options.
  NGX.api('form:set:field', {
  name: 'radio', // must match the name attribute of the radio group
  value: 'option_1' // must match one of the defined values for the radio group
  });
  

• form:set:hidden:field

  This method allows you to programmatically set an HTML hidden input field in the form as a name and value pair. This field will not be displayed to the user in any way and the user may not modify it. The field name and value set in the hidden field will be submitted with the form data.

  NGX.api('form:set:hidden:field', <options>)

  Supported arguments

  options

  Copy

  {
  name: <name of the form hidden input> (type:string),
  value: <desired value> (type:string)
  }

  Example

  Copy

  // Here we set a value for hidden input, customerLocation.
  NGX.api('form:set:hidden:field', {
  name: 'customerLocation',
  value: 'Planet Earth'
  });

• form:add:submitHandler

  This method allows additional arbitrary logic to be executed before the form is allowed to submit.

  NGX.api('form:add:submitHandler', <options>)

  Supported arguments

  options

  Copy

  {
    id: <unique id> (type:string),
    handler: <handler function> (type:function, arguments:[inputs // All form inputs and their current values]),
    error: <optional error message> (type:string),
  }

  Example:

  Copy

  NGX.api('form:add:submitHandler', {
  id: 'checkRadio',
  handler: function(inputs) {
  // inputs contains all form input fields and their current values.
  if(inputs.radio_1 && inputs.radio_1.value === 'option_3') {
  // valid
  // return true to allow form to submit
  return true;
  } else {
  // invalid
  // return false to prevent form submit
  return false;
  }
  },
  error: 'Error. Please select option 3 to continue.'
  });
  

• form:remove:submitHandler

  This method removes a previously added form submit handler.

  NGX.api('form:remove:submitHandler', <options>)

  Supported arguments

  options

  Copy

  {
  id: <unique id> (type:string)
  }

  Example:

  Copy

  NGX.api('form:remove:submitHandler', {
  id: 'checkRadio'
  });

• form:set:customerid

  This method allows a non-embedded experience to set an external customer ID and ID type. This customer ID and type will be included with the form data when an entry is submitted. This method should be used in this Custom Javascript settings area.

  IMPORTANT! This value is also stored in hidden input inside the form. We have this method because of backward compatibility, and because this value must be sanitized. If you need non-sanitized value, you should use form:set:hidden:field with ngx_customer_id name instead.

  NGX.api('form:set:customerid', <customerid>, <customeridtype>)

  Supported arguments

  customerid

  An alphanumeric String containing a user-defined customer ID. May also contain hyphens and/or underscores.

  customeridtype

  An alphanumeric String containing the type of customer ID. May also contain hyphens and/or underscores.

  Example:

  Copy

  NGX.api('form:set:customerid', 'jane-doe-987', 'id-type');

• form:get:customerid

  This method allows a non-embedded experience to retrieve a previously-set external customer ID.

  This customer ID is included with the form data when an entry is submitted. This method should be used in this Custom Javascript settings area.

  NGX.api('form:get:customerid')

  Supported arguments

  none

  Example:

  Copy

  var custID = NGX.api('form:get:customerid');

Overlay API

Overlay methods allow overlays to be programatically invoked & dismissed using one of our supported behaviors.

• overlay:open

  Open an overlay.

  NGX.api('overlay:open', <options>)

  Supported arguments

  options

  Copy

  {
    content: <content to display> (type:string|element),
    behaviour: <optional mode of operation> (type:string, value:dialog|full, default:full),
    className: <optional css classnames to append> (type:string)
  }

  Example:

  Copy

  NGX.api('overlay:open', {
  content: '<p>Hello World!</p>',
  behaviour: 'dialog',
  className: 'customOverlay'
  });

• overlay:close

  Closes a previously opened overlay.

  NGX.api('overlay:close')

  Supported arguments

  none

  Example:

  Copy

  NGX.api('overlay:close');

Captcha API

Captcha methods allow Captcha prompts to be programatically invoked & dismissed.

• captcha:open

  Open an overlay containing a Captcha prompt.

  NGX.api('captcha:open', <options>)

  Supported arguments

  options

  Copy

  {
    message: <optional message to display> (type:string),
    responseHandler: <handler function called when user completes Captcha> (type:function, arguments:[responseToken // Captcha response token]),
    closeHandler: <handler function called when Overlay is closed> (type:function, arguments:[captchaCompleted // Boolean indicating if captcha was successfully completed before overlay was closed])
  }

  Example

  Copy

  NGX.api('captcha:open', {
  message:'<p>Are you human?</p>',
  responseHandler:function(responseToken) { console.log(responseToken); },
  closeHandler:function(captchaCompleted) { console.log(captchaCompleted); }
  });

• captcha:close

  Closes a previously opened Captcha prompt.

  NGX.api('captcha:close')

  Supported arguments

  none

  Example:

  Copy

  NGX.api('captcha:close');

Customization API

Customization methods allow certain system generated markup to be modified or extended.

• module:add:customization

  This method allows a given module to have its markup customized, useful if you wish to add persistent additional markup to a module.

  NGX.api('module:add:customization', <options>)

  Supported arguments

  options

  Copy

  {
  id: <module id> (type:string),
  selector: <target element selector> (type:string),
  position: <position to insert> (type:string, value:before|after),
  render: <render function> (type:function)
  }

  Example:

  Copy

  NGX.api('module:add:customization', {
  id: 'headline_1529937686682',
  selector: '.xByline',
  position: 'after',
  render: function() {
  return '<h3 class="xTitle xByline">Here is a custom element</h3>';
  }
  });
  

• module:remove:customization

  This method removes a previously added customization from a given module.

  NGX.api('module:remove:customization', <options>)

  Supported arguments

  options

  Copy

  {
  id: <module id> (type:string)
  }

  Example:

  Copy

  NGX.api('module:remove:customization', {
  id: 'headline_1529937686682'
  });

Embed API

Embed methods allow communication between child and parent windows when an experience is embedded.

For custom code executing in a parent window, the NGX namespace will not be available until our Embed script is included and loaded by the browser. As noticed above, we provide a callback function so that logic relying on the NGX object being available can be executed as soon as our namespace is ready.

Example:

window.ngxReadyMicro = function() {
// NGX namespace is ready, you can use embed methods here
}

• embed:send:message

  This method allows unidirectional sending of arbitrary data "messages" between windows.

  NGX.api('embed:send:message', <message>)

  Supported arguments

  Message

  An object containing arbitray data you wish to send.

  Copy

  {
  // object properties here...
  }

  Example:

  Copy

  NGX.api('embed:send:message', {
  firstName: 'Joe',
  lastName: 'Blogs'
  });

• embed:receive:message

  This method allows unidirectional receiving of arbitrary data "messages" between windows.

  NGX.api('embed:receive:message', <options>)

  Supported arguments

  options

  Copy

  {
    handler: <handler function> (type:function, arguments:[message // The message object]),
  }

  Example

  Copy

  NGX.api('embed:receive:message', {
  handler: function(message) {
  // The message id (corresponds to the iframe id).
  console.log(message.id);
  // The message body.
  console.log(message.body);
  },
  });

• embed:resize

  This method manually initiates a recalculation of the experience content height, then communicates with the parent window to adjust the iframe height accordingly.

  NGX.api('embed:resize')

  Supported arguments

  none

  Example:

  Copy

  NGX.api('embed:resize');

• embed:page:info

  This method retrieves information about the parent page from within an embedded experience, including URL, viewport dimensions, and scroll position.

  NGX.api('embed:page:info', <callback>)

  Supported arguments

  Callback

  A function that receives the page info object with the following properties:

  Copy

  {
  url: <full URL of the parent page> (type:string),
  viewportHeight: <parent viewport height in pixels> (type:number),
  documentHeight: <total document height in pixels> (type:number),
  scrollTop: <current scroll position in pixels> (type:number),
  offsetTop: <iframe offset from document top in pixels> (type:number)
  }

  Example:

  Copy

  NGX.api('embed:page:info', function(pageInfo) {
  console.log('Parent URL:', pageInfo.url);
  console.log('Viewport height:', pageInfo.viewportHeight);
  });

• embed:request:user:context

  This method requests the information about the user from the host page, which can be used to trigger onload integration request. Keep in mind that method does not provide the context immediately: it registers the embed as a context subscriber. When host page is ready to provide the context - all subscribers will be notified, AND all subscriptions will be removed. E.g. to receive new context, you need to request it again.

  NGX.api('embed:request:user:context')

  Supported arguments

  none

  Example:

  Copy

  NGX.api('embed:request:user:context');

  Important! To provide the context from the HOST page, you need to call an API method in the host page. Keep in mind that this API call should be wrapped into ngxReadyMicro callback to ensure that NGX global is available at the moment when context provider will be registered (see the example below).

  NGX.api('register:context:provider', <callback>)

  Supported arguments

  callback

  A function that will be called on the HOST page and should return either an object with the context, or the Promise which will be resolved by the object with the context. This function will be called by the host page for each registered context subscriber (e.g. embed), and will receive campaign id as an argument. It can provide different contexts for different campaigns. The context object should have the next structure: \

  Copy

  {
    onload: <An object which contains parameters for onload integration. If it is presented - the onload integration request will be triggered> (type:object)
    preferOnloadData: <A flag whether we should prefer data from onload integration if it exists. If true - data from onload integration will override the data from context> (type:boolean)
    prefilledValues: <An object with prefilled values (keys - field names). These values will be set in form fields. Use this to provide default values.> (type:object)
    knownFields: <An array with known values, which will be hidden from the user since they may not modify them.> (type:array[string])
  }

  Example:

  Copy

  window.ngxReadyMicro = function() {
  NGX.api('register:context:provider', (campaignId) => {
  return {
  onload: {
  "nc.ol_user_id": "my_user_id",
  "nc.ol_zync_id":"my_zync_id"
  },
  preferOnloadData: false,
  prefilledValues: {
  "email": "samplemail@mail.com",
  },
  knownFields: ["name_Firstname", "name_Lastname"]
  }
  });
  }

• embed:register:context:handler

  This method registers custom context handler and will be called when user context is provided by the host page.

  NGX.api('embed:register:context:handler', <options>)

  Supported arguments

  options

  An object which contains callback function that will be called when the context is provided by the host page, and user-defined id for this handler.

  Example:

  Copy

  NGX.api('embed:register:context:handler', {
  handler: (context) => {
  console.log('Context is received!', context);
  },
  id: "myCustomContextHandler"
  }
  )

• embed:unregister:context:handler

  This method unregisters custom context handler.

  NGX.api('embed:unregister:context:handler', <id>)

  Supported arguments

  id

  User-defined ID of context handler (defined when calling embed:register:context:handler)

  Example:

  Copy

  NGX.api('embed:unregister:context:handler', "myCustomContextHandler")

Animation API

Animation methods allow customization of the various segue behaviours used by default.

• animation:set:page:transition

  This method configures animation properties for transitions between entire pages (eg. after a successful form entry a confirmation page is normally displayed).

  NGX.api('animation:set:page:transition', <options>

  Supported arguments

  options

  An object defining the animation properties.

  Copy

  {

  {
    in: {
      type: <one of our supported segue types. Please see the Animation Type List section for a complete list> (type:string),
      duration: <duration for segue in milliseconds> (type:number),
      delay: <delay before segue begins in milliseconds> (type:number)
    },
    out: {
      type: <one of our supported segue types. Please see the Animation Type List section for a complete list> (type:string),
      duration: <duration for segue in milliseconds> (type:number),
      delay: <delay before segue begins in milliseconds> (type:number)
    }
  }

  Example

  Copy

  // Basic usage. Here we just override the type for the segue in direction. Defaults will be used for any properties not explicitly defined.
  NGX.api('animation:set:page:transition', {
    in:{
      type:'bounceLeft'
    }
  });
  
  // Simple usage, in addition to the segue type, here we also define the duration for the segue.
  NGX.api('animation:set:page:transition', {
    in:{
      type:'bounceLeft',
      duration:750
    }
  });
  
  // Advanced usage, here we define all the previous properties and add a short delay as well. We also provide corresponding properties for the segue out direction.
  NGX.api('animation:set:page:transition', {
    out:{
      type:'bounceRight',
      duration:750,
      delay:350
    },
    in:{
      type:'bounceLeft',
      duration:750,
      delay:350
    }
  });

• animation:set:slide:transition

  This method configures animation properties for transitions between slides.

  NGX.api('animation:set:slide:transition', <options>)

  Supported arguments

  options

  An object defining the animation properties.

  Copy

  {
    in: {
      type: <one of our supported segue types. Please see the Animation Type List section for a complete list> (type:string),
      duration: <duration for segue in milliseconds> (type:number),
      delay: <delay before segue begins in milliseconds> (type:number)
    },
    out: {
      type: <one of our supported segue types. Please see the Animation Type List section for a complete list> (type:string),
      duration: <duration for segue in milliseconds> (type:number),
      delay: <delay before segue begins in milliseconds> (type:number)
    }
  }

  Example:

  Copy

  // Basic usage. Here we just override the type for the segue in direction. Defaults will be used for any properties not explicitly defined.
  NGX.api('animation:set:slide:transition', {
    in:{
      type:'bounceLeft'
    }
  });
  
  // Simple usage, in addition to the segue type, here we also define the duration for the segue.
  NGX.api('animation:set:slide:transition', {
    in:{
      type:'bounceLeft',
      duration:750
    }
  });
  
  // Advanced usage, here we define all the previous properties and add a short delay as well. We also provide corresponding properties for the segue out direction.
  NGX.api('animation:set:slide:transition', {
    out:{
      type:'bounceRight',
      duration:750,
      delay:350
    },
    in:{
      type:'bounceLeft',
      duration:750,
      delay:350
    }
  });

• animation:set:row:transition

  This method configures animation properties for row transitions.

  NGX.api('animation:set:row:transition', <options>)

  Supported arguments

  options

  An object defining the animation properties. Note: rows do not support a segue out direction.

  Copy

  {
    in: {
      type: <one of our supported segue types. Please see the Animation Type List section for a complete list> (type:string),
      duration: <duration for segue in milliseconds> (type:number),
      delay: <delay before segue begins in milliseconds> (type:number)
    }
  }

  Example:

  Copy

  // Basic usage. Here we just override the type for the segue in direction. Defaults will be used for any properties not explicitly defined.
  NGX.api('animation:set:row:transition', {
    in:{
      type:'bounceLeft'
    }
  });
  
  // Simple usage, in addition to the segue type, here we also define the duration for the segue.
  NGX.api('animation:set:row:transition', {
    in:{
      type:'bounceLeft',
      duration:750
    }
  });
  
  // Advanced usage, here we define all the previous properties and add a short delay as well.
  NGX.api('animation:set:row:transition', {
    in:{
      type:'bounceLeft',
      duration:750,
      delay:350
    }
  });

• animation:set:module:transition

  This method configures animation properties for individual elements within specific module types.

  NGX.api('animation:set:module:transition', <moduleType>, <elementType>, <options>)

  Supported arguments

  moduleType

  One of our supported system module types, currently only a few module types are supported, but more will follow. Must be one of:

  • callout

  • headline

  • image

  • video

  elementType

  A supported element type for the targeted module type. Must be one of:

  • copy

  • media

  • cta

  options

  An object defining the animation properties. Note: modules do not support a segue out direction.

  Copy

  {
    in: {
      type: <one of our supported segue types. Please see the Animation Type List section for a complete list> (type:string),
      duration: <duration for segue in milliseconds> (type:number),
      delay: <delay before segue begins in milliseconds> (type:number)
    }
  }

  Example:

  Copy

  // Basic usage. Here we just override the type for the segue in direction of the media element within a callout module. Defaults will be used for any properties not explicitly defined.
  NGX.api('animation:set:module:transition', {
    moduleType:'callout',
    elementType:'media',
    in:{
      type:'bounceLeft'
    }
  });
  
  // Simple usage, in addition to the segue type, here we also define the duration for the segue.
  NGX.api('animation:set:module:transition', {
    moduleType:'callout',
    elementType:'media',
    in:{
      type:'bounceLeft',
      duration:750
    }
  });
  
  // Advanced usage, here we define all the previous properties and add a short delay as well.
  NGX.api('animation:set:module:transition', {
    moduleType:'callout',
    elementType:'media',
    in:{
      type:'bounceLeft',
      duration:750,
      delay:350
    }
  });

Utility API

Various utility methods exposed for convenience.

• util:browser:info

  Provides information on the current browser and operating system.

  NGX.api('util:browser:info')

  Supported arguments

  none

  Example:

  Copy

  var browser = NGX.api('util:browser:info');
  console.log(browser.name); // Chrome
  console.log(browser.version); // 68.0

Viewport API

Sometimes, you can have situations with highly customized campaigns, where the visibility of some content is managed by custom JavaScript code.

Since NextGen Experiences uses lazy loading to improve performance, in this specific circumstance, you may find that client side functionality is not fully enabled (e.g. clicking a checkbox does not display a check). When this happens, you will need to notify the Display API to load appropriate module bundles (for instance, form, quiz, conditional, etc.) when the viewport content has been chanced by custom code.

To do this, use the API call provided below:

NGX.api('viewport:content:changed');

Custom classes API

For some cases, you may want to add custom CSS classes to modules. It cannot be done directly, through interaction with real DOM node, because our DOM nodes are renedered by React, and custom classes will be lost when component re-renders.

To achieve this, you can use these two API methods:

• module:add:custom:classes

  This method adds custom classes to CLOSEST DOM node with class xComponent. Custom classes will have prefix xCustomClass-

  NGX.api('module:add:custom:classes', '<options>')

  Supported arguments

  options

  Copy

  {
    id: <Optional. Module Id (which is set in data-ngx-id attribute)> (type:string),
    selector: <Optional. CSS selector to find the real DOM node> (type:string),
    customClassNames: <Custom className, OR array with classNames> (type:string|string[]),
  }

  This method finds the DOM node either by data-ngx-id attribute equals to options.id, or DOM nodes by CSS selector in options.selector. Then it finds CLOSEST nodes with xComponent class for each found node, and adds custom classes to this node. They will be preserved between the rerenders.

  Example:

  Copy

  // Basic usage. Add custom class myClass to module with ID=radio_12987654.
  NGX.api('module:add:custom:classes', {
    id: 'radio_12987654',
    customClassNames: 'myClass'
  });
  // The result: module with data-ngx-id='radio_12987654' has class 'xCustomClass-myClass'
  
  // Add custom classes myClass1, myClass2 to modules which contain input with type='radio'
  NGX.api('module:add:custom:classes', {
    selector: 'input[type="radio"]',
    customClassNames: ['myClass1', 'myClass2']
  });
  // The result: nodes with class 'xComponent' which contain input[type="radio"] have classes 'xCustomClass-myClass1', 'xCustomClass-myClass2'
  

• module:remove:custom:classes

  This method removes custom classes to CLOSEST DOM node with class xComponent.

  NGX.api('module:remove:custom:classes', '<options>');

  Supported arguments

  options

  Copy

  {
    id: <Optional. Module Id (which is set in data-ngx-id attribute)> (type:string),
    selector: <Optional. CSS selector to find the real DOM node> (type:string),
    customClassNames: <Custom className, OR array with classNames> (type:string|string[]),
  }

  This method finds the DOM node either by data-ngx-id attribute equals to options.id, or multiple DOM nodes by CSS selector in options.selector. Then it finds CLOSEST node with xComponent class for each found node, and removes custom classes from this node.

Form Module Custom validation API

If embedded validation is not enough, you can implement your own validation for particular modules (Email, Phone). You can provide either syncronous validation function, which returns boolean (valid/invalid), or asyncronous function which returns Promise. This Promise should be resolved by validation result (boolean). Async validation can be applicable when you use 3rd-party validation service.

Custom validation will be called by our standard platform validation process, AFTER the standard validation passes. If the standard validation fails, the custom validation will not be called. Keep in mind that async validation blocks form submission. So while the async validation is running, the entry cannot be submitted.

Attention! You need to be sure that DOM node which renders your module exists, when you run custom validation!

• module:add:custom:validation

  This method adds custom validation to particular module (only Email or Phone are supported now!)

  NGX.api('module:add:custom:validation', '<options>');

  Supported arguments

  options

  Copy

  {
    id: <Optional. Module Id (which is set in data-ngx-id attribute)> (type:string),
    selector: <Optional. CSS selector to find the real DOM node> (type:string),
    error: <Error text which should under the module be shown if custom validation fails> (type:string),
    validator: <Function for custom validation> (type:function(value: string) -> boolean | Promise<boolean>),
  }

  Function validator will be called if module passes usual validation. It will receive the module value in its first argument, module id as second one, and should return either boolean or Promise which will be resolved by boolean

  Example:

  Copy

  // Basic usage. Add custom validation to module with ID=email_12345678.
  NGX.api('module:add:custom:validation', {
    id: 'email_12345678',
    error: 'Something is wrong with this email!',
    validator: function(value, moduleId) {
      return value === 'test@mail.com';
    }
  });
  
  // Add custom Add custom async validation to module with ID=email_12345678.
  NGX.api('module:add:custom:validation', {
    id: 'email_12345678',
    error: 'Something is wrong with this email!',
    validator: function(value, moduleId) {
      return new Promise( resolve => {
        // Add your async validation (for example, 3rd-party service request) here
        setTimeout(resolve, 1500, value === 'test@mail.com');
      });
    }
  });

• module:remove:custom:validation

  This method removes custom validation function from module.

  NGX.api('module:remove:custom:validation', '<options>');

  Supported arguments

  options

  Copy

  {
  id: <Module Id (which is set in data-ngx-id attribute)> (type:string)
  }

  This method removes custom validation (added by 'module:add:custom:validation') from the module.

Onload integration

User can trigger onload integration request to request known user data and prefill some fields

NGX.api('send:onload:integration:request', '<options>');

Supported arguments

options

// Basic usage. Trigger onload integration request with additional params
NGX.api('send:onload:integration:request', { "nc.ol_user_id": "1234", "nc.ol_zync_id": "abcd" } );

Event list

The following system events are currently raised and can be listened to via the Events API:

{
  id: <slide or page id>,
  type: <navigation type>,
}

{
  id: <slide or page id>,
  type: <navigation type>,
}

{
  inner: <dom element reference to overlay inner element>
}

{
  type: <tracking event type>,
  params: <object containing any data that was tracked>
}

{
  id: <id of the module that re-rendered>
}

{
  id: <unique entry id>
  uid: <user id>
  nxg_ext_id: <external customer id >
}

Animation Type list

The following animation segue types are currently supported and can be used when customizing animations using the Animation API: