Advanced Widget Configuration

Provided that you have some JavaScript or jQuery experience, the widget allows you to use it in more advanced ways. It’s built to provide an easily extendable and customizable experience. Below you will find several topics describing how to extend the widget. Additionally, there is an index of the events and a public API available from the widget.

Creating custom feedback handlers

The widget provides a basic feedback UI by default and gives you several ways to customize this feedback. However, in some instances, you may want to customize how this feedback is presented to the user. We’ve built the widget with this scenario in mind, allowing you to not only disable the default feedback, but also create your own using events dispatched from the fields.

To disable the default feedback set the feedback option to false.

The following is a code snippet to create a feedback handler that will attach itself to any field registered to the widget – either programmatically or automatically.

/**
 * Hook into field registration events
 * The nb:registered event is fired on the body every time
 * _nb.fields.registerListener is called and during page load for
 * each field auto registered.
 *
 * All `nb:` prefixed events contain a `detail` object
 * with the following params:
 *   `id` - a reference ID for the field & form
 *   `result` - a result object
 *   `error` - error object from request
 */
document.querySelector('body').addEventListener('nb:registered', function (event) {

    // Get field using id from registered event
    let field = document.querySelector('[data-nb-id="' + event.detail.id + '"]');

    // Handle clear events (input has changed or an API error was returned)
    field.addEventListener('nb:clear', function(e) {      
      	// Check for errors
      	if (e.detail.result && e.detail.result.isError()) {
          	if (e.detail.result.isThrottled()) {
            	// Do stuff when the verification is throttled
            }
          
          	// Do stuff when other API errors occur
          	// - Our recommendation is to hide any loaders and treat these emails the same way you would treat an Unknown email
        }
      
        // Do stuff when input changes, (e.g. hide loader)
    });

    // Handle loading status (API request has been made)
    field.addEventListener('nb:loading', function(e) {
        // Do stuff while waiting on API response
    });

    // Handle results (API call has succeeded)
    field.addEventListener('nb:result', function(e) {
      	if (e.detail.result.is(_nb.settings.getAcceptedStatusCodes())) {
            // Do stuff for good email
        }
        else {
            // Do stuff for bad email
        }
    });

    // Handle soft results (fails regex; doesn't bother making API request)
    field.addEventListener('nb:soft-result', function(e) {
        // Do stuff when input doesn't even look like an email (i.e. missing @ or no .com/.net/etc...)
    });
});

Registering fields after page load

By default, the widget will pick up on any fields using the “email” type or the “data-nb” attribute. However, this only works on fields that are present in the DOM during the initial page load. Fields added to the page’s DOM after the page has been loaded will need to be registered with the widget programmatically.

To register a field, you must call the registerListener method once the field has been added to the page’s DOM. See below:

// Get the DOM node
var field = document.querySelector('#my-field');

// Register field with the widget and broadcast nb:registration event
// If ommitted the second argument will assume the value of true
_nb.fields.registerListener(field, true);

If the second argument is set to true, the nb:registration JavaScript event will be broadcasted from the field during registration. Any existing feedback listeners wrapped in a nb:registration event listener (if enabled this includes the default feedback) will then be attached to the field.

Setting this argument to false will prevent the event from being broadcasted, allowing you to create a unique feedback handler for this field. See the section below for more information on creating unique feedback for fields.

If you need to remove your field from the DOM, such as in a single page application, it’s good practice to unregister your fields first. To do this, use the unregisterListener method just prior to removing the field from the DOM. See below:

// Get the DOM node
var field = document.querySelector('#my-field');

// Unregister field with the widget
_nb.fields.unregisterListener(field);

// Now it's safe to remove the field

Creating unique feedback methods for each field

On occasion, you may need to have multiple fields using different feedback handlers on the same page. This can be accomplished by disabling the default feedback and attaching event handlers to each field (similarly to the “Creating custom feedback handlers” section above) or by registering fields without broadcasting the nb:registration event.

First, either disable the default feedback by setting the feedback option to false or add a new field to the DOM and register it with registration broadcasting turned off. See the example below for registering a field with broadcasting disabled:

// Get the DOM node
var field = document.querySelector('#my-field');

// Register field with the widget and disable nb:registration broadcasting
_nb.fields.registerListener(field, false);

Next, use the following snippet for each field to create feedback handlers.

// Get field using id from registered event
let field = document.querySelector('[data-nb-id="' + event.detail.id + '"]');

// Handle clear events; i.e. hide feedback
field.addEventListener('nb:clear', function(e) {
    // Do stuff when input changes or when API responds with an error
});

// Handle loading status (API request has been made)
field.addEventListener('nb:loading', function(e) {
    // Do stuff while waiting on API response
});

// Handle results (API call has succeeded)
field.addEventListener('nb:result', function(e) {
    // Check the result
    if (e.detail.result.is(_nb.settings.getAcceptedStatusCodes())) {
        // Do stuff for good email
    }
    else {
        // Do stuff for bad email
    }
});

// Handle soft results (fails regex; doesn't bother making API request)
field.addEventListener('nb:soft-result', function(e) {
    // Do stuff when input doesn't even look like an email (i.e. missing @ or no .com/.net/etc...)
});