wp_dropdown_users
Create dropdown HTML content of users.
Description
(string) wp_dropdown_users( (string) $args = '' );
The content can either be displayed, which it is by default or retrieved by setting the echo argument. The include, and exclude arguments do not need to be used; all users will be displayed in that case. Only one can be used, either include, or exclude, but not both.
The available arguments are as follows:
Returns (string)
String of HTML content.
Parameters (1)
- 0. $args — Optional. (string) =>
''
- Array or string of arguments to generate a drop-down of users. See
WP_User_Query
::prepare_query(…) for additional available arguments.Options
- show_option_all (string) =>
''
Text to show as the drop-down default (all).
- show_option_none (string) =>
''
Text to show as the drop-down default when no users were found.
- option_none_value (int|string) =>
-1
Value to use for
$show_option_non
when no users were found. - hide_if_only_one_author (string) =>
''
Whether to skip generating the drop-down if only one user was found.
- orderby (string) =>
'display_name'
Field to order found users by. Accepts user fields.
- order (string) =>
'ASC'
Whether to order users in ascending or descending order. Accepts ASC (ascending) or DESC (descending).
- include (array|string) =>
''
Array or comma-separated list of user IDs to include.
- exclude (array|string) =>
''
Array or comma-separated list of user IDs to exclude.
- multi (bool|int) =>
0
Whether to skip the ID attribute on the select element. Accepts 1|true or 0|false.
- show (string) =>
'display_name'
User data to display. If the selected item is empty then the user_login will be displayed in parentheses. Accepts any user field, or display_name_with_login to show the display name with user_login in parentheses.
- echo (int|bool) =>
1
Whether to echo or return the drop-down. Accepts 1|true (echo) or 0|false (return).
- selected (int) =>
0
Which user ID should be selected.
- include_selected (bool) =>
false
Whether to always include the selected user ID in the drop- down.
- name (string) =>
'user'
Name attribute of select element.
- id (string) =>
is the value of $name
ID attribute of the select element.
- class (string) =>
''
Class attribute of the select element.
- blog_id (int) =>
is ID of the current blog
ID of blog (Multisite only).
- who (string) =>
''
Which type of users to query. Accepts only an empty string or authors..
- role (string|array) =>
''
An array or a comma-separated list of role names that users must match to be included in results. Note that this is an inclusive list: users must match *each* role.
- role__in (array) =>
array()
An array of role names. Matched users must have at least one of these roles.
array( /** * Text to show as the drop-down default (all). * * @type string * @default '' */ 'show_option_all' => '', /** * Text to show as the drop-down default when no users were found. * * @type string * @default '' */ 'show_option_none' => '', /** * Value to use for $show_option_non when no users were found. * * @type int|string * @default -1 */ 'option_none_value' => -1, /** * Whether to skip generating the drop-down if only one user was found. * * @type string * @default '' */ 'hide_if_only_one_author' => '', /** * Field to order found users by. Accepts user fields. * * @type string * @default 'display_name' */ 'orderby' => 'display_name', /** * Whether to order users in ascending or descending order. Accepts 'ASC' (ascending) or 'DESC' * (descending). * * @type string * @default 'ASC' */ 'order' => 'ASC', /** * Array or comma-separated list of user IDs to include. * * @type array|string * @default '' */ 'include' => '', /** * Array or comma-separated list of user IDs to exclude. * * @type array|string * @default '' */ 'exclude' => '', /** * Whether to skip the ID attribute on the 'select' element. Accepts 1|true or 0|false. * * @type bool|int */ 'multi' => 0, /** * User data to display. If the selected item is empty then the 'user_login' will be displayed in * parentheses. Accepts any user field, or 'display_name_with_login' to show the display name * with user_login in parentheses. * * @type string * @default 'display_name' */ 'show' => 'display_name', /** * Whether to echo or return the drop-down. Accepts 1|true (echo) or 0|false (return). * * @type int|bool * @default 1 */ 'echo' => 1, /** * Which user ID should be selected. * * @type int */ 'selected' => 0, /** * Whether to always include the selected user ID in the drop- down. * * @type bool * @default false */ 'include_selected' => false, /** * Name attribute of select element. * * @type string * @default 'user' */ 'name' => 'user', /** * ID attribute of the select element. * * @type string * @default is the value of $name */ 'id' => is the value of $name, /** * Class attribute of the select element. * * @type string * @default '' */ 'class' => '', /** * ID of blog (Multisite only). * * @type int * @default is ID of the current blog */ 'blog_id' => is ID of the current blog, /** * Which type of users to query. Accepts only an empty string or 'authors'. * * @type string * @default '' */ 'who' => '', /** * An array or a comma-separated list of role names that users must match to be included in * results. Note that this is an inclusive list: users must match *each* role. * * @type string|array * @default '' */ 'role' => '', /** * An array of role names. Matched users must have at least one of these roles. * * @type array * @default array() */ 'role__in' => array() );
…
- show_option_all (string) =>
Usage
if ( !function_exists( 'wp_dropdown_users' ) ) { require_once ABSPATH . WPINC . '/user.php'; } // Optional. Array or string of arguments to generate a drop-down of users. See WP_User_Query::prepare_query() for additional available arguments. $args = array( 'show_option_all' => '', 'show_option_none' => '', 'option_none_value' => -1, 'hide_if_only_one_author' => '', 'orderby' => 'display_name', 'order' => 'ASC', 'include' => '', 'exclude' => '', 'multi' => 0, 'show' => 'display_name', 'echo' => 1, 'selected' => 0, 'include_selected' => false, 'name' => 'user', 'id' => is the value of $name, 'class' => '', 'blog_id' => is ID of the current blog, 'who' => '', 'role' => '', 'role__in' => array() ); // NOTICE! Understand what this does before running. $result = wp_dropdown_users($args);
Defined (1)
The function is defined in the following location(s).
- /wp-includes/user.php
- 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(),
- );
- $defaults['selected'] = is_author() ? get_query_var( 'author' ) : 0;
- $r = wp_parse_args( $args, $defaults );
- $query_args = wp_array_slice_assoc( $r, array( 'blog_id', 'include', 'exclude', 'orderby', 'order', 'who', 'role', 'role__in', 'role__not_in' ) );
- $fields = array( 'ID', 'user_login' );
- $show = ! empty( $r['show'] ) ? $r['show'] : 'display_name';
- if ( 'display_name_with_login' === $show ) {
- $fields[] = 'display_name';
- } else {
- $fields[] = $show;
- }
- $query_args['fields'] = $fields;
- $show_option_all = $r['show_option_all'];
- $show_option_none = $r['show_option_none'];
- $option_none_value = $r['option_none_value'];
- /**
- * Filters the query arguments for the list of users in the dropdown.
- *
- * @since 4.4.0
- *
- * @param array $query_args The query arguments for get_users().
- * @param array $r The arguments passed to wp_dropdown_users() combined with the defaults.
- */
- $query_args = apply_filters( 'wp_dropdown_users_args', $query_args, $r );
- $users = get_users( $query_args );
- $output = '';
- if ( ! empty( $users ) && ( empty( $r['hide_if_only_one_author'] ) || count( $users ) > 1 ) ) {
- $name = esc_attr( $r['name'] );
- if ( $r['multi'] && ! $r['id'] ) {
- $id = '';
- } else {
- $id = $r['id'] ? " id='" . esc_attr( $r['id'] ) . "'" : " id='$name'";
- }
- $output = "<select name='{$name}'{$id} class='" . $r['class'] . "'>\n";
- if ( $show_option_all ) {
- $output .= "\t<option value='0'>$show_option_all</option>\n";
- }
- if ( $show_option_none ) {
- $_selected = selected( $option_none_value, $r['selected'], false );
- $output .= "\t<option value='" . esc_attr( $option_none_value ) . "'$_selected>$show_option_none</option>\n";
- }
- if ( $r['include_selected'] && ( $r['selected'] > 0 ) ) {
- $found_selected = false;
- $r['selected'] = (int) $r['selected'];
- foreach ( (array) $users as $user ) {
- $user->ID = (int) $user->ID;
- if ( $user->ID === $r['selected'] ) {
- $found_selected = true;
- }
- }
- if ( ! $found_selected ) {
- $users[] = get_userdata( $r['selected'] );
- }
- }
- foreach ( (array) $users as $user ) {
- if ( 'display_name_with_login' === $show ) {
- /** translators: 1: display name, 2: user_login */
- $display = sprintf( _x( '%1$s (%2$s)', 'user dropdown' ), $user->display_name, $user->user_login );
- } elseif ( ! empty( $user->$show ) ) {
- $display = $user->$show;
- } else {
- $display = '(' . $user->user_login . ')';
- }
- $_selected = selected( $user->ID, $r['selected'], false );
- $output .= "\t<option value='$user->ID'$_selected>" . esc_html( $display ) . "</option>\n";
- }
- $output .= "</select>";
- }
- /**
- * Filters the wp_dropdown_users() HTML output.
- *
- * @since 2.3.0
- *
- * @param string $output HTML output generated by wp_dropdown_users().
- */
- $html = apply_filters( 'wp_dropdown_users', $output );
- if ( $r['echo'] ) {
- echo $html;
- }
- return $html;
- }