The WP-Members User List Extension gives you a shortcode that you can use to display lists of users on your site. Default parameters can be set in the plugin settings, but custom list parameters can be passed through the shortcode which allows you to set up multiple lists with different parameters.
This extension is available with the WP-Members Pro Bundle, WP-Members Lifetime Support, or is also available individually.
Features
The User List plugin allows you to create user directories and lists that can be used in a variety of different ways. It can be used for searchable user directories but it can also be used to display groups of users for other purposes. It is initiated by shortcode and each shortcode instance can have different settings, so you are not limited to just the defaults that you create in the plugin’s settings. There is a (very) basic demo on the WP-Members Demo Site.
The output is also very flexible when using CSS. The demo also has some list instances that have completely custom output (the descriptions of how to implement those customizations are available on the support site).
Installation
This extension installs as a plugin. You can download the installation package as a zip file. Then use the new plugin uploader or unzip the package and FTP transfer to your plugin’s folder. Once the extension is installed, you can go to Plugins > Installed Plugins to activate.
When you purchase the extension, or it is included in your bundled subscription, you will receive a license key that provides you a year of updates to the plugin. Activating your license key will activate the the plugin to receive updates when they are released.
Using the Extension
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.
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.
Example usage:
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):
[wpmem_ul]
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:
[wpmem_logged_in] [wpmem_ul number=5] [/wpmem_logged_in]
[wpmem_logged_out] The members list can only be viewed by members. If you are a member, login to view the list. [/wpmem_logged_out]
Create a Profile Detail Page
You can create a link to an optional detailed user profile page. For this feature, you will need to create a separate page and add the following shortcode:
[wpmem_ul_profile]
There is a selector in the admin panel for you to define a profile page (if used). You will need to set this to the location of the page you have placed this shortcode on. The setting will create a link at the H2 heading in the main list that passes the user ID to the the profile page.
Parameters for Profile Detail Shortcode
- fields – the fields that you wish to display for the user’s profile. These correspond to the option name (meta_key) of any fields you have set up in WP-Members. Values should be comma separated with no spaces (i.e. “user_login,user_email,first_name,last_name”)
- id – the numeric ID of a user for which the profile will be displayed. By default, this value is passed to the page in a querystring. But you can display a profile for a specific user by setting this value. Value should be an integer corresponding to a user ID in the wp_users table.
- div – true|false – determines if the fields should be wrapped with a <div> tag. Defaults to true.
- div_id – sets an id for the <div> tag (if used).
- div_class – sets a class for the <div> tag (if used). Defaults to “field-name”.
- span – true|false – determines if the fields should be wrapped with a <span> tag. Defaults to false.
- span_id – sets an id for the <span> tag (if used).
- span_class – sets a class for the <span> tag (if used).
- avatar – the numeric value of avatar size in pixels (i.e. 20 would make the displayed avatar 20px x 20px). Use a negative value for no avatar.
- labels – true|false – determines if the field names are displayed as labels (i.e. First Name: Bob). Defaults to false.
- main_div_before – applies a <div> wrapper to the entire profile. Defaults to “<div id=”user-list-profile”>”.
- main_div_after – applies a closing </div> tag to the main wrapper set above. Defaults to “</div>”. Should be the closing value of whatever is used in main_div_before.
- show_empty – shows or hides empty fields. Defaults to true (show).
Stylesheets
This extension has several stylesheet options. It starts by checking to see if you are using any of the main plugin (WP-Members) included stylesheets. If any of those are used, the extension will change its stylesheet to a default that is designed to match the parent plugin’s stylesheet.
Alternatively, you can load a stylesheet by either deregistering the default stylesheet and loading one with wp_enqueue_style, or you can use the extension’s wpmem_ul_style_path filter hook to pass a url location for your custom stylesheet.
Filter Hooks
This extension has several filter hooks available for customization
- wpmem_ul_search_form
- wpmem_ul_results_heading
- wpmem_ul_nav
- wpmem_ul_list_args
- wpmem_ul_user_list
- wpmem_ul_error_msg
- wpmem_ul_h2
- wpmem_ul_empty_h2
- wpmem_ul_user_rows
- wpmem_ul_user
- wpmem_ul_empty_field
- wpmem_ul_style_path
- wpmem_ul_wpmem_txt
- wpmem_ul_strip_breaks
- wpmem_ul_profile_args
- wpmem_ul_profile_empty
- wpmem_ul_profile_rows