Basic Use
To implement the list, create the page you want the list to display on and add the following shortcode:
[wpmem_ul]
The User List allows for multiple instances in a site, but can generally only be used once on a page. If you are only implementing a single list on a single page, it is recommended that you simply use the shortcode and rely on the admin panel to implement your settings.
Additional Custom Attributes
If you are implementing additional lists and you need to override the list settings from the admin, you can utilize the attributes below.
- role – determine the role of users to list (such as subscriber, author, etc). To display “all” roles, pass the role attribute as empty (role=””). The default is “subscriber”.
- exclude – a list of User IDs (numeric) to exclude from the list display.
- number – the number of users that will be displayed per page. The default is 10.
- search – determines whether or not to display the search form. The default is true. Setting to false turns it off.
- search_by – determines which fields that are included in the search by dropdown. Values must be passed as “Field Name|meta key” pairs separated by commas (i.e. “First Name|first_name,Last Name|last_name”).
- nav – determines whether or not to display the nav links. The default is true. Setting to false turns it off.
- fields – an array of the fields you would like displayed for each user. The default is username (user_login) and “member since”.
- avatar – size of the user avatar. The default is 45px. A negative number can be passed for no avatar.
- h2 – what field to display as the h2 heading for each user in the list. The default is first_last. Possible arguments are first_last, last_first, display_name, user_login, username. First name / last name combinations assume use of the WP and WP-Members native first_name and last_name fields.
- order_by – what field to order the list by. The default is username. The possibilities here are currently limited to ordering the list by a field that is part of the wp_users table (user_login, user_email, user_nicename, display_name). To order by a meta field, set this to meta_value and also specify the meta_key parameter.
- show_labels – true/false boolean to include the field title as part of the display. For example, first_name: Sam. The default is false. (“show_titles” is deprecated in version 2.0. Use “show_titles” for User List 1.x, “show_labels” for User List version 2.x.)
- meta_key – this allows you to set up a list of users with a specific meta key.
- meta_value – if you use the meta_key parameter to filter the displayed list, this must be included to determine the meta_key value to display. (“meta_val” is deprecated in version 2.0. Use “meta_val” for User List 1.x, “meta_value” for User List version 2.x.)
Additional Examples setting custom shortcode parameters
Display 5 users per page, no search form:
[wpmem_ul number=5 search=false]
Display default 10 users per page, no navigation links:
[wpmem_ul nav=false]
This shortcode can also be nested with the wp-members status shortcode, such as:
The members list can only be viewed by members. If you are a member, login to view the list.