Lost password form template

Overview

The lost password form template (lost_password_form.php) is the initial entry point for the password reset workflow. This template displays a simple form where users enter their email address or username to request a password reset link.

File location: templates/lost_password_form.php

Stage: 1 (Request)

When displayed: When users visit the reset password page without any URL parameters, or after successfully submitting the form (shows confirmation message).

Template structure

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

<div id="password-lost-form-wrap">
    <!-- Error messages -->
    <!-- Success message -->
    
    <form id="lostpasswordform" method="post">
        <fieldset>
            <legend><?php echo $form_title; ?></legend>
            <!-- Form text -->
            <!-- Email/username input -->
            <!-- Hidden fields (nonce, action) -->
            <!-- Submit button -->
        </fieldset>
    </form>
</div>

Available variables

The template receives these variables from the plugin:

$form_title

Type: String

Source: General settings (somfrp_form_title)

Default: "Reset Password"

Purpose: Heading displayed at the top of the form

Usage: <legend><?php echo $form_title; ?></legend>

$lost_text_output

Type: String (HTML allowed)

Source: General settings (somfrp_lost_password_message)

Default: "Please enter your username or email address. You will receive a link to create a new password via email."

Purpose: Instruction text explaining what users should do

Usage: <?php echo $lost_text_output; ?>

$button_text

Type: String

Source: General settings (somfrp_button_text)

Default: "Reset Password"

Purpose: Label for the submit button

Usage: <button type="submit"><?php echo $button_text; ?></button>

$errors

Type: Array or null

Source: Form validation errors

Purpose: Error messages to display if validation fails

Usage:

<?php if ( ! empty( $errors ) && is_array( $errors ) ) : ?>
    <?php foreach ( $errors as $error ) : ?>
        <p class="som-password-error-message">
            <?php echo esc_html( $error ); ?>
        </p>
    <?php endforeach; ?>
<?php endif; ?>

$email_confirmed

Type: Boolean

Source: Set to true after email is successfully sent

Purpose: Controls display of success confirmation message

Usage:

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

Form fields

Email/Username Input

Field name: somfrp_user_info

Field ID: somfrp_user_info

Type: Text input

Required: Yes

Autocomplete: username

Purpose: Accepts either email address or WordPress username

Validation: Plugin checks for @ symbol to determine whether to lookup by email or username

HTML:

<input 
    type="text" 
    name="somfrp_user_info" 
    id="somfrp_user_info" 
    required 
    autocomplete="username"
>

Hidden Fields

Nonce field:

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

Submitted flag:

<input type="hidden" name="submitted" id="submitted" value="true">

Action identifier:

<input type="hidden" name="somfrp_action" id="somfrp_post_action" value="somfrp_lost_pass">

warning

Do not remove or modify hidden fields. They are required for form processing and security validation.

CSS classes and IDs

Main wrapper

ID: #password-lost-form-wrap

Purpose: Container for entire form and messages

Form

ID: #lostpasswordform

Purpose: Main form element

Messages

Success message: .som-password-sent-message

Error message: .som-password-error-message (combined with .som-password-sent-message)

Submit container

Class: .lostpassword-submit

Purpose: Wrapper for submit button and hidden fields

Form processing flow

1. User enters email/username: Types into somfrp_user_info field
2. User submits form: Clicks submit button
3. Plugin validates input: Checks nonce, validates user exists
4. On success:
   • Generates reset key using get_password_reset_key()
   • Sends email with reset link
   • Reloads page with $email_confirmed = true
   • Displays success message
5. On error:
   • Reloads page with $errors array populated
   • Displays error messages

Customization examples

Change form layout

<div id="password-lost-form-wrap" class="custom-wrapper">
    <div class="form-container">
        <form id="lostpasswordform" method="post">
            <!-- Custom layout -->
        </form>
    </div>
</div>

Add help text

<div class="somfrp-lost-pass-form-text">
    <?php echo $lost_text_output; ?>
    <p class="help-text">
        <?php esc_html_e( 'Need help? Contact support@example.com', 'your-theme' ); ?>
    </p>
</div>

Add placeholder text

<input 
    type="text" 
    name="somfrp_user_info" 
    id="somfrp_user_info" 
    placeholder="<?php esc_attr_e( 'Enter your email address', 'your-theme' ); ?>"
    required 
    autocomplete="username"
>

Customize button

<button type="submit" class="btn btn-primary btn-lg">
    <span class="icon">🔒</span>
    <?php echo $button_text; ?>
</button>

Common issues

Form doesn't submit

Problem: Clicking submit button doesn't process the form.

Causes:

• Removed nonce field
• Changed form ID
• JavaScript error preventing submission

Solution: Verify all hidden fields are present. Check browser console for errors. Ensure form ID is lostpasswordform.

Error messages don't display

Problem: Validation errors don't appear on the page.

Causes:

• Removed error display code
• CSS hiding error messages
• Template override missing error handling

Solution: Verify error display code is present. Check CSS isn't hiding .som-password-error-message. Compare to plugin default template.

Success message doesn't show

Problem: After submitting form, no confirmation message appears.

Causes:

• Removed $email_confirmed conditional
• CSS hiding success message
• Email failed to send (check email troubleshooting)

Solution: Verify $email_confirmed conditional is present. Check CSS isn't hiding .som-password-sent-message. Check WordPress debug log for email errors.

Accessibility considerations

Labels

Always include labels for form fields:

<label for="somfrp_user_info">
    <?php _e( 'Email Address or Username', 'frontend-reset-password' ); ?>
</label>

ARIA attributes

Add ARIA attributes for screen readers:

<input 
    type="text" 
    name="somfrp_user_info" 
    id="somfrp_user_info"
    aria-label="<?php esc_attr_e( 'Email Address or Username', 'frontend-reset-password' ); ?>"
    aria-required="true"
    required 
>

Error announcements

Use ARIA live regions for error messages:

<div role="alert" aria-live="polite">
    <?php if ( ! empty( $errors ) ) : ?>
        <!-- Error messages -->
    <?php endif; ?>
</div>

Security best practices

Always escape output

// Good
<?php echo esc_html( $error ); ?>

// Bad
<?php echo $error; ?>

Preserve nonce verification

Never remove or modify the nonce field:

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

Use autocomplete attributes

Help password managers and browsers:

<input autocomplete="username">

Testing checklist

After customizing this template:

• Form displays correctly on desktop
• Form displays correctly on mobile
• Submit button is clickable
• Error messages display when entering invalid email/username
• Success message displays after valid submission
• Email is received with reset link
• Form works with JavaScript disabled
• Screen readers can navigate the form
• Keyboard navigation works (Tab, Enter)

What's next

• Reset password form - New password entry form
• Template overrides guide - Create custom templates
• Three-stage reset flow - Understand the complete workflow