Motor Finance Application Form Widget

Comprehensive Developer Guide

v1.0

Table of Contents

Overview

The Motor Finance Application Form Widget is a plug-and-play JavaScript solution that renders a multi-step finance application form with company-specific theming and configuration. It's designed to be embedded in any website and provides a seamless user experience for motor finance applications.

🚀 Easy Integration

Simple setup with minimal configuration required. Works with any modern web framework.

📊 Multi-step Form Wizard

Progressive form completion with progress tracking and step navigation.

✅ Real-time Validation

Instant field validation with error messaging and form state management.

📱 Responsive Design

Mobile-first design that works perfectly on all devices and screen sizes.

🎨 Theme Configuration

Company-specific branding with custom colours, fonts, and logos.

📱 Mobile Responsive

Optimised for all screen sizes with touch-friendly interface.

🔗 Event System

Comprehensive event system for integration with external applications.

Advanced Features

  • Dynamic Error Handling: Automatic error code extraction and conditional contact links
  • Success Management: Customisable success callbacks and panel display
  • Form Interaction Tracking: Comprehensive analytics and user behaviour monitoring
  • Session Management: Secure session handling and data persistence
  • Device Detection: Automatic device and browser information collection
  • Validation Analytics: Error counting and form completion time tracking

Installation

Prerequisites

  • jQuery 3.6.0 or higher
  • dropdownDatepicker plugin (for date fields)

1. Include Dependencies

<!-- jQuery (required) -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>

<!-- dropdownDatepicker plugin (required for date fields) -->
<script src="https://apply.kyiper.com/assets/js/scripts/jquery-dropdown-datepicker.js"></script>

<!-- Kyiper Form Widget -->
<script src="https://apply.kyiper.com/assets/js/kyiper-form-widget.js"></script>

2. Create a Container

<div id="kyiper-form-container"></div>

3. Initialise the Widget

const widget = new KyiperFormWidget.init({
    companyId: 'your-client-id',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://your-api-domain.com'
});
Note: The widget requires jQuery for date field functionality and the dropdownDatepicker plugin for enhanced date selection.

Basic Setup

Minimal Configuration

const widget = new KyiperFormWidget.init({
    companyId: 'your-client-id',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://api.example.com'
});

Complete Example

<!DOCTYPE html>
<html>
<head>
    <title>Motor Finance Application</title>
    <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
    <script src="https://apply.kyiper.com/assets/js/scripts/jquery-dropdown-datepicker.js"></script>
    <script src="https://apply.kyiper.com/js/kyiper-form-widget.js"></script>
</head>
<body>
    <div id="kyiper-form-container"></div>
    
    <script>
        const widget = new KyiperFormWidget.init({
            companyId: 'your-client-id',
            containerId: 'kyiper-form-container',
            apiBaseUrl: 'https://api.example.com'
        });
    </script>
</body>
</html>

Configuration Options

Parameter Type Default Description
companyId string Required Unique identifier for the company. This is the Client Id which can be found under Company Information in the Dashboard Settings.
containerId string Required ID of the HTML container element
LOAD_TIMEOUT number 15000 API request timeout in milliseconds
RETRY_ATTEMPTS number 3 Number of retry attempts for failed requests
RETRY_DELAY number 1000 Delay between retry attempts in milliseconds
customerReference string '' Unique identifier for a customer or dealership. For motor channel partners, this represents unique dealer IDs. For individual dealerships, this represents unique end customer IDs.
customerName string '' Name of the customer or dealership. Required if customerReference is provided.

Customer Configuration

The widget supports optional customer identification through customerReference and customerName parameters. These are particularly useful for tracking applications from specific dealerships or customers.

Customer Reference Usage

The customerReference serves as a unique identifier that can represent different entities depending on your business model:

🏢 Motor Channel Partners

Use customerReference to identify unique dealership IDs within your network. This helps track which specific dealership the application originated from.

👤 Individual Dealerships

Use customerReference to identify unique end customer IDs. This helps track individual customers making applications through your dealership.

Validation Rules

Important: If customerReference is provided (not empty), then customerName becomes required. The widget will throw an error during initialization if this validation fails.

Usage Examples

Motor Channel Partner Example

const widget = new KyiperFormWidget.init({
    companyId: 'your-client-id',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://api.example.com',
    customerReference: 'DEALER_001',  // Unique dealership ID
    customerName: 'ABC Motors Ltd'    // Dealership name
});

Without Customer Data (Standard Usage)

const widget = new KyiperFormWidget.init({
    companyId: 'your-client-id',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://api.example.com'
    // customerReference and customerName are optional
});

Error Handling

If you provide customerReference without customerName, the widget will throw an error during initialization:

Error: customerName is required when customerReference is provided
Note: Both customerReference and customerName are optional by default. The validation only applies when customerReference is explicitly provided.

Theme Configuration

