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()
);        


Usage

  1. if ( !function_exists( 'wp_dropdown_users' ) ) { 
  2. require_once ABSPATH . WPINC . '/user.php'; 
  3.  
  4. // Optional. Array or string of arguments to generate a drop-down of users. See WP_User_Query::prepare_query() for additional available arguments. 
  5. $args = array( 
  6. 'show_option_all' => '', 
  7. 'show_option_none' => '', 
  8. 'option_none_value' => -1, 
  9. 'hide_if_only_one_author' => '', 
  10. 'orderby' => 'display_name', 
  11. 'order' => 'ASC', 
  12. 'include' => '', 
  13. 'exclude' => '', 
  14. 'multi' => 0, 
  15. 'show' => 'display_name', 
  16. 'echo' => 1, 
  17. 'selected' => 0, 
  18. 'include_selected' => false, 
  19. 'name' => 'user', 
  20. 'id' => is the value of $name, 
  21. 'class' => '', 
  22. 'blog_id' => is ID of the current blog, 
  23. 'who' => '', 
  24. 'role' => '', 
  25. 'role__in' => array() 
  26. ); 
  27.  
  28. // NOTICE! Understand what this does before running. 
  29. $result = wp_dropdown_users($args); 
  30.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/user.php  
  1. function wp_dropdown_users( $args = '' ) { 
  2. $defaults = array( 
  3. 'show_option_all' => '', 'show_option_none' => '', 'hide_if_only_one_author' => '',  
  4. 'orderby' => 'display_name', 'order' => 'ASC',  
  5. 'include' => '', 'exclude' => '', 'multi' => 0,  
  6. 'show' => 'display_name', 'echo' => 1,  
  7. 'selected' => 0, 'name' => 'user', 'class' => '', 'id' => '',  
  8. 'blog_id' => get_current_blog_id(), 'who' => '', 'include_selected' => false,  
  9. 'option_none_value' => -1,  
  10. 'role' => '',  
  11. 'role__in' => array(),  
  12. 'role__not_in' => array(),  
  13. ); 
  14.  
  15. $defaults['selected'] = is_author() ? get_query_var( 'author' ) : 0; 
  16.  
  17. $r = wp_parse_args( $args, $defaults ); 
  18.  
  19. $query_args = wp_array_slice_assoc( $r, array( 'blog_id', 'include', 'exclude', 'orderby', 'order', 'who', 'role', 'role__in', 'role__not_in' ) ); 
  20.  
  21. $fields = array( 'ID', 'user_login' ); 
  22.  
  23. $show = ! empty( $r['show'] ) ? $r['show'] : 'display_name'; 
  24. if ( 'display_name_with_login' === $show ) { 
  25. $fields[] = 'display_name'; 
  26. } else { 
  27. $fields[] = $show; 
  28.  
  29. $query_args['fields'] = $fields; 
  30.  
  31. $show_option_all = $r['show_option_all']; 
  32. $show_option_none = $r['show_option_none']; 
  33. $option_none_value = $r['option_none_value']; 
  34.  
  35. /** 
  36. * Filters the query arguments for the list of users in the dropdown. 
  37. * @since 4.4.0 
  38. * @param array $query_args The query arguments for get_users(). 
  39. * @param array $r The arguments passed to wp_dropdown_users() combined with the defaults. 
  40. */ 
  41. $query_args = apply_filters( 'wp_dropdown_users_args', $query_args, $r ); 
  42.  
  43. $users = get_users( $query_args ); 
  44.  
  45. $output = ''; 
  46. if ( ! empty( $users ) && ( empty( $r['hide_if_only_one_author'] ) || count( $users ) > 1 ) ) { 
  47. $name = esc_attr( $r['name'] ); 
  48. if ( $r['multi'] && ! $r['id'] ) { 
  49. $id = ''; 
  50. } else { 
  51. $id = $r['id'] ? " id='" . esc_attr( $r['id'] ) . "'" : " id='$name'"; 
  52. $output = "<select name='{$name}'{$id} class='" . $r['class'] . "'>\n"; 
  53.  
  54. if ( $show_option_all ) { 
  55. $output .= "\t<option value='0'>$show_option_all</option>\n"; 
  56.  
  57. if ( $show_option_none ) { 
  58. $_selected = selected( $option_none_value, $r['selected'], false ); 
  59. $output .= "\t<option value='" . esc_attr( $option_none_value ) . "'$_selected>$show_option_none</option>\n"; 
  60.  
  61. if ( $r['include_selected'] && ( $r['selected'] > 0 ) ) { 
  62. $found_selected = false; 
  63. $r['selected'] = (int) $r['selected']; 
  64. foreach ( (array) $users as $user ) { 
  65. $user->ID = (int) $user->ID; 
  66. if ( $user->ID === $r['selected'] ) { 
  67. $found_selected = true; 
  68.  
  69. if ( ! $found_selected ) { 
  70. $users[] = get_userdata( $r['selected'] ); 
  71.  
  72. foreach ( (array) $users as $user ) { 
  73. if ( 'display_name_with_login' === $show ) { 
  74. /** translators: 1: display name, 2: user_login */ 
  75. $display = sprintf( _x( '%1$s (%2$s)', 'user dropdown' ), $user->display_name, $user->user_login ); 
  76. } elseif ( ! empty( $user->$show ) ) { 
  77. $display = $user->$show; 
  78. } else { 
  79. $display = '(' . $user->user_login . ')'; 
  80.  
  81. $_selected = selected( $user->ID, $r['selected'], false ); 
  82. $output .= "\t<option value='$user->ID'$_selected>" . esc_html( $display ) . "</option>\n"; 
  83.  
  84. $output .= "</select>"; 
  85.  
  86. /** 
  87. * Filters the wp_dropdown_users() HTML output. 
  88. * @since 2.3.0 
  89. * @param string $output HTML output generated by wp_dropdown_users(). 
  90. */ 
  91. $html = apply_filters( 'wp_dropdown_users', $output ); 
  92.  
  93. if ( $r['echo'] ) { 
  94. echo $html; 
  95. return $html;