Content Preview Guide

Overview

The X402 Paywall plugin includes a sophisticated content preview system that allows content creators to show a teaser of their paywalled content. This improves user experience and can increase conversion rates by giving potential buyers a glimpse of what they'll receive.

Key Features

1. Flexible Preview Options

Authors can choose from 5 preview modes:

• No Preview (0): Show paywall immediately with no content teaser
• Short Preview (100 words): Brief teaser, ideal for articles
• Medium Preview (250 words): Moderate teaser for longer content
• Long Preview (500 words): Extensive teaser for in-depth articles
• Custom (<!--more--> tag): Full author control using WordPress More tag

2. Smart HTML Preservation

The preview system intelligently preserves HTML structure:

• Maintains Valid HTML: Properly closes all tags at cutoff point
• Preserves Block Structure: Keeps paragraphs, headings, lists intact
• Attribute Preservation: All HTML attributes (classes, IDs) are maintained

3. Rich Media Support

Videos, images, and embeds are treated as complete blocks:

• Complete Embeds Only: Never cuts embeds in half
• Supported Media:
  • YouTube/Vimeo video embeds (via <iframe>)
  • Native HTML5 <video> and <audio> tags
  • Images (<img> tags)
  • Generic iframes
  • <embed> and <object> tags
  • WordPress figure blocks

4. WordPress Integration

• Shortcode Processing: All shortcodes are processed before preview extraction
• oEmbed Support: YouTube, Vimeo, and other embeds work correctly
• Content Filters: Runs through the_content filter for full compatibility
• Theme Compatibility: Works with any WordPress theme

Configuration

Per-Post Settings

When editing a post or page with X402 paywall enabled:

1. Scroll to the X402 Paywall Settings meta box
2. Locate the Preview Length dropdown
3. Select your desired preview option:
   • No Preview: Immediate paywall, no teaser
   • Short (100 words): Quick introduction
   • Medium (250 words): Balanced preview
   • Long (500 words): Comprehensive teaser
   • Custom (<!--more--> tag): Manual control

Using the WordPress More Tag

For maximum control, choose "Custom (<!--more--> tag)" and add the tag in your content editor:

Block Editor (Gutenberg):

1. Click the + button to add a block
2. Search for "More"
3. Insert the "More" block where preview should end

Classic Editor:

1. Position cursor where preview should end
2. Click the "Insert More Tag" button in the toolbar
3. Or manually type <!--more-->

Example:

<p>This is the introduction to my article. It will be visible to everyone.</p>

