WP_DROPDOWN_USERS() │ WP 2.3.0

Функция wp_dropdown_users() используется для создания выпадающего списка пользователей в HTML.

Основные возможности

По умолчанию список пользователей отображается на странице, но если установить параметр 'echo' в false, его можно просто вернуть в виде строки, а не выводить. Параметры 'include' и 'exclude' являются необязательными; если они не заданы, отобразятся все пользователи. В одном вызове можно использовать только один из них — либо 'include', либо 'exclude', но не оба одновременно.

Время выполнения:

• 1 раз — 0.015165 сек (очень медленно)
• 50000 раз — 812.51 сек (очень медленно)

Хуки функции

• wp_dropdown_users_args — позволяет фильтровать аргументы запроса.
• wp_dropdown_users — позволяет фильтровать HTML-вывод.

Возвращаемое значение

Строка. HTML-код выпадающего списка пользователей.

Как использовать

Вызов функции выглядит следующим образом:

wp_dropdown_users( $args );

Аргументы

Вызов функции принимает массив или строку аргументов для генерации выпадающего списка пользователей:

• show_option_all (string): Текст, отображаемый как опция по умолчанию.

  • По умолчанию: ''

• show_option_none (string): Текст для показа, если пользователи не найдены.

  • По умолчанию: ''

• option_none_value (int|string): Значение для параметра $show_option_none, если пользователи не найдены.

  • По умолчанию: -1

• hide_if_only_one_author (string): Пропустить генерацию списка, если найден только один пользователь?

  • По умолчанию: ''

• orderby (string): Поле для сортировки найденных пользователей.

  • По умолчанию: 'display_name'

• order (string): Порядок сортировки пользователей.

  • Принимает: 'ASC' (по возрастанию) или 'DESC' (по убыванию).
  • По умолчанию: 'ASC'

• include (int[]|string): Массив или запятая-разделенный список ID пользователей, которых нужно включить.

  • По умолчанию: ''

• exclude (int[]|string): Массив или запятая-разделенный список ID пользователей, которых нужно исключить.

  • По умолчанию: ''

• multi (true|false|int): Пропустить ID атрибут на элементе 'select'.

  • По умолчанию: 0|false

• show (string): Данные пользователя для отображения.

  • По умолчанию: 'display_name'

• echo (int|true|false): Вывести или вернуть выпадающий список.

  • По умолчанию: 1|true

• selected (int): ID пользователя, который должен быть выбран.

• include_selected (true|false): Всегда включать выбранный ID пользователя в выпадающий список?

  • По умолчанию: false

• name (string): Атрибут name для элемента select.

  • По умолчанию: 'user'

• id (string): Атрибут id для элемента select.

  • По умолчанию: значение $name

• class (string): Атрибут class для элемента select.

  • По умолчанию: ''

• blog_id (int): ID блога (только для мультисайтов).

  • По умолчанию: ID текущего блога

• who (string): Устарел, используйте $capability вместо него. Какой тип пользователей запрашивать.

  • По умолчанию: пусто (все пользователи)

• role (string|string[]): Массив или запятая-разделенный список названий ролей, которые пользователи должны соответствовать, чтобы быть включеными в результаты.

  • По умолчанию: ''

• role__in (string[]): Массив названий ролей. Похожие пользователи должны иметь хотя бы одну из этих ролей.

  • По умолчанию: пустой массив

• role__not_in (string[]): Массив названий ролей для исключения.

  • По умолчанию: пустой массив

• capability (string|string[]): Массив или запятая-разделенный список названий возможностей, которые пользователи должны иметь, чтобы быть включенными в результаты.

  • По умолчанию: ''

• capability__in (string[]): Массив названий возможностей. Пользователи должны иметь хотя бы одну из этих возможностей.

  • По умолчанию: пустой массив

• capability__not_in (string[]): Массив названий возможностей для исключения.

  • По умолчанию: пустой массив

Примеры

Пример 1: Отображение списка пользователей в выпадающем списке

Давайте создадим полноценную форму для отправки данных (внутри тега <form> и с кнопкой отправки):

Пользователи:

    'author' ] ); ?>
   

Пример 2: Выпадающий список авторов в таблице постов

Для этой задачи можете обратиться к отдельной заметке.

Пример 3: Параметр "who" больше не действителен

С версии 5.9 необходимо использовать новые параметры capabilities (возможности) или role (роль).

Изменения

• С версии 2.3.0: Введено.
• С версии 4.5.0: Добавлено значение 'display_name_with_login' для 'show'.
• С версии 4.7.0: Добавлены параметры 'role', 'rolein' и 'rolenot_in'.
• С версии 5.9.0: Добавлены параметры 'capability', 'capabilityin' и 'capabilitynot_in'. Устарел параметр 'who'.

Код функции

function wp_dropdown_users( $args = '' ) {
    $defaults = array(
        'show_option_all'         => '',
        'show_option_none'        => '',
        'hide_if_only_one_author' => '',
        'orderby'                 => 'display_name',
        'order'                   => 'ASC',
        'include'                 => '',
        'exclude'                 => '',
        'multi'                   => 0,
        'show'                    => 'display_name',
        'echo'                    => 1,
        'selected'                => 0,
        'name'                    => 'user',
        'class'                   => '',
        'id'                      => '',
        'blog_id'                 => get_current_blog_id(),
        'who'                     => '',
        'include_selected'        => false,
        'option_none_value'       => -1,
        'role'                    => '',
        'role__in'                => array(),
        'role__not_in'            => array(),
        'capability'              => '',
        'capability__in'          => array(),
        'capability__not_in'      => array(),
    );

    $defaults['selected'] = is_author() ? get_query_var( 'author' ) : 0;
    $parsed_args = wp_parse_args( $args, $defaults );
    $query_args = wp_array_slice_assoc(...);

    // ... (оставшаяся часть функции) ...
}

Данная функция позволяет формировать список пользователей в выпадающем меню и является полезным инструментом для создания форм и фильтров в админ-панели WordPress.