Template customization

Template System Overview

Free Downloads for WooCommerce uses a template system that allows you to customize the appearance and behavior of download buttons and forms by overriding plugin templates in your theme.

The plugin uses template files to render download interfaces. You can customize these templates by copying them to your theme and modifying them.

Template Hierarchy

The plugin looks for templates in this order:

1. Child Theme: {child-theme}/somdn-templates/
2. Parent Theme: {parent-theme}/somdn-templates/
3. Plugin: {plugin}/templates/

This hierarchy allows you to override templates without modifying plugin files.

Available Templates

Download Form Templates

Located in templates/download-forms/ directory:

Template	Purpose
single-file.php	Single file download button/link
multi-file-button.php	Multiple files with "Download All" button only
multi-file-links.php	Multiple files as individual links
multi-file-button-links.php	Multiple files with both button and links
multi-file-button-checkboxes.php	Multiple files with checkboxes for selection
multi-file-button-filenames.php	Multiple files with button and filename list

Pro Templates (Pro Edition Only)

Located in pro/templates/ directory:

Template	Purpose
download-forms/capture-email-form.php	Email capture modal form
account/free-download-limits.php	Account page download limits display

Creating Template Overrides

Step 1: Create Directory

Create a somdn-templates directory in your theme:

# For parent theme
wp-content/themes/your-theme/somdn-templates/

# For child theme (recommended)
wp-content/themes/your-child-theme/somdn-templates/

Step 2: Copy Template

Copy the template you want to customize from the plugin to your theme:

Example: Customize single file template

Copy from:

wp-content/plugins/download-now-for-woocommerce/templates/download-forms/single-file.php

To:

wp-content/themes/your-theme/somdn-templates/download-forms/single-file.php

Step 3: Modify Template

Edit the copied template in your theme. Your changes will now be used instead of the plugin's default template.

Step 4: Test

Clear all caches and test your customizations on the frontend.

warning

Always copy templates to your theme, never modify plugin files directly. Plugin updates will overwrite your changes.

Template Structure

Single File Template

Basic structure of single-file.php:

<?php
/**
 * Single File Download Template
 * 
 * Available variables:
 * $product_id - Product ID
 * $product - WC_Product object
 * $files - Array of downloadable files
 * $args - Template arguments
 */

// Get settings
$button_text = $args['button_text'];
$button_class = $args['button_class'];
$display_method = $args['display_method'];

// Get first file
$file = reset($files);

// Display button or link
if ($display_method === 'button') {
    // Button display
    ?>
    <a href="<?php echo esc_url($file['download_url']); ?>" 
       class="<?php echo esc_attr($button_class); ?>">
        <?php echo esc_html($button_text); ?>
    </a>
    <?php
} else {
    // Link display
    ?>
    <a href="<?php echo esc_url($file['download_url']); ?>" 
       class="somdn-download-link">
        <?php echo esc_html($file['name']); ?>
    </a>
    <?php
}

Multiple Files Template

Basic structure of multi-file-links.php:

<?php
/**
 * Multiple Files Links Template
 * 
 * Available variables:
 * $product_id - Product ID
 * $product - WC_Product object
 * $files - Array of downloadable files
 * $args - Template arguments
 */

// Display each file as a link
foreach ($files as $file) {
    ?>
    <div class="somdn-download-item">
        <a href="<?php echo esc_url($file['download_url']); ?>" 
           class="somdn-download-link">
            <?php echo esc_html($file['name']); ?>
        </a>
    </div>
    <?php
}

Available Variables

Templates have access to these variables:

Product Variables

• $product_id - Product ID (integer)
• $product - WooCommerce product object (WC_Product)
• $variation_id - Variation ID if applicable (integer or null)

File Variables

• $files - Array of downloadable files
  • $file['name'] - File name
  • $file['file'] - File URL
  • $file['download_url'] - Secure download URL with nonce

Argument Variables

• $args - Array of template arguments
  • $args['button_text'] - Button text from settings
  • $args['button_class'] - Button CSS classes
  • $args['link_class'] - Link CSS classes
  • $args['display_method'] - Display method (button/link)
  • $args['context'] - Context (single/archive/shortcode)

User Variables

• $current_user - Current WordPress user object
• is_user_logged_in() - Check if user is logged in

Customization Examples

Example 1: Add File Size to Links

Modify multi-file-links.php to show file sizes:

<?php
foreach ($files as $file) {
    // Get file size
    $file_path = str_replace(home_url('/'), ABSPATH, $file['file']);
    $file_size = file_exists($file_path) ? size_format(filesize($file_path)) : '';
    ?>
    <div class="somdn-download-item">
        <a href="<?php echo esc_url($file['download_url']); ?>" 
           class="somdn-download-link">
            <?php echo esc_html($file['name']); ?>
            <?php if ($file_size) : ?>
                <span class="file-size">(<?php echo esc_html($file_size); ?>)</span>
            <?php endif; ?>
        </a>
    </div>
    <?php
}

Example 2: Add Icons to Download Buttons

Modify single-file.php to add an icon:

<a href="<?php echo esc_url($file['download_url']); ?>" 
   class="<?php echo esc_attr($button_class); ?>">
    <i class="fas fa-download"></i>
    <?php echo esc_html($button_text); ?>
</a>

Example 3: Custom HTML Structure

Create a custom layout for multiple files:

<div class="custom-downloads-grid">
    <?php foreach ($files as $file) : ?>
        <div class="download-card">
            <div class="download-icon">
                <i class="fas fa-file-pdf"></i>
            </div>
            <div class="download-info">
                <h4><?php echo esc_html($file['name']); ?></h4>
                <a href="<?php echo esc_url($file['download_url']); ?>" 
                   class="download-button">
                    Download
                </a>
            </div>
        </div>
    <?php endforeach; ?>
</div>

Example 4: Conditional Display Based on User Role

Show different content for different user roles:

<?php
$current_user = wp_get_current_user();
$is_premium = in_array('premium_member', $current_user->roles);

if ($is_premium) {
    // Premium members see enhanced button
    ?>
    <a href="<?php echo esc_url($file['download_url']); ?>" 
       class="premium-download-button">
        <span class="badge">Premium</span>
        <?php echo esc_html($button_text); ?>
    </a>
    <?php
} else {
    // Regular button for others
    ?>
    <a href="<?php echo esc_url($file['download_url']); ?>" 
       class="<?php echo esc_attr($button_class); ?>">
        <?php echo esc_html($button_text); ?>
    </a>
    <?php
}

Example 5: Add Download Count

Display how many times a file has been downloaded:

<?php
$download_count = get_post_meta($product_id, 'somdn_dlcount', true);
?>
<div class="download-with-count">
    <a href="<?php echo esc_url($file['download_url']); ?>" 
       class="<?php echo esc_attr($button_class); ?>">
        <?php echo esc_html($button_text); ?>
    </a>
    <?php if ($download_count) : ?>
        <span class="download-count">
            Downloaded <?php echo number_format($download_count); ?> times
        </span>
    <?php endif; ?>
</div>

Styling Custom Templates

Add Custom CSS

Add styles for your custom templates in your theme's stylesheet:

/* Custom download grid */
.custom-downloads-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
    gap: 20px;
    margin: 20px 0;
}

.download-card {
    border: 1px solid #ddd;
    border-radius: 8px;
    padding: 20px;
    text-align: center;
}

.download-icon {
    font-size: 48px;
    color: #0073aa;
    margin-bottom: 15px;
}

.download-info h4 {
    margin: 0 0 10px 0;
    font-size: 16px;
}

.download-button {
    display: inline-block;
    background: #0073aa;
    color: white;
    padding: 10px 20px;
    border-radius: 4px;
    text-decoration: none;
}

.download-button:hover {
    background: #005a87;
}

Template Functions

Helper Functions Available in Templates

These functions are available for use in your custom templates:

somdn_get_download_url($product_id, $file_key)

Get secure download URL for a specific file.

$download_url = somdn_get_download_url($product_id, 0);

somdn_is_product_valid($product_id)

Check if product is valid for free download.

if (somdn_is_product_valid($product_id)) {
    // Display download button
}

somdn_get_files($product_id)

Get array of downloadable files for a product.

$files = somdn_get_files($product_id);
foreach ($files as $file) {
    echo $file['name'];
}

Advanced Customization

Using Template Hooks

The plugin provides action hooks within templates for additional customization:

// Before download button
do_action('somdn_before_download_button', $product_id);

// After download button
do_action('somdn_after_download_button', $product_id);

// Before file list
do_action('somdn_before_file_list', $product_id);

// After file list
do_action('somdn_after_file_list', $product_id);

Adding Custom Content

Use hooks to add custom content without modifying templates:

// Add custom message before download button
add_action('somdn_before_download_button', function($product_id) {
    echo '<p class="download-notice">This is a free download!</p>';
});

// Add custom content after file list
add_action('somdn_after_file_list', function($product_id) {
    echo '<p class="download-help">Need help? <a href="/support">Contact us</a></p>';
});

Troubleshooting Template Overrides

Template Not Loading

If your custom template isn't being used:

1. ✅ Verify directory name is exactly somdn-templates
2. ✅ Check file path matches plugin structure
3. ✅ Ensure file name is exactly the same as plugin template
4. ✅ Clear all caches (browser, server, plugin)
5. ✅ Check file permissions (should be readable)

PHP Errors

If you see PHP errors:

1. ✅ Check for syntax errors in your template
2. ✅ Verify all variables are defined before use
3. ✅ Use isset() or empty() to check variables
4. ✅ Enable WordPress debug mode to see detailed errors

Styling Issues

If styling doesn't apply:

1. ✅ Check CSS specificity
2. ✅ Verify CSS is loaded after plugin CSS
3. ✅ Use browser inspector to debug
4. ✅ Clear browser cache

Variables Not Available

If variables are undefined:

1. ✅ Check you're using the correct template
2. ✅ Verify variable names match documentation
3. ✅ Use var_dump() to inspect available variables
4. ✅ Check plugin version (variables may differ)

Best Practices

Template Maintenance

• Document changes: Comment your modifications
• Version control: Track template changes in git
• Test thoroughly: Test on multiple devices and browsers
• Keep backups: Save original templates before modifying
• Update carefully: Check for template changes when updating plugin

Code Quality

• Escape output: Use esc_html(), esc_attr(), esc_url()
• Sanitize input: Use sanitize_text_field(), etc.
• Check variables: Use isset() before accessing variables
• Follow WordPress coding standards: Match WordPress style
• Add comments: Explain complex logic

Performance

• Minimize queries: Don't add unnecessary database queries
• Cache when possible: Use transients for expensive operations
• Optimize loops: Keep loops efficient
• Avoid external requests: Don't make HTTP requests in templates

What's Next

• Display Options - Configure display settings
• Single File Downloads - Single file behavior
• Multiple File Downloads - Multiple file behavior
• Advanced: Action Hooks - Available action hooks
• Advanced: Filter Hooks - Available filter hooks