Loan Calculator Widget

Comprehensive Developer Guide

v2.0

Overview
Installation
Basic Usage
Configuration Options
API Integration
Features
Public Methods
Examples
Styling & Theming
Troubleshooting
Changelog

Overview

The Loan Calculator Widget is a powerful, customisable JavaScript component that provides loan calculation functionality with a modern, responsive interface. It integrates seamlessly with your loan calculation API and offers extensive customisation options.

🚀 Easy Integration

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

🎨 Fully Customisable

Customise colours, fonts, currency, language, and branding to match your application.

📱 Responsive Design

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

🌙 Theme Support

Built-in light, dark, and auto themes with system preference detection.

🌍 Multi-language

Extensible language system with easy translation support.

⚡ Real-time Updates

Instant calculations and dynamic updates as users interact with the form.

Installation

1. Include the Widget Files

Add the widget files to your project:

<link rel="stylesheet" href="LoanCalculatorWidget.css">
<script src="LoanCalculatorWidget.js"></script>

2. Create a Container

<div id="loan-calculator"></div>

3. Initialise the Widget

const widget = new LoanCalculatorWidget(
    document.getElementById('loan-calculator'),
    {
        apiUrl: 'https://your-api.com/loan/calculate',
        apiToken: 'your-api-token',
        assetCost: 50000,
        termMonths: 60
    }
);

Note: The widget is self-contained and doesn't require any external dependencies. It uses vanilla JavaScript and CSS.

Basic Usage

Minimal Configuration

const widget = new LoanCalculatorWidget(
    document.getElementById('loan-calculator'),
    {
        apiUrl: '/api/loan/calculate',
        assetCost: 50000,
        termMonths: 60
    }
);

Complete Example

<!DOCTYPE html>
<html>
<head>
    <title>Loan Calculator</title>
    <link rel="stylesheet" href="LoanCalculatorWidget.css">
</head>
<body>
    <div id="loan-calculator"></div>
    
    <script src="LoanCalculatorWidget.js"></script>
    <script>
        const widget = new LoanCalculatorWidget(
            document.getElementById('loan-calculator'),
            {
                apiUrl: 'https://api.example.com/loan/calculate',
                apiToken: 'your-token',
                environment: 'PRODUCTION',
                assetCost: 50000,
                termMonths: 60,
                depositAmount: 5000,
                currency: '£',
                theme: 'auto'
            }
        );
    </script>
</body>
</html>

Configuration Options

Property	Type	Default	Description
`apiUrl`	string	`'/api/loan/calculate'`	URL endpoint for loan calculation API
`apiToken`	string	`''`	Authentication token for API requests
`environment`	string	`'PRODUCTION'`	Environment setting (PRODUCTION, TEST, etc.)
`assetCost`	number	`0`	Total cost of the asset being financed
`termMonths`	number	`60`	Loan term in months (1-120)
`depositAmount`	number	`0`	Initial deposit amount (optional)
`language`	string	`'en'`	Language code for widget text
`logoUrl`	string	`''`	URL to company logo image
`theme`	string	`'auto'`	Theme: 'light', 'dark', or 'auto'
`currency`	string	`'€'`	Currency symbol for display
`applyUrl`	string	`''`	URL for Apply for HP Finance button
`branding`	object	`{...}`	Branding customization options
`languages`	object	`{...}`	Custom language translations

Branding Configuration

branding: {
    primary: '#6c3fa7',    // Primary brand colour
    secondary: '#f5f5f5',  // Secondary background colour
    font: 'inherit'        // Font family
}

Language Configuration

languages: {
    en: {
        term: 'Term (months)',
        monthlyPayment: 'Your Monthly Payment',
        deposit: 'Your Deposit',
        tradeIn: 'Trade In',
        apply: 'Apply For HP Finance',
        // ... more translations
    },
    es: {
        term: 'Plazo (meses)',
        monthlyPayment: 'Su Pago Mensual',
        // ... Spanish translations
    }
}

API Integration

API Request Format

The widget sends POST requests to your API endpoint with the following structure:

POST /api/loan/calculate
Content-Type: application/json
X-API-Token: your-token
X-Environment: PRODUCTION

{
    "assetCost": 50000,
    "termMonths": 60,
    "monthlyPayment": 850.00,      // Optional: if user enters monthly payment
    "depositAmount": 5000.00       // Optional: deposit + trade-in combined
}

API Response Format

Your API should return a JSON response with the following structure:

{
    "termMonths": 60,
    "initialMonthlyRepayment": 950.00,
    "standardMonthlyRepayment": 850.00,
    "finalMonthlyRepayment": 850.00,
    "assetCost": 50000,
    "depositAmount": 5000,
    "totalCreditAmount": 45000,
    "interestPayable": 6000,
    "totalAmountPayable": 51000,
    "apr": 9.9,
    "interestRate": 8.5,
    "errors": {},           // Optional: validation errors
    "warnings": {}          // Optional: warnings
}

Important: The widget combines deposit and trade-in values into a single depositAmount field. Your API should handle this combined value.

Error Handling

The widget handles various error scenarios:

Network Errors: Displayed in the error box
API Errors: Shows server error messages
Validation Errors: Field-specific error display
Warnings: Non-blocking warning messages

Features

Core Features

📊 Real-time Calculations

Instant loan calculations as users modify terms, deposits, or trade-in values.

💰 Deposit & Trade-in Support

Combines cash deposits and trade-in values for accurate loan calculations.

🎯 Monthly Payment Calculator

Calculate required deposit when user enters desired monthly payment.

📋 Detailed Results Table

Comprehensive breakdown of all loan terms and costs.

🔗 Action Buttons

Apply for finance, email quote, and print functionality.

⚙️ Dynamic Configuration

Update settings and values programmatically after initialisation.

