User

Edit this page on Github

Overview

The user field allows you to select one or multiple users. This field has several settings that can be displayed as a: simple select dropdown, checkbox list, or beautiful select dropdown with select2 library.

Screenshots

Beautiful select with select2 library (default):

Checkbox list:

Radio list:

Radio list inline:

Settings

Besides the common settings, this field has the following specific settings:

Name	Description
query_args	Query arguments for getting users. Uses same arguments as get_users(). Optional.
placeholder	The placeholder for the select box. Default is “Select an user”. Applied only when the field_type is a select field.
field_type	How the users are displayed? See below.

This field inherits the look and field (and settings) from other fields, depending on the field_type, which accepts the following value:

Field type	Description	Settings inherited from
select	Simple select dropdown.	select
select_advanced	Beautiful select dropdown using the select2 library. This is the default value.	select_advanced
checkbox_list	Flatten list of checkboxes which allows to select multiple items.	checkbox_list
radio_list	Flatten list of radio boxes which allows to select only 1 item.	radio

Note that for checkbox_list, the multiple setting is always set to true.

Sample code

This code shows users in select2 dropdown:

array(
    'name'        => 'User',
    'id'          => 'user',
    'type'        => 'user',

    // 'clone'    => true,

    // Field type.
    'field_type'  => 'select_advanced',

    // Placeholder.
    'placeholder' => 'Select an author',

    // Query arguments (optional). No settings means get all published users.
    // @see https://codex.wordpress.org/Function_Reference/get_users
    'query_args'  => array(),
),

The code below shows users in a radio list format:

array(
    'name'        => 'User',
    'id'          => 'user',
    'type'        => 'user',

    // 'clone'    => true,

    // Field type.
    'field_type'  => 'radio_list',

    // Inline radios? Inheritted from radio field.
    'inline'      => true,

    // Query arguments (optional). No settings means get all published users.
    // @see https://developer.wordpress.org/reference/functions/get_users/
    'query_args'  => array(),
),

Ajax Load

Since version 5.2, Meta Box uses Ajax to increase the performance for the field query. Instead of fetching all users at once, the plugin now fetches only some users when the page is loaded, and then fetches more users when users scroll down to the list.

See this video for demonstration (made for posts, but works similar for taxonomies):

This feature is available only for fields that set field_type to select_advanced. There are some extra parameters for you to disable or customize it.

Enable/Disable Ajax Requests

To enable the Ajax requests, simply add 'ajax' => true (which is added by default) to the field:

array(
    'id' => 'project_author',
    'title' => 'Project Author',
    'type' => 'user',
    'ajax' => true, // THIS
),

Setting this parameter to false will disable Ajax requests, making it work exactly the same as in previous versions.

Limit The Number of Users for Pagination

Similar to the previous version, the number of users for pagination is set via the number in the query_args parameter:

array(
    'id' => 'project_author',
    'title' => 'Project Author',
    'type' => 'user',
    'ajax' => true,
    'query_args' => array(
        'number' => 10, // THIS
    ),
),

Unlike in previous versions, this number is used only for Ajax requests to fetch the next bunch of users. The new fetched users will be appended to the list of options in the dropdown, to make the infinite scroll effect.

It also doesn’t affect the initial load of the field. When the field is loaded, Meta Box only queries for saved users (which is usually not many). So the initial query is very minimal and doesn’t cause any performance problem.

Searching Parameters

You probably don’t want to perform an Ajax request when open the dropdown at first. You might want to make Ajax requests only when users type something and search for that. To do that, you need to set the minimumInputLengthfor the input, as below:

array(
    'id' => 'project_author',
    'title' => 'Project Author',
    'type' => 'user',
    'ajax' => true,
    'query_args' => array(
        'number' => 10,
    ),
    'js_options' => array(
        'minimumInputLength' => 1, // THIS
    ),
),

This parameter sets the minimum number of characters required to start a search. It may be good if you don’t want users to make too many Ajax requests that could harm your server.

Data

This field saves user ID(s) in the database.

If field is not multiple, then a single user ID is saved in the database. Otherwise, the field saves multiple user IDs in the database, where each user ID is store in a single row in the database with the same meta key (similar to what add_post_meta does with last parameter false).

If the field is cloneable, then the value is stored as a serialized array in a single row in the database.

Template usage

If field is not multiple, getting value is simple:

$user_id = rwmb_meta( $field_id );
$user = get_userdata( $user_id );
echo 'Username: ', $user->user_login;
echo 'User display name: ', $user->display_name;

If field is multiple, you can loop through the returned values like this:

$user_ids = rwmb_meta( $field_id );
foreach ( $user_ids as $user_id ) {
    $user = get_userdata( $user_id );
    echo '<p>', $user->display_name, '</p>';
}

If you just want to output selected users in an unordered list, use this code:

rwmb_the_value( $field_id );

Read more about rwmb_meta() and rwmb_the_value().

Filters

rwmb_user_choice_label and rwmb_{$field_id}_choice_label

These filters allow developers to change the label of user fields. The 1st label applies to all user fields, and the later for a specific field.

Example: If you are using a field called some_user and you want to change the label in the select box to user first_name instead of the default display_name:

function some_user_filter( $label, $field, $user ) {
    return $user->first_name ;
}
add_filter( 'rwmb_some_user_choice_label', 'some_user_filter', 10, 3);

Edit this page on Github