JavaScript Widget 3.0 For Developers

Overview
Getting Started
- How to ensure JS widget loaded
- Debug Mode
Basic Configuration

JavaScript Widget 3.0 - Developer Documentation

While the JS Widget is designed for easy use—requiring only a simple copy-paste and no coding—there are several advanced features available through the JS Widget SDK that can be utilized on the client side. These capabilities are intended for advanced users who are comfortable writing and customizing JavaScript code.

Note: Writing incomplete or syntactically incorrect code can break Clearout's JS Widget functionality on your forms. Always test custom scripts thoroughly in a sandbox environment before deploying them to production.

Getting Started with the Basics

How to ensure the Clearout's JS has loaded correctly on the page?

Once you've added Clearout's JS code to your page, refresh the page and open the browser console.

You should see the below mentioned log message indicating that Clearout's SDK has been successfully initialized along with the version.

Console log showing Clearout SDK initialization

This log ensures that the widget is active and ready to perform validations on your page.

Enabling debug mode & inspect options

Enabling Debug Mode provides detailed and descriptive logs in the browser console. These logs include insights such as:

Field detection and validation processes
API request and response details
Error messages and warnings
Performance metrics

To enable debug mode, you can override the options in your JavaScript code:


                  <script>
                      function onCoJSScriptLoaded() {
                        console.log('Clearout JS Loaded - Overriding Options!!');
                        window.clearout.options.debug = true
                        window.clearout.options.inspect = true
                      }
                  </script>
                  <script id="clearout-js-widget" src="https://clearout.io/jswidget/{your_app_id}" async onload="onCoJSScriptLoaded()"></script>

Note: Debug mode should only be enabled in development environments as it may impact performance and expose sensitive information.

Basic Configuration

Overriding Options

In JS Widget 3.0, app settings are managed through the Clearout Dashboard. However, you can override these settings on the client side if needed. For example:


                  <script>
                    function onCoJSScriptLoaded() {
                      console.log('Clearout JS Loaded - Overriding Options!!');
                      window.clearout.options.mode = 'formSubmit'
                      window.clearout.options.email.block_free_account = true
                      window.clearout.options.email.feedback_free_account_message = 'Free email accounts are not allowed :('
                    }
                  </script>
                  <script id="clearout-js-widget" src="https://clearout.io/jswidget/{your_app_id}" async onload="onCoJSScriptLoaded()"></script>

This will force the JS Widget to use FormSubmit mode and block free email accounts, regardless of the dashboard settings.

Advanced Override Options

The following options can only be set through client-side overrides and are not available in the app setup. These options provide advanced customization capabilities but should be used with caution.

Warning: Improper usage of these override options can cause scripts to break. Always thoroughly test in a sandbox environment before deploying to production.

1. Custom Form Selection

The window.clearout.options.form_elements option allows you to specify which form elements on the page require validation. This is particularly useful for div-based or non-standard forms or custom form implementations.

window.clearout.options.form_elements = [
  {selector:'#custom-form-container'}, // treats this id selector as a form with default widget options
  {selector: '.dynamic-form-wrapper', options: {mode: 'formSubmit'}}, // treats this class selector as a form with formSubmit mode
  {selector: '[data-form-type="custom"]', options: {mode: 'ajax', email: {block_free_account: true}}} // treats this data-form-type attribute selector as a form with ajax mode and blocks free email accounts
];

2. Pre-filled Value Validation

The window.clearout.options.prefill_validation option enables validation of pre-filled values in form fields. This is useful when forms are pre-populated with data and you want to validate these values immediately.

window.clearout.options.prefill_validation = true;

3. Built-in Error Message Suppression

The window.clearout.options.suppress_form_builtin_error_message_selector option allows you to specify selectors for form elements whose built-in error messages should be suppressed. This helps prevent duplicate error messages when using Clearout's validation.

window.clearout.options.suppress_form_builtin_error_message_selector = '.form-error-message, .validation-message';

4. Phone Field Overlay

The window.clearout.options.phone.overlay option enables Clearout to create an enriched phone UI component over your form's existing phone field. This provides enhanced validation and formatting capabilities.

window.clearout.options.phone.overlay = true;

5. Form Discovery

The form discovery options allow you to configure the duration and interval for form discovery. This is useful when you have forms that are dynamically loaded on the page.


                    window.clearout.options.form_discovery_duration = 15000; // Max allowed time to discover forms on page, set to -1 for infinite
                    window.clearout.options.form_discovery_interval = 500; // Interval between form discovery attempts

Disabling Validation on Particular Fields

In some cases, you may want to exclude certain fields from Clearout's validation. This is particularly useful when you have duplicate fields (like email and confirm email) where validating both fields would be redundant.

