This adds a shortcode that creates as list of users on a page. It has an optional search form and prev/next navigation links. You can set your list defaults in the plugin settings. Go to the WP-Members Options and select the User List tab.
The settings that you can set via the admin panel are:
- Role – determine the role of users to list. The dropdown will display all roles available, including any custom roles added.
- User IDs to Exclude – A list of User IDs (numeric) to exclude from the list display.
- Records per page – determines the number or users to be displayed per page.
- Show search – check this if you would like to enable and display the search box.
- Navigation – navigation display settings.
- Avatar size – the size in pixels of the user avatar. Use a negative number for no avatar.
- Heading value – the record or value to display in the H2 heading for each user.
- Order by – the field to use to order the list. If you select “User Meta,” you can then select the meta to sort by. For either selection, you can sort ascending or descending.
- Show labels – can show no labels, the field names, or the meta key.
- Show empty – determines whether to show empty fields or not.
- Profile page – if you set up a more detailed user profile page with the optional profile shortcode, select the page in this selector so the heading value can link to it.
Below the settings you will find a selection of fields to display. This will determine which fields are displayed for the user records. You can also determine which fields to use for the “search by:” list. NOTE: for best results, it is recommended that you limit search fields to text fields only. This panel is for setting your own defaults for the user list shortcode. However, you can override any of your default settings with parameters passed in the shortcode. There are several optional parameters that can be passed through the shortcode.
Implement the User List on a page
To implement the list, create the page you want the list to display on and add the following shortcode:
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.
If you are implementing additional lists and you need to override the list settings from the admin, you can utilize the attributes below.
Parameters for User List Shortcode
- role – determine the role of users to list (such as subscriber, author, etc). The default is all roles.
- 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_titles – true/false boolean to include the field title as part of the display. For example, first_name: Sam. The default is false.
- meta_key – this allows you to set up a list of users with a specific meta key.
- meta_val – if you use the meta_key parameter, this must be included to determine the meta_key value to display. (“meta_val” is being deprecated in version 2.0. Use meta_val for User List 1.x, meta_value for User List version 2.x.)
Basic list display using settings from the User List tab (Note if you are using a single instance of the list, this is what you should use):
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:
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.