# Template Customization Guide

The Recast Paywall plugin is fully themeable using WordPress template hierarchy, similar to WooCommerce.

## 🎨 Three Ways to Customize

### 1. **CSS Styling** (Easiest)
Override the default styles in your theme's `style.css`:

```css
/* Customize paywall appearance */
.recast-paywall-post {
    background: #f5f5f5;
    border-radius: 12px;
}

.recast-paywall-button-primary {
    background: #ff6600;
    border-radius: 25px;
}
```

### 2. **Template Files** (Recommended)
Copy template files from the plugin to your theme and modify:

**Plugin templates location:**
```
wp-content/plugins/recast-paywall/templates/
├── paywall-post.php    (Full post paywall)
└── paywall-block.php   (Block-level paywall)
```

**Copy to your theme:**
```
wp-content/themes/your-theme/recast-paywall/
├── paywall-post.php
└── paywall-block.php
```

The plugin will automatically use your theme's version if it exists!

### 3. **Filter Hooks** (Advanced)
Use WordPress filters for complete control:

```php
// In your theme's functions.php
add_filter('recast_paywall_post_html', function($html, $postId, $inventoryData, $userState, $summary) {
    // Return your completely custom HTML
    return '<div class="my-custom-paywall">...</div>';
}, 10, 5);
```

## 📝 Template Variables

All template files receive these variables:

| Variable | Type | Description |
|----------|------|-------------|
| `$post` | `WP_Post` | The post object |
| `$postId` | `int` | Post ID |
| `$inventoryData` | `array` | Product data from Recast |
| `$userState` | `array` | Current user information |
| `$summary` | `string` | Content teaser/preview |
| `$this` | `PaywallRenderer` | Renderer instance (for helper methods) |

### Inventory Data Structure
```php
$inventoryData = [
    'item_id' => 'recast-item-id',
    'price' => 999,      // Price in cents
    'status' => 'PURCHASEABLE',
    'currency' => 'USD',
];
```

### User State Structure
```php
$userState = [
    'is_logged_in' => true,
    'user_id' => 123,
    'user_email' => 'user@example.com',
    'user_name' => 'John Doe',
];
```

## 🔧 Available Filters

### Template Locations
```php
// Add custom template locations
add_filter('recast_paywall_template_locations', function($locations, $template_name) {
    // Add custom directory before theme directory
    array_unshift($locations, WP_CONTENT_DIR . '/my-custom-templates/');
    return $locations;
}, 10, 2);
```

### Template Path
```php
// Modify the resolved template path
add_filter('recast_paywall_template_path', function($file, $template_name, $location) {
    // Log or modify which template is being used
    return $file;
}, 10, 3);
```

### Complete HTML Override
```php
// Post-level paywall
add_filter('recast_paywall_post_html', function($html, $postId, $inventoryData, $userState, $summary) {
    if (empty($html)) {
        // Return your custom HTML
        return '<div>Custom paywall for post ' . $postId . '</div>';
    }
    return $html;
}, 10, 5);

// Block-level paywall
add_filter('recast_paywall_block_html', function($html, $postId, $inventoryData, $userState, $summary) {
    if (empty($html)) {
        // Return your custom HTML
        return '<div>Custom block paywall</div>';
    }
    return $html;
}, 10, 5);
```

### Summary Length
```php
// Change preview text length
add_filter('recast_paywall_summary_length', function($length) {
    return 150; // Words
});
```

## 🎯 Example: Complete Theme Override

**Create:** `your-theme/recast-paywall/paywall-post.php`

```php
<?php
/**
 * Custom Recast Paywall Template
 */

$price = $inventoryData['price'];
$priceDisplay = $price ? sprintf('%s', number_format($price)) : 'Free';
?>

<div class="my-custom-paywall">
    <div class="paywall-header">
        <h2><?php echo esc_html($post->post_title); ?></h2>
        <p class="price"><?php echo esc_html($priceDisplay); ?></p>
    </div>
    
    <div class="paywall-preview">
        <?php echo wp_kses_post($summary); ?>
    </div>
    
    <div class="paywall-actions">
        <?php if ($userState['is_logged_in']): ?>
            <button 
                class="buy-button" 
                onclick="recastPurchaseContent(<?php echo esc_js($postId); ?>)">
                Buy Now
            </button>
        <?php else: ?>
            <a href="<?php echo esc_url(wp_login_url()); ?>" class="login-button">
                Login to Purchase
            </a>
        <?php endif; ?>
    </div>
</div>
```

## 🎨 CSS Classes Reference

### Post-Level Paywall
```css
.recast-paywall-post              /* Container */
.recast-paywall-overlay           /* Background overlay */
.recast-paywall-content           /* Content wrapper */
.recast-paywall-summary           /* Preview text */
.recast-paywall-wall              /* Paywall panel */
.recast-paywall-logo              /* Premium badge */
.recast-paywall-title             /* Post title */
.recast-paywall-pricing           /* Price section */
.recast-paywall-price             /* Price display */
.recast-paywall-status            /* Status badge */
.recast-paywall-actions           /* Button container */
.recast-paywall-button            /* Generic button */
.recast-paywall-button-primary    /* Primary action button */
.recast-paywall-login-prompt      /* Login section */
.recast-paywall-purchase          /* Purchase section */
.recast-paywall-note              /* Helper text */
```

### Block-Level Paywall
```css
.recast-paywall-block             /* Container */
.recast-paywall-block-content     /* Content wrapper */
.recast-paywall-block-summary     /* Preview text */
.recast-paywall-block-cta         /* Call to action section */
.recast-paywall-block-pricing     /* Price section */
.recast-paywall-block-price       /* Price display */
.recast-paywall-block-button      /* Action button */
```

## 🔍 Template Hierarchy

The plugin searches for templates in this order:

1. **Child Theme**: `wp-content/themes/child-theme/recast-paywall/paywall-post.php`
2. **Parent Theme**: `wp-content/themes/parent-theme/recast-paywall/paywall-post.php`
3. **Plugin Default**: `wp-content/plugins/recast-paywall/templates/paywall-post.php`

This follows WordPress best practices, similar to WooCommerce template overrides.

## 💡 Best Practices

1. **Always copy from plugin** - Start with the default template and modify
2. **Keep variable names** - Don't change `$postId`, `$inventoryData`, etc.
3. **Escape output** - Use `esc_html()`, `esc_url()`, `wp_kses_post()`
4. **Add version comments** - Track which plugin version your template is based on
5. **Test after updates** - Plugin updates may add new features to templates

## 🐛 Debugging

Enable template debugging:

```php
// In functions.php
add_filter('recast_paywall_template_path', function($file, $template_name, $location) {
    error_log("Recast Paywall: Loading template '$template_name' from: $file");
    return $file;
}, 10, 3);
```

## 📚 Need Help?

- **Plugin Support**: https://github.com/your-repo/issues
- **WooCommerce Template Guide**: [Similar approach](https://docs.woocommerce.com/document/template-structure/)
- **WordPress Template Hierarchy**: [Learn more](https://developer.wordpress.org/themes/basics/template-hierarchy/)