Theme configuration allows for company-specific branding and styling.

Theme Properties

Property Type Description Example
buttonColor string Primary button background colour '#004fa9'
buttonFontColor string Primary button text colour '#ffffff'
bodyFontFamily string Font family for form text 'Arial, sans-serif'
contactUrl string Contact page URL for error messages 'https://example.com/contact'
logo object Company logo configuration See Logo Configuration

Logo Configuration

{
  "logo": {
    "url": "https://example.com/logo.png",
    "alt": "Company Logo",
    "width": 200,
    "height": 60
  }
}

Callback Functions

Success Callback

Called when the form is successfully submitted.

window.KyiperFormWidget.onSuccess = function(data) {
    console.log('Application submitted:', data);
    // Handle successful submission
    // data.applicationId - Generated application ID
    // data.submittedAt - Submission timestamp
    // data.status - Always 'submitted'
    // data.data - Full server response
};

Error Callback

Called when form submission fails.

window.KyiperFormWidget.onError = function(data) {
    console.log('Submission failed:', data);
    // Handle submission error
    // data.error - Error message
    // data.submittedAt - Error timestamp
    // data.status - Always 'error'
};
Note: If no callbacks are configured, the widget will display built-in success or error panels.

Error Handling

Error Panel Display

When no error callback is configured, the widget displays an error panel with:

  • Dynamic error code extraction
  • Conditional contact link (based on theme config)
  • Professional error messaging

Error Code Extraction

The widget automatically extracts error codes from:

  • error.status - HTTP status code
  • error.statusCode - Alternative status code
  • error.code - Generic error code
  • HTTP message parsing (e.g., "HTTP 404: Not Found")

Error Message Examples

HTTP Error 404. Resource not found. contact us
HTTP Error 500. Database connection failed. contact us
HTTP Error 422. Validation failed. contact us

Success Handling

Success Panel Display

When no success callback is configured, the widget displays a success panel with:

  • Success confirmation message
  • Checkmark icon
  • "Thank you for submitting your application" message

Success Panel Structure

<div class="form-panel">
    <div class="document-upload-success-part common-portal-panel">
        <div class="application-document justify-content-center flex-wrap flex-column">
            <div class="body-text">
                <span>Successfully Submitted!</span>
            </div>
            <div class="uploaded-image-box">
                <div class="body-text">
                    <!-- Success SVG icon -->
                    <p>Thank you for submitting your application.</p>
                </div>
            </div>
        </div>
    </div>
</div>

Examples

Basic Implementation

const widget = new KyiperFormWidget.init({
    companyId: 'your-client-id',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://api.example.com'
});

With Callbacks

// Success callback
window.KyiperFormWidget.onSuccess = function(data) {
    // Redirect to success page
    window.location.href = '/success';
};

// Error callback
window.KyiperFormWidget.onError = function(data) {
    // Show custom error message
    alert('Application failed: ' + data.error);
};

// Initialise widget
const widget = new KyiperFormWidget.init({
    companyId: 'your-client-id',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://api.example.com'
});

Advanced Configuration

const widget = new KyiperFormWidget.init({
    companyId: 'your-client-id',
    containerId: 'kyiper-form-container',
    apiBaseUrl: 'https://api.example.com',
    LOAD_TIMEOUT: 20000,
    RETRY_ATTEMPTS: 5,
    RETRY_DELAY: 2000,
    customerReference: 'DEALER_001',
    customerName: 'ABC Motors Ltd'
});

Troubleshooting

Common Issues

Widget Not Loading

Problem: Widget doesn't appear or shows errors
Solution: Check that all required files are loaded and the container element exists

API Connection Issues

Problem: "Failed to load form schema" errors
Solution: Verify API URL, endpoints, and CORS settings

Theme Not Applied

Problem: Default styling appears instead of company theme
Solution: Verify companyId is correct and theme configuration API response

Form Validation Issues

Problem: Validation not working as expected
Solution: Check form schema validation rules and required field configuration

Debug Mode

Enable debug logging by setting:

window.KyiperFormWidget.debug = true;

Performance Tips

  • Use a CDN for widget files in production
  • Minify CSS and JavaScript files
  • Optimise API response times
  • Consider lazy loading for multiple widgets

Changelog

Version 1.0.0 Current

  • NEW: Multi-step form wizard with progress tracking
  • NEW: Theme configuration support
  • NEW: Success and error callbacks
  • NEW: Event-driven architecture
  • NEW: Mobile-responsive design
  • NEW: Dynamic error handling
  • NEW: Conditional field logic
  • NEW: Form validation system
  • NEW: Public API methods

Support & Resources

For additional support, documentation, or feature requests:

  • Documentation: This guide covers all features and configurations
  • Examples: Check the example files for implementation patterns
  • API Reference: Ensure your API matches the expected request/response format
  • Browser Support: Tested on Chrome, Firefox, Safari, and Edge