To disable validation on a specific field, simply add the data-clearout-validation-disable attribute to the field element. The JS Widget will automatically ignore any fields with this attribute.

<form id="signup-form">
  <input type="email" name="email" placeholder="Enter your email">
  <input type="email" name="confirm_email" placeholder="Confirm your email" data-clearout-validation-disable>
  <button type="submit">Sign Up</button>
</form>

Note: This attribute is particularly useful for:

Confirm email fields
Hidden fields that don't require validation
Fields that are handled by other validation systems
Fields that are temporarily disabled or read-only

Available Options

Here are all the configurable options available in the Clearout JS Widget:

                  
                    window.clearout.options = {
                      api_url: config.API_URL,
                      timeout: 10,
                      mode: 'ajax',

                      on_ready: null,
                      form_elements: [], // changed
                      suppress_form_builtin_error_message_selector: null,

                      submit_button_cursor_style: 'pointer',
                      submit_button_selector: null,

                      auto_validation: true,
                      prefill_validation: false,

                      recaptcha_site_key: null,
                      feedback_google_recaptcha: 'Google Recaptcha Verification Failed',

                      inspect: false,
                      debug: false,
                      
                      email: {
                        elements: [],
                        enabled: true,

                        allow_safe_to_send_yes: false, // changed
                        
                        block_role_account: false,
                        block_free_account: false,
                        block_disposable_account: true,
                        block_unknown_status: false,
                        block_catchall_status: false,
                        block_gibberish_account: false,
                        block_form_submission_on_timeout: false,
                        block_form_submission_on_limit_crossed: false,

                        feedback: true,
                        optional: false,
                        selector: null,
                        
                        on_before_verify: null,
                        on_after_verify: null,

                        suggest_email: false,
                        suggest_email_message_template: 'Did you mean __SUGGESTED_EMAIL_ADDRESS__?',

                        feedback_invalid_classname: 'co-error-msg',
                        feedback_invalid_message: 'Invalid email address',
                        feedback_role_account_message: 'Invalid - Role account not allowed',
                        feedback_free_account_message: 'Invalid - Free account not allowed',
                        feedback_disposable_account_message: 'Invalid - Disposable account not allowed',
                        feedback_unknown_message: 'Unable to verify the email address, try after sometime',
                        feedback_catchall_message: 'Catch All email not acceptable, please enter a different email address',
                        feedback_gibberish_message: 'Invalid - Gibberish email address not allowed',
                        feedback_safe_to_send_only_message: 'Please enter different email, entered email is not safe',
                        feedback_on_timeout_message: 'Email could not be verified - timeout occurred',
                        feedback_on_usage_limit_crossed_message: 'Unable to verify the email address, usage limit crossed',
                      },

                      phone: {
                        elements: [],
                        enabled: false,

                        block_mobile_numbers: false,
                        block_landline_numbers: false,
                        block_toll_free_numbers: false,
                        block_voip_numbers: false,
                        block_unknown_type: false,
                        block_form_submission_on_timeout: false,
                        block_form_submission_on_limit_crossed: false,

                        selector: null,
                        optional: false,
                        
                        on_before_verify: null,
                        on_after_verify: null,

                        feedback: true,
                        feedback_invalid_message: 'Invalid phone number',
                        feedback_invalid_classname: 'co-phone-error-msg',
                        feedback_mobile_message: 'Invalid - Mobile numbers not allowed',
                        feedback_landline_message: 'Invalid - Landline numbers Not allowed',
                        feedback_toll_free_message: 'Invalid - Toll Free numbers not allowed',
                        feedback_voip_message: 'Invalid - VOIP numbers not allowed',
                        feedback_unknown_message: 'Invalid - Unknown numbers not allowed',
                        feedback_on_timeout_message: 'Phone Number could not be verified - timeout occurred',
                        feedback_on_usage_limit_crossed_message: 'Unable to verify the phone number, usage limit crossed',
                      },

                      name: {
                        elements: [],
                        enabled: false,
                        gibberish_threshold: 'high',

                        block_gibberish_name: true,
                        block_form_submission_on_timeout: false,
                        block_form_submission_on_limit_crossed: false,

                        selector: null,
                        optional: false,
                        on_before_verify: null,
                        on_after_verify: null,
                        
                        feedback: true,
                        feedback_invalid_message: 'Invalid name',
                        feedback_invalid_classname: 'co-name-error-msg',
                        feedback_gibberish_message: 'Invalid - Gibberish name not allowed',
                        feedback_on_timeout_message: 'Name could not be verified - timeout occurred',
                        feedback_on_usage_limit_crossed_message: 'Unable to verify the Name, usage limit crossed',
                      }
                    }

Module	Setting	Type	Default Value	Description

Customizing Styles and CSS