<p>This paragraph contains a YouTube video:</p>
[youtube https://www.youtube.com/watch?v=dQw4w9WgXcQ]

<!--more-->

<p>This content is behind the paywall. Only paying users can see it.</p>

Technical Implementation

Word-Based Preview Extraction

When using word count limits (100/250/500), the plugin:

1. Processes Content: Runs content through the_content filter to process shortcodes and embeds
2. Parses HTML: Uses DOMDocument to parse HTML structure
3. Walks DOM Tree: Recursively walks through nodes
4. Counts Words: Counts only text content, not HTML tags
5. Preserves Media: Includes complete media elements without counting their words
6. Closes Tags: Ensures all HTML tags are properly closed
7. Adds Ellipsis: Appends "..." when content is truncated

More Tag Preview

When using <!--more--> tag:

1. Splits Content: Uses PHP explode() to split on <!--more-->
2. Takes First Part: Uses only content before the tag
3. Processes Content: Runs through the_content filter
4. Fallback: If no more tag found, shows no preview

Media Element Handling

The plugin treats these elements as complete blocks:

array('iframe', 'img', 'video', 'audio', 'figure', 'embed', 'object')

These are never cut in half or counted toward word limit.

CSS Styling

Default Styles

The plugin includes responsive CSS for preview display:

.x402-paywall-preview {
    position: relative;
    margin-bottom: 40px;
    padding-bottom: 60px;
}

.x402-paywall-preview::after {
    content: '';
    position: absolute;
    bottom: 0;
    left: 0;
    right: 0;
    height: 120px;
    background: linear-gradient(to bottom, rgba(255, 255, 255, 0), rgba(255, 255, 255, 1));
    pointer-events: none;
}

Customizing Preview Styles

To customize preview appearance, add CSS to your theme:

In your theme's style.css or custom CSS:

/* Change fade gradient color */
.x402-paywall-preview::after {
    background: linear-gradient(to bottom, rgba(248, 248, 248, 0), rgba(248, 248, 248, 1));
}

/* Adjust fade height */
.x402-paywall-preview::after {
    height: 150px;
}

/* Add border or shadow */
.x402-paywall-preview {
    border: 1px solid #e0e0e0;
    border-radius: 8px;
    padding: 20px;
    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
}

/* Style the ellipsis */
.x402-preview-more {
    font-size: 1.5em;
    color: #999;
    text-align: center;
}

Responsive Video Embeds

The plugin automatically handles responsive video sizing:

.x402-paywall-preview iframe[src*="youtube"],
.x402-paywall-preview iframe[src*="vimeo"],
.x402-paywall-preview iframe[src*="dailymotion"] {
    aspect-ratio: 16 / 9;
    width: 100%;
    height: auto;
}

Best Practices

1. Choose Appropriate Preview Length

• Short Articles (500-1000 words): Use 100-word preview
• Medium Articles (1000-2000 words): Use 250-word preview
• Long Articles (2000+ words): Use 500-word preview or custom more tag
• Video Content: Use custom more tag to show intro + embed

2. Strategic More Tag Placement

Place the <!--more--> tag:

• After your hook/introduction
• After teasing your main points
• Before the paywall call-to-action
• After any free preview video/image

3. Include Rich Media in Preview

Consider including in your preview:

• Introductory video explaining the content
• Key images or infographics
• Author introduction video
• Problem statement visualization

4. Test Your Preview

Always preview your content:

1. Save your post as draft
2. Log out or use incognito mode
3. Visit the post URL
4. Verify preview looks good
5. Check that media displays correctly
6. Ensure gradient fade works properly

5. Balance Preview and Paywall

• Don't give away too much in the preview
• Give enough to show value
• Use preview to build curiosity
• End preview at a cliffhanger when possible

Code Reference

Database Schema

Preview length is stored as post meta:

SELECT meta_value 
FROM wp_postmeta 
WHERE post_id = 123 
AND meta_key = '_x402_paywall_preview_length';

Valid Values: '0', '100', '250', '500', '-1'

Programmatic Access

Get preview setting:

$preview_length = get_post_meta($post_id, '_x402_paywall_preview_length', true);
// Returns: '0', '100', '250', '500', '-1', or empty string (defaults to '0')

Set preview setting:

update_post_meta($post_id, '_x402_paywall_preview_length', '250');

Filters and Hooks

Filter preview HTML before display:

add_filter('x402_paywall_preview_html', function($preview_html, $post_id, $preview_length) {
    // Modify preview HTML
    return $preview_html;
}, 10, 3);

Filter preview word count:

add_filter('x402_paywall_preview_word_count', function($word_count, $post_id) {
    // Modify word count based on post type, category, etc.
    if (has_category('premium', $post_id)) {
        return 500; // Longer preview for premium category
    }
    return $word_count;
}, 10, 2);

Troubleshooting

Preview Not Showing

Check these items:

1. Ensure preview length is not set to "No Preview"
2. Verify content has enough words for the selected preview length
3. Check that paywall is enabled for the post
4. Confirm you're viewing as a non-paying user
5. Clear browser cache and WordPress transients

Media Not Displaying

Possible causes:

1. Invalid Embed URL: Verify YouTube/Vimeo URL is correct
2. Shortcode Issue: Check shortcode is properly formatted
3. Theme Conflict: Disable other plugins temporarily to test
4. oEmbed Disabled: Ensure wp_oembed_get() is enabled

Debug steps:

// Add to functions.php temporarily
add_filter('x402_paywall_preview_html', function($html) {
    error_log('Preview HTML: ' . $html);
    return $html;
});

HTML Breaking

If HTML appears broken after cutoff:

1. Check Source HTML: Ensure original content has valid HTML
2. Increase Word Count: Try next preview length up
3. Use More Tag: Switch to custom more tag for manual control
4. Check DOM Parsing: Look for PHP errors in debug.log

Gradient Not Visible

If fade gradient isn't showing:

1. Background Color: Ensure gradient matches your theme's background
2. Z-Index Conflicts: Check for theme CSS overriding z-index
3. Custom Styles: Add !important to override theme styles
4. Browser Support: Test in different browsers

Performance Considerations

Caching

The preview extraction process runs on every page load for non-paying users:

• Server-side caching recommended: Use WordPress object caching
• CDN caching: Can cache entire page for anonymous users
• Transient caching: Not implemented by default to ensure fresh content

Optimization Tips

1. Keep Content Clean: Remove unnecessary HTML/whitespace
2. Optimize Embeds: Use lazy loading for videos
3. Limit Media: Don't include too many videos in preview
4. Use CDN: Serve images/videos from CDN

Object Caching

For high-traffic sites, add custom caching:

add_filter('x402_paywall_render_preview', function($preview, $post_id, $content) {
    $cache_key = 'x402_preview_' . $post_id;
    $cached = wp_cache_get($cache_key);
    
    if ($cached !== false) {
        return $cached;
    }
    
    // Preview extraction happens here
    // ...
    
    wp_cache_set($cache_key, $preview, '', 3600); // 1 hour
    return $preview;
}, 10, 3);

Migration from Previous Versions

If upgrading from a version without preview support:

1. All existing paywalls default to "No Preview"
2. No database migration required (new post meta only)
3. Backward compatible: Old paywalls work unchanged
4. Opt-in feature: Authors must explicitly enable preview

See Also

• Access Duration Guide - Configuring time-based access
• Theme Developer Guide - Customizing paywall templates
• Hooks Reference - Available filters and actions
• Token Detection Guide - Payment token setup