Canadian Address Lookup Widget System

This document describes the widget generation and embedding system for the Canadian Census Data application.

Overview

The widget system allows users to create customizable address lookup widgets that can be embedded on any website. These widgets provide a user-friendly interface for searching Canadian addresses using the Census Data API.

Features

• Widget Generator (widget_generator.php): Customizable interface, theme selection, size configuration, search options, API configuration, real-time preview.
• Widget Endpoint (widget.php): Responsive design, real-time search, multiple filters, map integration, cross-origin communication, theme support.
• Widget Manager (widget_manager.php): Widget overview, embed code generation, widget management, usage statistics.

File Structure

├── widget_generator.php    # Widget creation interface
├── widget.php             # Widget endpoint (serves the actual widget)
├── widget_manager.php     # Widget management interface
├── widget_demo.html       # Demo page showing widget usage
└── WIDGET_README.md       # Markdown documentation

Usage Guide

1. Creating a Widget: Go to the Widget Generator, configure your settings, and click "Generate Widget".
2. Embedding a Widget: Copy the generated embed code and paste it into your HTML:

<iframe src="http://your-domain.com/widget.php?id=YOUR_WIDGET_ID" 
        width="400" 
        height="300" 
        frameborder="0" 
        style="border: none; border-radius: 8px; box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);">
</iframe>

3. Handling Address Selection: Listen for address selection events from the widget:

window.addEventListener('message', function(event) {
    if (event.data.type === 'address_selected') {
        console.log('Address selected:', event.data.address);
        console.log('Location:', event.data.location);
        // Handle the selected address in your application
    }
});

API Integration

• GET /api.php?endpoint=provinces - Get all provinces
• GET /api.php?endpoint=census-divisions&pruid={province_id} - Get census divisions for a province
• GET /api.php?endpoint=addresses - Search addresses with various filters

Supported search parameters: street, city, postcode, pruid, limit

Themes

• Light Theme (Default): Clean, professional appearance, white background, blue accents
• Dark Theme: Dark background, light text, blue accents
• Blue Theme: Blue-tinted background, professional appearance
• Green Theme: Green-tinted background, fresh appearance

Security Considerations

• Authentication required for API access
• Rate limiting to prevent abuse
• Input validation and sanitization
• Widgets work in cross-origin iframes

Customization Options

• Widget title, button text, placeholder
• Theme selection
• Size and max results
• Filter options (province, city, postal code)

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

Troubleshooting

• Widget not loading: Check widget ID, API endpoint, and authentication
• Search not working: Check browser console, API response, and network
• Styling issues: Check iframe dimensions, CSS conflicts, and theme

Enable debug mode by adding ?debug=1 to the widget URL.

Performance Optimization

• Debounced search (500ms)
• Configurable result limits
• Caching for province/city data
• Lazy loading of results

Future Enhancements

• Advanced filtering
• Custom CSS injection
• Analytics integration
• Multi-language support
• Address validation
• Geocoding services
• Export functionality

Support

1. Check the API documentation
2. Review the demo page
3. Test with the widget generator
4. Check browser console for errors

License

This widget system is part of the Canadian Census Data application and follows the same licensing terms.