Simple User Listing

This plugin has been out in the wild for some time now and it seemed appropriate to give it a post on my blog. Once upon a time I was working on a magazine site with a lot of authors and my client wanted to display all the authors in a cool way. Every other plugin I found was too rigid in its output, either markup or CSS or both. I needed to be able to customize and style this list to fit my theme. And while the original site I working on is now defunct, Simple User Listing lives on.

Basic Usage

Once you’ve installed and activated the plugin you only have to add the shortcode to any page (or post) where you’d like to display a full list of all your blog’s users. By default the plugin will display all of the blog’s users and ‘paginate’ the list based on the “Posts per Page” setting.

[userlist]

Custom Templates

I created this plugin to use templates that can be overridden and customized by theme developers. There are 4 templates in the plugin’s templates folder: content-author.php, navigation-author.php, none-author.php and search-author.php. The templates should be relatively self-explanatory and I suspect most of the customizations will happen in content-author.php which is responsible for how each user in the user loop is displayed.

To modify a template simply copy the template file from the simple-user-listing/templates folder of the plugin and paste it  into a simple-user-listing folder in the root of your theme (so my-theme/simple-user-listing). Now you can change the markup any way you please and the plugin will know to use your template instead of the default.

It will be similar to template parts for post loops, except you will have access to each user’s $user object instead of the $post object. For more details on what is available in the  $user object see the Codex reference on WP_User()

Custom Lists

Simple User Listing relies on the WP_Query class and supports almost all of WP_Query’s parameters. Here’s a full list of all parameters:

'query_id' => 'simple_user_listing',
'role' => '',
'include' => '',
'exclude' => '',
'blog_id' => '',
'number' => get_option( 'posts_per_page', 10 ),
'order' => 'ASC',
'orderby' => 'login',
'meta_key' => '',
'meta_value' => '',
'meta_compare' => '=',
'meta_type' => 'CHAR',
'count_total' => true

To use any WP_Query parameter merely add it to the shortcode. For example:

List of Authors

[userlist role="author"]

List of Specific Users

[userlist include="1,2,3,4"]

Order Users by Last Name

As of version 1.5.2 meta query parameters were rolled into the core of the plugin…. well single meta queries anyway. You can sort by any any meta key (much like querying posts).

[userlist meta_key="last_name" orderby="meta_value" order="ASC"]

WP-Pagenavi Bonus

Simple User Listings works with WP-Pagenavi out of the box. Simply activate WP-Pagenavi and your user lists will be paginated with numbers instead of the default previous/next links.

Search by Display Name

By default the search relies on username, but we can change this with some trickery via the pre_user_query hook. Similar to pre_get_posts this is your last chance to change the WP_User_Query query before it is executed. I’ve built in a query_id variable so that you don’t go willy-nilly filtering all user queries which could have some unintended side effects.

// Switch user search from user_login to display_name via query_where 
function kia_search_users_by_display_name( $query ) {

  if ( isset( $query->query_vars['query_id'] ) && $query->query_vars['query_id'] == 'simple_user_listing' ) {
     $query->query_where = str_replace( "user_login", "display_name", $query->query_where );
  }

} 
add_action( 'pre_user_query', 'kia_search_users_by_display_name' ); 

Search by User Meta

And finally, I’ll try to walk you through setting up a custom search.

First we’ll create a new search-author.php template in our theme’s simple-user-listing folder. This template will have a pair of radio buttons that will allow the user to decide between traditional search and searching by a meta field…. in this case “city”, but it really could be whatever you want.

You don’t have to change your search template, but I thought it might be nice.

<?php
/**
 * The Template for displaying Author Search
 */
if ( ! defined( 'ABSPATH' ) ) exit; // Exit if accessed directly

$search = get_query_var( 'as' ) ? get_query_var( 'as' ) : ''; 
$method = get_query_var( 'method' ); 
$method = $method && in_array( $method, array( 'default', 'city' ) ? $method : 'default';

?>

<div class="author-search">

<h2><?php _e('Search authors by user name or by city');?></h2>

<form method="get" id="sul-searchform" action="<?php the_permalink(); ?>">
  <label for="as" class="assistive-text"><?php _e( 'Search' ); ?></label></p> 

  <p><input type="radio" name="method" value="default" <?php checked( $method, 'default' ); ?> /> <?php _e( 'By Username' );?></p>
  <p><input type="radio" name="method" value="city" <?php checked( $method, 'city' );?> /> <?php _e( 'By City' );?></p>

  <p><input type="text" class="field" name="as" id="sul-s" placeholder="<?php _e('Search Authors');?>" value="<?php echo $search;?>" /></p>

  <p><input type="submit" class="submit" id="sul-searchsubmit" value="<?php _e('Search Authors');?>" /?></p>
</form?>;

<?php
if( $search ){ ?>
    <h2><?php printf( __('Search Results for: %s'), '<em>;' . $search .'</em>;' );?></h2>;
    <a href="<?php the_permalink();"?>;<?php _e('Back To Author Listing');?></a?>;
<?php } <?php

</div><!-- .author-search --> 

Next we’ll register a query variable. This belongs in your theme’s functions.php or better still a site-specific mu-plugin, so that it isn’t tied to you theme. Remember that themes are for presentation. Plugins are for manipulating data in ways that should persist through theme changes.

Technically if you don’t change the search template you don’t need to do this either, but I’m going whole-hog here. Did someone say Bacon?

// register an additional SUL search variable
function kia_search_users_allowed_vars( $vars ) {
  $vars[] = 'method';
  return $vars;
}
add_filter( 'sul_user_allowed_search_vars', 'kia_search_users_allowed_vars' );

And finally, we need to adjust the Simple User Listing args before they are sent to WP_Query.

// Switch the WP_User_Query args to a meta search if "by company" is selected function 
function kia_meta_search( $args ){

  $method = ( get_query_var( 'method' ) == 'company' ) ? 'company' : 'name';
  $search = ( isset( $_GET['as'] ) ) ? sanitize_text_field( $_GET['as'] ) : false;

  // if set to search by company switch to a meta query
  if ( $search && $method == 'company' ){
    $args['search'] = ''; //kill default search
    $args['query_id'] = 'simple_user_listing_meta';
    $args['meta_key'] = 'company_name';
    $args['meta_value'] = $search;
    $args['meta_compare'] = 'LIKE';
  }

  return $args;
} 
add_filter('sul_user_query_args', 'kia_meta_search'); 

Support

That should do it. This plugin isn’t in particularly ‘active’ development. Essentially meaning that I’m not looking to add features. However, if it breaks somewhere do let me know.

I apologize in advance but I can’t help you with your custom implementations via the comments or WordPress support forums. I am open to contract work though. Please contact me if you’d like to hire me.

Let me know where you are using my plugin. I’d love to see how you are styling it!