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:

1. Child theme (highest priority): child-theme/somfrp-templates/*.php
2. Parent theme: parent-theme/somfrp-templates/*.php
3. 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: 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:

1. Clear all caches (WordPress, browser, CDN)
2. Test complete workflow:
   • Request password reset
   • Check email delivery
   • Click reset link
   • Enter new password
   • Verify success message
   • Log in with new password
3. Test error scenarios:
   • Invalid email/username
   • Expired reset key
   • Weak password
   • Mismatched passwords
4. Test on multiple devices (desktop, tablet, mobile)
5. 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
 * - 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

What's next

• Styling and CSS - Customize visual appearance
• Password reset flow - Understand the template hierarchy
• Developer reference - Detailed template documentation