Advanced Features

Responsive Design: Works on all screen sizes
Accessibility: WCAG compliant with proper ARIA labels
Cross-browser Support: Works in all modern browsers
Performance Optimised: Efficient rendering and minimal reflows
Error Recovery: Graceful handling of API failures
Loading States: Visual feedback during calculations

Public Methods

The widget instance provides several methods for dynamic configuration and control:

setLanguage(language)

widget.setLanguage('es')

Changes the widget language. Requires corresponding language configuration.
setTheme(theme)

widget.setTheme('dark')

Changes the widget theme. Options: 'light', 'dark', 'auto'.
setBranding(branding)

widget.setBranding({ primary: '#ff0000' })

Updates branding colours and fonts.
setLogo(logoUrl)

widget.setLogo('https://example.com/logo.png')

Changes the logo image URL.
setCurrency(currency)

widget.setCurrency('$')

Changes the currency symbol throughout the widget.
setApiToken(token)

widget.setApiToken('new-token')

Updates the API authentication token.
setEnvironment(env)

widget.setEnvironment('TEST')

Changes the environment setting for API requests.
setApplyUrl(url)

widget.setApplyUrl('https://apply.example.com')

Updates the Apply for HP Finance button URL.
refresh()

widget.refresh()

Manually triggers a new calculation with current values.

Examples

Basic Implementation

const widget = new LoanCalculatorWidget(
    document.getElementById('calculator'),
    {
        apiUrl: '/api/loan/calculate',
        assetCost: 25000,
        termMonths: 48
    }
);

Full Featured Implementation

const widget = new LoanCalculatorWidget(
    document.getElementById('calculator'),
    {
        apiUrl: 'https://api.finance.com/calculate',
        apiToken: 'prod-token-123',
        environment: 'PRODUCTION',
        assetCost: 75000,
        termMonths: 72,
        depositAmount: 10000,
        currency: '£',
        theme: 'auto',
        language: 'en',
        logoUrl: 'https://company.com/logo.png',
        applyUrl: 'https://apply.finance.com',
        branding: {
            primary: '#2c3e50',
            secondary: '#ecf0f1',
            font: 'Roboto, sans-serif'
        }
    }
);

Dynamic Updates

// Update currency based on user selection
document.getElementById('currency-select').addEventListener('change', (e) => {
    widget.setCurrency(e.target.value);
});

// Update theme based on user preference
document.getElementById('theme-toggle').addEventListener('click', () => {
    const currentTheme = widget.getCurrentTheme();
    widget.setTheme(currentTheme === 'light' ? 'dark' : 'light');
});

// Update apply URL based on selected product
document.getElementById('product-select').addEventListener('change', (e) => {
    const productId = e.target.value;
    widget.setApplyUrl(`https://apply.example.com/product/${productId}`);
});

Multi-language Support

const widget = new LoanCalculatorWidget(
    document.getElementById('calculator'),
    {
        apiUrl: '/api/loan/calculate',
        assetCost: 50000,
        termMonths: 60,
        language: 'es',
        languages: {
            es: {
                term: 'Plazo (meses)',
                monthlyPayment: 'Su Pago Mensual',
                deposit: 'Su Depósito',
                tradeIn: 'Valor de Cambio',
                apply: 'Solicitar Financiamiento',
                emailQuote: 'Enviar Cotización',
                printQuote: 'Imprimir Cotización',
                // ... more translations
            }
        }
    }
);

Styling & Theming

CSS Customisation

The widget uses CSS custom properties for easy theming. You can override these in your stylesheet:

/* Custom theme colours */
.lcw-root {
    --lcw-primary: #2c3e50;
    --lcw-bg: #ecf0f1;
    --lcw-text: #2c3e50;
}

/* Dark theme overrides */
body[data-theme='dark'] .lcw-root {
    --lcw-primary: #3498db;
    --lcw-bg: #2c3e50;
    --lcw-text: #ecf0f1;
}

Available CSS Variables

--lcw-primary: Primary brand colour
--lcw-bg: Background colour
--lcw-text: Text colour

Responsive Breakpoints

The widget automatically adapts to different screen sizes:

Desktop: Full layout with all elements side by side
Tablet: Adjusted spacing and font sizes
Mobile: Stacked layout with optimised touch targets

Custom Styling Examples

/* Custom button styling */
.lcw-btn {
    background: linear-gradient(45deg, #6c3fa7, #8e44ad) !important;
    border-radius: 25px !important;
    box-shadow: 0 4px 15px rgba(108, 63, 167, 0.3) !important;
}

/* Custom input styling */
.lcw-input {
    border: 2px solid #e9ecef !important;
    transition: border-colour 0.3s ease !important;
}

.lcw-input:focus {
    border-colour: #6c3fa7 !important;
    box-shadow: 0 0 0 3px rgba(108, 63, 167, 0.1) !important;
}

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: "API request failed" errors
Solution: Verify API URL, token, and CORS settings

Styling Conflicts

Problem: Widget styling conflicts with page CSS
Solution: Use more specific CSS selectors or isolate the widget in an iframe

Debug Mode

Enable debug logging by opening the browser console. The widget logs detailed information about:

Configuration loading
API requests and responses
State changes
Error conditions

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 2.0 Current

NEW: Added depositAmount configuration parameter
NEW: Added applyUrl for Apply for HP Finance button
FIXED: Trade-in values now combine with deposit amounts
IMPROVED: Enhanced error handling and user feedback
IMPROVED: Better mobile responsiveness
IMPROVED: More comprehensive API integration

Version 1.0

INITIAL: Basic loan calculator functionality
FEATURE: Real-time calculations
FEATURE: Theme support
FEATURE: Currency customisation
FEATURE: Multi-language support

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

Table of Contents