imgjs-subscribe-module

IMGJS Subscribe Module

A vanilla JavaScript subscription form component that provides a user-friendly email subscription flow with optional profile enrichment.

Quick Start for WordPress

Add this to your theme's header.php or via wp_head action:

<!-- Pre-configure the module (optional) -->
<script>
window.imgjs = window.imgjs || {};
window.imgjs.subscribeConfig = {
  apiBaseUrl: 'https://your-wordpress-site.com/wp-json/imgjs/v1',
  colors: {
    primary: "#0073aa" // WordPress blue
  }
};
</script>

<!-- Add the script -->
<script src="https://unpkg.com/@insight-media-group/imgjs/dist/imgjs-subscribe.min.js"></script>

Then use anywhere in your theme:

<!-- Simple button -->
<button onclick="window.imgjs.subscribe.open()">Subscribe Now</button>

<!-- With pre-filled email -->
<button onclick="window.imgjs.subscribe.open('<?php echo wp_get_current_user()->user_email; ?>')">
  Update Your Profile
</button>

See examples/wordpress.html for full WordPress integration examples including:

• WordPress menu integration
• Shortcode usage
• Widget implementation
• Theme customization
• Admin notice integration

Features

• Clean, modern UI with customizable styling
• Three-step subscription flow with error handling
• Robust input validation and sanitization
• Secure image URL validation
• Proper cleanup and memory management
• Fully accessible (ARIA compliant)
• Mobile responsive
• No external dependencies
• Customizable theming
• Event callbacks with error handling
• Automatic error recovery (10% random error simulation in development)

Installation

Via NPM

npm install @insight-media-group/imgjs

Via CDN

You can include the module directly in your HTML using the CDN. There are two ways to configure it:

1. Pre-load Configuration (Recommended)

<!-- Configure before loading the script -->
<script>
window.imgjs = window.imgjs || {};
window.imgjs.subscribeConfig = {
  // API endpoint
  apiBaseUrl: 'https://api.insightmediagroup.io',
  
  // Typography
  font: "'Inter', -apple-system, sans-serif",
  
  // Colors
  colors: {
    primary: "#6366f1",      // Main brand color (buttons, links)
    text: "#1e293b",         // Main text color
    textMuted: "#64748b",    // Secondary text color
    border: "#e2e8f0",       // Border color
    background: "#ffffff"     // Background color
  },
  
  // Images
  images: {
    logo: "https://example.com/logo.png",
    promo: "https://example.com/promo.jpg"
  },
  
  // Event callbacks
  callbacks: {
    onSuccess: (data) => console.log('Form submitted:', data),
    onClose: () => console.log('Modal closed'),
    onError: (error) => console.error('Error:', error)
  }
};
</script>
<script src="https://unpkg.com/@insight-media-group/imgjs"></script>

2. Post-load Configuration

<!-- Load the script -->
<script src="https://unpkg.com/@insight-media-group/imgjs"></script>

<!-- Configure after loading -->
<script>
imgjs.subscribe.config({
  // Configuration options...
});
</script>

Usage

• Import and initialize the module:

// If using ES modules
import '@insight-media-group/imgjs';

// The module will automatically attach to window.imgjs.subscribe

• Configure the module (if not using pre-load configuration):

imgjs.subscribe.config({
  // API endpoint
  apiBaseUrl: 'https://api.insightmediagroup.io',
  
  // Typography
  font: "'Inter', -apple-system, sans-serif",
  
  // Colors
  colors: {
    primary: "#6366f1",      // Main brand color (buttons, links)
    text: "#1e293b",         // Main text color
    textMuted: "#64748b",    // Secondary text color
    border: "#e2e8f0",       // Border color
    background: "#ffffff"     // Background color
  },
  
  // Images (URLs are automatically sanitized)
  images: {
    logo: "https://example.com/logo.png",
    promo: "https://example.com/promo.jpg"
  },
  
  // Event callbacks
  callbacks: {
    onSuccess: (data) => console.log('Form submitted:', data),
    onClose: () => console.log('Modal closed'),
    onError: (error) => console.error('Error:', error)
  }
});

• Open the subscription modal:

// Open with empty email field
imgjs.subscribe.open();

// Open with pre-filled email
imgjs.subscribe.open('[e-mail]');

• Cleanup when done (optional):

// Remove modal, event listeners, and clear state
imgjs.subscribe.destroy();

Security Features

Input Validation & Sanitization

• Email validation using robust regex pattern
• Phone number validation (E.164 format)
• HTML/Script tag removal from inputs
• Special character encoding
• Length limits on all fields
• XSS prevention

URL Security

• Automatic sanitization of image URLs
• Protocol validation (only http/https allowed)
• Invalid URL handling with warnings

Error Handling

• Graceful error recovery
• User-friendly error messages
• Network error simulation in development (10% rate)
• Proper error event propagation

Validation Rules

Email

• RFC 5321 compliant
• Maximum length: 254 characters
• Required field

Phone

• E.164 format support
• 10-15 digits
• Optional + prefix
• No leading zeros
• Common separator support (spaces, dots, hyphens)

Text Fields

• First Name: max 50 chars
• Last Name: max 50 chars
• Employer: max 100 chars
• Title: max 100 chars
• Industry: max 100 chars

Accessibility

• ARIA roles and attributes
• Keyboard navigation support
• Focus trap in modal
• Screen reader friendly
• High contrast support
• Responsive design

Browser Support

• All modern browsers (Chrome, Firefox, Safari, Edge)
• IE11 and older browsers are not supported

Development

• Clone the repository
• Install dependencies:

npm install

• Start development server:

npm run dev

• Build for production:

npm run build

⚠️ Development Server Notice The included development server (mock-server.js) is for local testing only and should NEVER be used in production. It provides:

• Mock API endpoint simulation
• 10% random error rate for testing error handling
• Special test email patterns (error@, timeout@, fail@)
• CORS headers for local development

For production, always use your own API endpoint by setting apiBaseUrl in the configuration.

Testing

The module includes a configuration tester in the development environment that allows real-time testing of:

• Color schemes
• Typography
• Image URLs
• Error scenarios
• Form validation

Test error scenarios using special email addresses:

• [e-mail] - Triggers a server error
• [e-mail] - Simulates a timeout
• [e-mail] - Triggers a validation error

Best Practices

• Memory Management

  • Always call destroy() when the module is no longer needed
  • Event listeners are automatically cleaned up
  • State is reset on close

• Error Handling

  • Use try-catch blocks around API calls
  • Implement error callbacks for custom handling
  • Provide user-friendly error messages

• Security

  • Validate and sanitize all inputs
  • Use HTTPS for API communication
  • Implement proper CORS headers
  • Sanitize image URLs

• Performance

  • Minimal DOM updates
  • Efficient event handling
  • Proper cleanup of resources

License

ISC