Template Overrides and Six Hooks for Extending the Avatar Uploader

Most sites never need anything on this page. It exists for the cases the settings screen does not cover: a note above the buttons, a consent checkbox, a different markup structure, or avatars stored somewhere other than the default directory.

Start with a hook, not a template

If you only need to add something, use an action. Six of them wrap the widget, each passed the resolved shortcode attributes:

wpmake_advance_user_avatar_before_uploader
wpmake_advance_user_avatar_before_upload_buttons
wpmake_advance_user_avatar_after_upload_buttons
wpmake_advance_user_avatar_after_uploader
wpmake_advance_user_avatar_before_avatar
wpmake_advance_user_avatar_after_avatar

The first four wrap the uploader; the last two wrap the display-only avatar. A hint under the buttons is three lines:

add_action(
    'wpmake_advance_user_avatar_after_upload_buttons',
    function ( $atts ) {
        echo '<p class="description">Square photos work best.</p>';
    }
);

A hook survives plugin updates without any maintenance on your side. A template override does not, quite — so reach for hooks first.

Overriding a template

When you genuinely need different markup, copy the template into your theme, keeping the file name:

wp-content/plugins/wpmake-advance-user-avatar/templates/
    wpmake-advance-user-avatar-upload-page.php    the uploader
    wpmake-advance-user-avatar-page.php           the display-only avatar

        to

wp-content/themes/your-theme/wpmake-advance-user-avatar/

Your copy is used instead of the plugin’s, and it survives plugin updates. The usual caveat applies: it also survives improvements and bug fixes to the original, so diff it against the plugin’s version when you update.

If the sub-directory name does not suit your theme’s conventions, change it:

add_filter(
    'wpmake_advance_user_avatar_template_directory',
    function () {
        return 'partials/avatar';
    }
);

And wpmake_advance_user_avatar_locate_template gives you the resolved absolute path, for cases where the template should come from a plugin of your own rather than the theme.

The filters worth knowing

• wpmake_advance_user_avatar_shortcode_atts — the resolved attributes for either shortcode, with the tag as the second argument. Use it to enforce a house size or class everywhere without editing every placement.
• wpmake_advance_user_avatar_upload_url — the directory avatars are written to. Useful when uploads are offloaded, or when avatars need their own bucket.
• wpmake_aua_avatar_subsizes — the extra square sizes generated on upload. Defaults to 32, 64 and 96 pixels; add a 192 if your theme renders large profile headers, or trim the list on a storage-constrained site.
• wpmake_aua_needs_frontend_assets — whether the front-end scripts and styles load on this request. The plugin already keeps them off pages that do not render the widget; this filter is for the cases its detection cannot see, such as a widget injected by a page builder at render time.
• wpmake_advance_user_avatar_wpmembers_row_position — where the field is inserted into the WP-Members profile form.
• pre_get_avatar_data — WordPress’s own filter, and the one the plugin supplies avatars through. The plugin hooks it at priority 99, so hook at 100 or later to override it entirely.

A worked example: a consent checkbox

Suppose your site needs users to confirm they have the right to use the photo they are uploading. No template override required:

add_action(
    'wpmake_advance_user_avatar_before_upload_buttons',
    function () {
        echo '<label class="aua-consent">'
            . '<input type="checkbox" id="aua-consent"> '
            . esc_html__( 'This is my photo and I am happy for it to be shown publicly.', 'your-textdomain' )
            . '</label>';
    }
);

add_action(
    'wpmake_aua_avatar_set',
    function ( $user_id, $attachment_id ) {
        update_user_meta( $user_id, 'avatar_consent_at', time() );
    },
    10,
    2
);

The first hook adds the control, the second records the fact. wpmake_aua_avatar_set fires wherever the change came from — the widget, the profile screen, the bulk manager or your own code — so the record is complete rather than only covering the front end.

What to reach for, in order

1. A setting, if one exists. It is upgrade-proof and somebody else maintains it.
2. CSS custom properties, for anything about size, shape or colour.
3. An action hook, to add markup.
4. A filter, to change a value the plugin computed.
5. A template override, only when the markup itself has to be different.

Each step down that list is more powerful and more of your problem at update time. Most requirements are met somewhere in the first three.