All UI components created by the Clearout JS Widget come with properly namespaced CSS classes, making it easy to target and customize their appearance using your own styles.

Below is a list of all elements and their associated class names:

co-input-container: This is the main wrapper div, which is wrapped around the respective input container.
co-loader-container: This is the loader container, which is placed on top of the container.
co-loader-img-container: This is the loader image's container, which basically contains the Tick, cross or the loader.
co-feedback-container: This is the container which contains the feedback elements and is positioned just below the input container.
co-feedback-msg: This is the container containing the actual feedback message.

Using the Validators

All of Clearout's built-in validators are exposed under the global window.clearout object. This allows advanced users to directly access and invoke the verify method of each validator, enabling deeper integration or custom validation logic in your application.

For example, you can manually trigger a validation like this:


                  let emailValidationResponse = await window.clearout.emailValidator.verify({ email: '[email protected]' })
                  console.log('Email Validation Response: ', emailValidationResponse.result)

                  let phoneValidationResponse = await window.clearout.phoneValidator.verify({ phone: '+918220154838' })
                  console.log('Phone Validation Response: ', phoneValidationResponse.result)

                  let nameValidationResponse = await window.clearout.nameValidator.verify({ name: 'Nishanth Babu' })
                  console.log('Name Validation Response: ', nameValidationResponse.result)

Using these exposed validation methods, you can verify the data in runtime alongside your client side logics to determine the status of data points at any point in your workflows.

Using the Form Component

To manually attach the Clearout JS Widget to specific forms using the SDK, you can use the globally available FormValidator class. This allows you to create an instance of the widget directly on a jQuery form object, offering precise control over which forms are initialized and how.

You can do this by instantiating FormValidator with two parameters: the jQuery form object and a custom options object. These options can either be inherited from the globally available window.clearout.options or fully customized as per your requirements.

new window.clearout.FormValidator(clearout.$('#testform'), clearout.options)

JS Widget Callback Hooks

The Clearout JS Widget currently supports three types of callback hooks that allow you to extend and customize the validation process:

on_ready
Triggered when the Clearout JS SDK is fully loaded and initialized on the page.
on_before_verify
Triggered just before the input data is sent to Clearout for validation.
on_after_verify
Triggered immediately after Clearout returns the validation response.

Note: The on_before_verify and on_after_verify hooks are field-specific and are individually available for email, phone, and name validations. This allows you to apply fine-grained logic tailored to each input type.

on_ready callback

The on_ready callback is executed once the Clearout JS Widget SDK has fully loaded and initialized on the page. This hook is particularly useful for running initialization logic that needs to execute once the widget is ready.

Common use cases include:

Applying custom CSS or styling to widget elements
Adding specific data attributes to input fields
Running setup scripts that depend on the widget being initialized

This callback guarantees that all globally scoped variables—such as validators and configuration options—are accessible and fully initialized, ensuring a safe point to begin custom interactions with the widget.

on_before_verify callback

The on_before_verify callback is triggered just before the field data is sent to Clearout for validation. This hook is ideal for performing custom pre-validation checks on the input data.

Function Parameters

The callback receives a destructured object:

email, phone, or name: The actual value being entered in the field
$form: The jQuery-wrapped form element

The Function is expected to return an object with is_acceptable (true/false) and an error_msg string. If is_acceptable is set to false, the field will not be submitted, and the provided error_msg will be displayed to the user.

This gives you complete control to add pre-checks or filters before Clearout runs its own verification logic.

function ({ email, $form }) {
  let is_acceptable = true
  let error_msg = null
  console.log('Debug: OnBeforeVerify hook is called: ', { email, $form })

  // Your Logic goes here
  // a simple account length check
  let acctName = email.split('@')[0]
  if (acctName.length > 25) {
    is_acceptable = false
    error_msg = 'Email is too long! pls try a shorter email.'
  }
  return ({ is_acceptable, error_msg })
}

on_after_verify callback

The on_after_verify callback is triggered after Clearout returns a response for the field's validation. This hook is particularly useful for performing any post-verification checks, triggering workflows, or making UI changes based on the validation outcome.

Function Parameters

The callback receives a destructured object:

email, phone, or name: The actual value being entered in the field
$form: The jQuery-wrapped form element
result: The verification response

This gives you complete control to add post-checks or filters after Clearout runs its own verification logic.

function ({ phone, $form, result }) {
  let is_acceptable = true
  let error_msg = null
  console.log('Debug: OnBeforeVerify hook is called: ', { phone, $form, result })

  // Your Logic goes here
  // A Sample logic to determine the length of phone number
  if (phone.length !== 10) {
    error_msg = 'Invalid Phone number not allowed!'
    is_acceptable = false
  }
  return ({ is_acceptable, error_msg })
}