Template overrides

Overview

Template overrides allow you to completely customize the HTML structure and layout of password reset forms by creating custom template files in your theme. This gives you full control over form design while preserving the plugin's functionality.

How template overrides work

The plugin uses a three-tier template hierarchy:

Child theme (highest priority): child-theme/somfrp-templates/*.php
Parent theme: parent-theme/somfrp-templates/*.php
Plugin defaults (fallback): plugin/templates/*.php

When rendering a form, the plugin checks each location in order and uses the first template file it finds.

Creating template overrides

Step 1: Create the templates directory

In your active theme (or child theme), create a directory named somfrp-templates:

wp-content/themes/your-theme/somfrp-templates/

Step 2: Copy template files

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

Plugin template location:

wp-content/plugins/frontend-reset-password/templates/
├── lost_password_form.php
├── lost_password_reset_form.php
└── lost_password_reset_complete.php

Your theme location:

wp-content/themes/your-theme/somfrp-templates/
├── lost_password_form.php          ← Copy here
├── lost_password_reset_form.php    ← Copy here
└── lost_password_reset_complete.php ← Copy here

Step 3: Customize the templates

Edit the copied files in your theme. The plugin will automatically use your custom versions instead of the defaults.

Template override examples

Example 1: Add Bootstrap classes

Override lost_password_form.php to use Bootstrap styling:

<?php
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}
?>

<div class="container">
    <div class="row justify-content-center">
        <div class="col-md-6">
            <div class="card">
                <div class="card-header">
                    <h3><?php echo $form_title; ?></h3>
                </div>
                <div class="card-body">
                    <?php if ( ! empty( $errors ) && is_array( $errors ) ) : ?>
                        <div class="alert alert-danger" role="alert">
                            <?php foreach ( $errors as $error ) : ?>
                                <p class="mb-0"><?php echo esc_html( $error ); ?></p>
                            <?php endforeach; ?>
                        </div>
                    <?php endif; ?>

                    <?php if ( $email_confirmed ) : ?>
                        <div class="alert alert-success" role="alert">
                            <?php esc_html_e( 'An email has been sent. Please check your inbox.', 'frontend-reset-password' ); ?>
                        </div>
                    <?php endif; ?>

                    <form id="lostpasswordform" method="post">
                        <div class="mb-3">
                            <label for="somfrp_user_info" class="form-label">
                                <?php esc_html_e( 'Email Address or Username', 'frontend-reset-password' ); ?>
                            </label>
                            <input 
                                type="text" 
                                name="somfrp_user_info" 
                                id="somfrp_user_info" 
                                class="form-control"
                                required 
                                autocomplete="username"
                            >
                        </div>

                        <?php wp_nonce_field( 'somfrp_lost_pass', 'somfrp_nonce' ); ?>
                        <input type="hidden" name="submitted" value="true">
                        <input type="hidden" name="somfrp_action" value="somfrp_lost_pass">

                        <button type="submit" class="btn btn-primary w-100">
                            <?php echo $button_text; ?>
                        </button>
                    </form>
                </div>
            </div>
        </div>
    </div>
</div>

Example 2: Add custom fields

Add a phone number field to the lost password form:

<form id="lostpasswordform" method="post">
    <fieldset>
        <legend><?php echo $form_title; ?></legend>
        
        <div class="somfrp-lost-pass-form-text">
            <?php echo $lost_text_output; ?>
        </div>

        <!-- Standard email/username field -->
        <p>
            <label for="somfrp_user_info">
                <?php esc_html_e( 'Email Address or Username', 'frontend-reset-password' ); ?>
            </label>
            <input type="text" name="somfrp_user_info" id="somfrp_user_info" required>
        </p>

        <!-- Custom phone number field -->
        <p>
            <label for="custom_phone">
                <?php esc_html_e( 'Phone Number (for verification)', 'your-theme' ); ?>
            </label>
            <input type="tel" name="custom_phone" id="custom_phone">
        </p>

        <?php wp_nonce_field( 'somfrp_lost_pass', 'somfrp_nonce' ); ?>
        <input type="hidden" name="submitted" value="true">
        <input type="hidden" name="somfrp_action" value="somfrp_lost_pass">

        <p class="lostpassword-submit">
            <button type="submit"><?php echo $button_text; ?></button>
        </p>
    </fieldset>
</form>

Note: Custom fields require additional PHP code to process. Use the somfrp_lost_pass_action hook to handle custom data.

Example 3: Simplify completion page

Create a minimal success page:

<?php
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}
?>

<div class="password-reset-success">
    <div class="success-icon">✓</div>
    <h2><?php echo $success_text; ?></h2>
    <a href="<?php echo esc_url( $login_url ); ?>" class="login-button">
        <?php echo $login_text; ?>
    </a>
</div>

<style>
.password-reset-success {
    text-align: center;
    padding: 40px;
}
.success-icon {
    font-size: 64px;
    color: #4CAF50;
    margin-bottom: 20px;
}
</style>

Required elements

When creating template overrides, always preserve these required elements:

Hidden form fields

Nonce fields (security):

<?php wp_nonce_field( 'somfrp_lost_pass', 'somfrp_nonce' ); ?>
<?php wp_nonce_field( 'somfrp_reset_pass', 'somfrp_nonce' ); ?>

Action identifiers:

<input type="hidden" name="somfrp_action" value="somfrp_lost_pass">
<input type="hidden" name="somfrp_action" value="somfrp_reset_pass">

Reset key and user ID (reset form only):

<input type="hidden" name="somfrp_key" value="<?php echo esc_attr( $_GET['key'] ); ?>">
<input type="hidden" name="somfrp_uid" value="<?php echo esc_attr( $_GET['uid'] ); ?>">

Form IDs

Keep these IDs for JavaScript compatibility:

#lostpasswordform - Lost password form
#resetpasswordform - Reset password form
#som_new_user_pass - New password input
#som_new_user_pass_again - Confirm password input

Input field names

Don't change these field names:

somfrp_user_info - Email/username input
som_new_user_pass - New password
som_new_user_pass_again - Confirm password

Security check

Always include at the top of every template:

<?php
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}
?>

Testing template overrides

After creating template overrides:

Clear all caches (WordPress, browser, CDN)
Test complete workflow:
- Request password reset
- Check email delivery
- Click reset link
- Enter new password
- Verify success message
- Log in with new password
Test error scenarios:
- Invalid email/username
- Expired reset key
- Weak password
- Mismatched passwords
Test on multiple devices (desktop, tablet, mobile)
Test with JavaScript disabled (server-side validation should still work)

Troubleshooting

Override not loading

Problem: Changes to template don't appear on site.

Causes:

Template file in wrong directory
File name doesn't match exactly (case-sensitive)
Caching plugin serving old HTML
Using parent theme instead of child theme

Solution:

Verify directory name is somfrp-templates (not frontend-reset-password)
Verify file names match exactly: lost_password_form.php, lost_password_reset_form.php, lost_password_reset_complete.php
Clear all caches
Check if child theme is active

Form doesn't submit

Problem: Form submission doesn't work after override.

Causes:

Removed nonce field
Changed form ID
Removed action identifier
Changed input field names

Solution: Compare your override to plugin default. Ensure all hidden fields, IDs, and names are present.

Validation doesn't work

Problem: Password requirements don't validate in real-time.

Causes:

Changed input IDs
Removed data attributes
JavaScript not loaded

Solution: Keep input IDs and data attributes. Check browser console for JavaScript errors.

Best practices

Use child themes

Always create overrides in a child theme, not the parent theme:

wp-content/themes/
├── parent-theme/
└── child-theme/              ← Put overrides here
    └── somfrp-templates/
        ├── lost_password_form.php
        ├── lost_password_reset_form.php
        └── lost_password_reset_complete.php

Document your changes

Add comments to explain customizations:

<?php
/**
 * Custom Lost Password Form
 * 
 * Customizations:
 * - Added Bootstrap classes
 * - Added phone number field
 * - Changed button styling
 * 
 * Last modified: 2025-11-05
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}
?>

Keep backups

Before customizing:

Backup original plugin templates
Use version control (Git)
Document what you changed and why

Test after plugin updates

After updating the plugin:

Check if default templates changed
Test your overrides still work
Update overrides if needed

Follow WordPress standards

Escape all output: esc_html(), esc_attr(), esc_url()
Use translation functions: __(), _e(), esc_html__()
Follow WordPress coding standards
Add proper indentation and formatting

Advanced customization

Using filters

Modify template paths programmatically:

add_filter( 'somfrp_get_template', 'custom_template_path', 10, 3 );
function custom_template_path( $template_path, $template_name, $templates ) {
    // Use different template based on user role
    if ( $template_name === 'lost-form' && current_user_can( 'administrator' ) ) {
        $custom_path = get_stylesheet_directory() . '/somfrp-templates/admin-lost-form.php';
        if ( file_exists( $custom_path ) ) {
            return $custom_path;
        }
    }
    return $template_path;
}

Adding custom variables

Pass additional data to templates:

add_filter( 'somfrp_template_vars', 'add_custom_template_vars', 10, 2 );
function add_custom_template_vars( $vars, $template_name ) {
    if ( $template_name === 'lost-form' ) {
        $vars['custom_message'] = 'Need help? Contact support@example.com';
    }
    return $vars;
}

Then use in your template:

<?php if ( isset( $custom_message ) ) : ?>
    <p class="help-text"><?php echo esc_html( $custom_message ); ?></p>
<?php endif; ?>

What's next

Styling and CSS - Customize visual appearance
Template override system concept - Understand the hierarchy
Templates reference - Detailed template documentation

Overview​

How template overrides work​

Creating template overrides​

Step 1: Create the templates directory​

Step 2: Copy template files​

Step 3: Customize the templates​

Template override examples​

Example 1: Add Bootstrap classes​

Example 2: Add custom fields​

Example 3: Simplify completion page​

Required elements​

Hidden form fields​

Form IDs​

Input field names​

Security check​

Testing template overrides​

Troubleshooting​

Override not loading​

Form doesn't submit​

Validation doesn't work​

Best practices​

Use child themes​

Document your changes​

Keep backups​

Test after plugin updates​

Follow WordPress standards​

Advanced customization​

Using filters​

Adding custom variables​

What's next​

Overview

How template overrides work

Creating template overrides

Step 1: Create the templates directory

Step 2: Copy template files

Step 3: Customize the templates

Template override examples

Example 1: Add Bootstrap classes

Example 2: Add custom fields

Example 3: Simplify completion page

Required elements

Hidden form fields

Form IDs

Input field names

Security check

Testing template overrides

Troubleshooting

Override not loading

Form doesn't submit

Validation doesn't work

Best practices

Use child themes

Document your changes

Keep backups

Test after plugin updates

Follow WordPress standards

Advanced customization

Using filters

Adding custom variables

What's next