# DataDoesIt Mugshot Widget System

Complete embeddable widget solution for displaying live mugshot galleries on any website with affiliate tracking support.

## 📋 Overview

The DataDoesIt Mugshot Widget system allows website owners to embed live criminal records galleries on their sites. The system includes:

- **Widget JavaScript** (`mugshot-widget.js`) - Frontend display component
- **Widget API** (`mugshot-widget.php`) - Backend data provider
- **Code Generator** (`generator.php`) - Interactive UI for creating embed code
- **Affiliate Tracker** (`affiliate-tracker.php`) - Revenue tracking system

## 🚀 Quick Start

### For Users (Web Developers)

1. Visit: `https://datadoesit.com/Widgets/generator.php`
2. Configure widget options:
   - Select locations (all or specific state/county)
   - Choose display options
   - Set items per page
   - Customize width and auto-refresh
3. Click "Generate Code"
4. Copy the generated code
5. Paste into your website HTML

### Example Usage

```html
<!-- DataDoesIt Mugshot Widget -->
<div id="datadoesit-mugshots"></div>
<script src="https://datadoesit.com/Widgets/mugshot-widget.js"></script>
<script>
  DataDoesItMugshots.init({
    state: 'Louisiana',
    county: 'Iberia',
    count: 20,
    width: '100%',
    affiliate: 'your_affiliate_code'
  });
</script>
```

## 📁 File Structure

```
/Widgets/
├── index.php                    # Main widgets page
├── generator.php                # Code generator interface
├── mugshot-widget.php          # Widget API backend
├── mugshot-widget.js           # Widget JavaScript
├── affiliate-tracker.php       # Affiliate tracking system
└── README.md                   # This file
```

## 🔌 API Endpoints

### Widget Data API
**Endpoint:** `GET /Widgets/mugshot-widget.php`

#### Parameters:

| Parameter | Type | Default | Max | Description |
|-----------|------|---------|-----|-------------|
| `action` | string | data | - | `data` for mugshots, `locations` for available areas |
| `state` | string | - | - | Filter by state (e.g., "Louisiana") |
| `county` | string | - | - | Filter by county (e.g., "Iberia") |
| `count` | integer | 20 | 100 | Records per page |
| `page` | integer | 1 | - | Page number |
| `format` | string | json | - | Response format (only json supported) |

#### Example Requests:

```bash
# Get all available locations
https://datadoesit.com/Widgets/mugshot-widget.php?action=locations

# Get 20 mugshots from Louisiana
https://datadoesit.com/Widgets/mugshot-widget.php?state=Louisiana&count=20

# Get mugshots from Iberia County, Louisiana (page 2)
https://datadoesit.com/Widgets/mugshot-widget.php?state=Louisiana&county=Iberia&count=20&page=2
```

#### Response Format:

```json
{
  "success": true,
  "count": 20,
  "total": 418,
  "page": 1,
  "mugshots": [
    {
      "id": 1,
      "name": "SMITH JOHN",
      "booking_date": "01/29/2026",
      "state": "Louisiana",
      "county": "Iberia",
      "photo_url": "https://datadoesit.com/Photos/...",
      "profile_url": "https://datadoesit.com/mugshots/profile/..."
    }
  ],
  "timestamp": "2026-01-29T12:34:56Z",
  "api_version": "2.0"
}
```

## 🛠️ Widget Configuration Options

### JavaScript Init Options

```javascript
DataDoesItMugshots.init({
  // Location filtering
  state: 'Louisiana',           // Filter by state (optional)
  county: 'Iberia',            // Filter by county (optional)
  
  // Display settings
  count: 20,                   // Items per page (1-100)
  page: 1,                     // Starting page
  width: '100%',               // Widget width
  height: 'auto',              // Widget height
  
  // Behavior
  showPagination: true,        // Show pagination controls
  showFilters: false,          // Show location filters
  autoRefresh: 0,              // Auto-refresh interval (seconds, 0 = disabled)
  
  // Theming
  theme: 'light',              // light or dark theme
  columns: 3,                  // Grid columns
  
  // Container
  containerId: 'datadoesit-mugshots',  // HTML element ID
  
  // Affiliate
  affiliate: 'affiliate_code'  // Affiliate tracking code
});
```

## 👥 Affiliate Integration

### For Affiliate Partners

1. **Get Your Affiliate Code**
   - Login to member area
   - Navigate to Dashboard → Affiliate Program
   - Copy your affiliate code

2. **Generate Widget Code**
   - Visit `/Widgets/generator.php`
   - Your affiliate code is automatically included
   - All widget interactions tracked for commissions

3. **Track Performance**
   - Dashboard shows widget impressions and conversions
   - Real-time analytics on embedded instances
   - Commission tracking

### Affiliate Tracking Details

The system tracks:
- **Impressions** - Widget loaded on page
- **Conversions** - User viewed profile or took action
- **Revenue** - Automatic commission calculation

### Adding Affiliate Parameter Manually

```html
<!-- Explicit affiliate parameter -->
<script>
  DataDoesItMugshots.init({
    state: 'Louisiana',
    affiliate: 'your_affiliate_code'
  });
</script>
```

Or via URL parameter:
```
?aff=your_affiliate_code
```

## 🎨 Customization

### CSS Styling

The widget uses CSS custom properties for easy customization:

```css
/* Override widget styles */
#datadoesit-mugshots {
  --primary-color: #333;
  --border-color: #ddd;
  --background: #fff;
}

/* Custom grid layout */
.datadoesit-gallery {
  grid-template-columns: repeat(4, 1fr);
}

/* Custom card styling */
.datadoesit-mugshot {
  border-radius: 12px;
  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
}
```

### Color Customization

```javascript
// Inject custom CSS
const style = document.createElement('style');
style.textContent = `
  .datadoesit-mugshot {
    border: 2px solid #your-color;
  }
  .datadoesit-pagination button.active {
    background: #your-color;
  }
`;
document.head.appendChild(style);

// Then initialize
DataDoesItMugshots.init({ /* options */ });
```

## 🔒 Security Features

- **CORS Enabled** - Works across domains
- **No API Key Required** - Public API for widgets
- **Rate Limited** - Standard rate limiting applied
- **XSS Protected** - HTML escaping on all user data
- **Affiliate Privacy** - Tracking uses cookies only
- **HTTPS Only** - Secure data transmission

## 📊 Analytics

### Available Metrics

- Widget impressions per page
- Geographic distribution
- User engagement
- Conversion rates
- Click-through patterns

### Accessing Analytics

Logged-in affiliates can view:
- Dashboard widget performance
- Real-time impression tracking
- Conversion attribution
- Revenue calculations

## 🐛 Troubleshooting

### Widget Not Displaying

1. **Check Container Exists**
   ```html
   <!-- Make sure this div exists -->
   <div id="datadoesit-mugshots"></div>
   ```

2. **Check JavaScript Loaded**
   - Open browser console
   - Type: `DataDoesItMugshots` 
   - Should show object if loaded

3. **Check API Response**
   - Open Network tab in DevTools
   - Look for `mugshot-widget.php` request
   - Should return valid JSON

### Empty Results

- Verify state/county spelling (case-insensitive)
- Try without filters to test
- Check data exists: `?action=locations`

### CORS Errors

- Widget is CORS-enabled by default
- Check browser console for specific errors
- Ensure script is loaded from HTTPS

### Affiliate Not Tracking

- Verify affiliate code is correct
- Check browser cookies are enabled
- Ensure logged in or `?aff=code` in URL

## 📈 Performance

- **Load Time:** < 100ms (API response)
- **Initial Render:** < 200ms
- **Memory Usage:** ~2MB per widget instance
- **Network:** ~50KB per page load

### Optimization Tips

1. **Lazy Load**
   ```javascript
   // Load only when visible
   const observer = new IntersectionObserver((entries) => {
     if (entries[0].isIntersecting) {
       DataDoesItMugshots.init({ /* options */ });
     }
   });
   observer.observe(document.getElementById('datadoesit-mugshots'));
   ```

2. **Cache Results**
   - Browser cache: 1 hour default
   - Customize cache headers in API

3. **Reduce Item Count**
   - Start with 12-15 items
   - Use pagination instead of loading all

## 📞 Support

- **Email:** support@datadoesit.com
- **Developer Support:** developers@datadoesit.com
- **Affiliate Support:** affiliates@datadoesit.com
- **Status Page:** https://datadoesit.com/status

## 📜 License

DataDoesIt Widget System is provided as-is for legal public records display. Users must comply with all applicable laws and regulations regarding public information display.

## 🔄 Changelog

### Version 2.0 (Current)
- ✅ New code generator interface
- ✅ Enhanced affiliate tracking
- ✅ Improved responsive design
- ✅ Added location filtering
- ✅ Better error handling
- ✅ Performance optimizations

### Version 1.0
- Initial release

## 🚀 Advanced Integration

### With WordPress

```php
<?php
// Add to theme functions.php or plugin
function datadoesit_mugshot_widget_shortcode($atts) {
    $defaults = array(
        'state' => '',
        'county' => '',
        'count' => 20
    );
    $atts = shortcode_atts($defaults, $atts);
    ?>
    <div id="datadoesit-mugshots-<?php echo time(); ?>"></div>
    <script src="https://datadoesit.com/Widgets/mugshot-widget.js"></script>
    <script>
        DataDoesItMugshots.init({
            state: '<?php echo esc_js($atts['state']); ?>',
            county: '<?php echo esc_js($atts['county']); ?>',
            count: <?php echo intval($atts['count']); ?>
        });
    </script>
    <?php
}
add_shortcode('datadoesit_mugshots', 'datadoesit_mugshot_widget_shortcode');
?>
```

Usage: `[datadoesit_mugshots state="Louisiana" county="Iberia"]`

### With React

```javascript
import { useEffect, useRef } from 'react';

export function MugshotWidget({ state, county, count }) {
  const containerRef = useRef(null);
  
  useEffect(() => {
    if (!window.DataDoesItMugshots) {
      const script = document.createElement('script');
      script.src = 'https://datadoesit.com/Widgets/mugshot-widget.js';
      document.body.appendChild(script);
    }
    
    window.DataDoesItMugshots.init({
      containerId: containerRef.current.id,
      state,
      county,
      count
    });
  }, [state, county, count]);
  
  return <div ref={containerRef} id="datadoesit-mugshots-react" />;
}
```

---

**Version 2.0** | Last Updated: January 29, 2026 | © DataDoesIt