WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Plugin API/Filter Reference/editable roles

Contents

Description

editable_roles is a filter applied by the function get_editable_roles() to the list of roles that one user can assign to others (a user must have the edit_users capability to change another user's role). This list is displayed in the bulk operations (if the user has the list_users and promote_users) of the Users Screen, and on the profile screen.

Usage

<?php
function my_editable_roles($all_roles) {
    
# ...
}
add_filter('editable_roles''my_editable_roles');

Parameters

$all_roles
(array) (required) All roles.
Default: None

Return

Filter functions should return an array of roles with the same format as the $all_roles parameter.

Examples

Filter out roles with levels higher than the current user's:

<?php
function remove_higher_levels($all_roles) {
    $user = wp_get_current_user();
    $next_level = 'level_' . ($user->user_level + 1);

    foreach ( $all_roles as $name => $role ) {
        if (isset($role['capabilities'][$next_level])) {
            unset($all_roles[$name]);
        }
    }

    return $all_roles;
}

add_filter('editable_roles', 'remove_higher_levels');

Add a "No role" option that sets users' roles to nothing on pages other than the user profile screen (where it already exists):

<?php
function add_empty_editable_role($all_roles) {
    $screen = get_current_screen();

    if (! (isset($all_roles['']) || 'user-edit' == $screen->id)) {
        $all_roles[''] = array(
            'name' => __('— No role for this site —'),
            'capabilities' => array(),
            );
    }

    return $all_roles;
}

add_filter('editable_roles', 'add_empty_editable_role');

Change Log

Since: Version 2.8

Source Files

This filter is applied by:

Related

Functions

This page is marked as incomplete. You can help Codex by expanding it.