{"id":20686276,"url":"https://github.com/helgatheviking/simple-user-listing","last_synced_at":"2025-09-07T02:07:53.469Z","repository":{"id":6650136,"uuid":"7894445","full_name":"helgatheviking/Simple-User-Listing","owner":"helgatheviking","description":"A shortcode for displaying lists of users in a simple, easy-to-customize (uses template parts) fashion","archived":false,"fork":false,"pushed_at":"2025-02-21T16:13:12.000Z","size":2711,"stargazers_count":20,"open_issues_count":6,"forks_count":8,"subscribers_count":3,"default_branch":"trunk","last_synced_at":"2025-04-22T13:55:15.819Z","etag":null,"topics":["directory","hacktoberfest","shortcode","users","wordpress"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/helgatheviking.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2013-01-29T15:05:45.000Z","updated_at":"2025-02-21T16:13:16.000Z","dependencies_parsed_at":"2024-11-16T22:32:12.424Z","dependency_job_id":"48f697f6-dc7d-43c6-af2e-87de046dbcd7","html_url":"https://github.com/helgatheviking/Simple-User-Listing","commit_stats":null,"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/helgatheviking/Simple-User-Listing","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helgatheviking%2FSimple-User-Listing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helgatheviking%2FSimple-User-Listing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helgatheviking%2FSimple-User-Listing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helgatheviking%2FSimple-User-Listing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/helgatheviking","download_url":"https://codeload.github.com/helgatheviking/Simple-User-Listing/tar.gz/refs/heads/trunk","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helgatheviking%2FSimple-User-Listing/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273986629,"owners_count":25202708,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["directory","hacktoberfest","shortcode","users","wordpress"],"created_at":"2024-11-16T22:31:58.704Z","updated_at":"2025-09-07T02:07:53.431Z","avatar_url":"https://github.com/helgatheviking.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Simple User Listing  #\n\nA shortcode for displaying paginated lists of users.\n\nThis is a developmental repo. Clone this repo and run `npm install \u0026\u0026 npm run release`   \nOR    \n|[Download latest release](https://github.com/helgatheviking/kia-subtitle/releases/latest)|\n\n\n\n## Description ##\n\nOther plugins output paginated lists of users, but I needed to be able to customize and style this list to fit my theme.  So I created this plugin to use templates that can be overridden and customized by theme developers.\n\nTo customize any of the templates, copy the file from the plugin's \"templates\" folder to your themes \"simple-user-listing\" folder. \n\n### Usage ###\n\nPlace this shortcode anywhere you'd like to display a full list of all your blog's users.\n\n\n\t[userlist]\n\n\nBy default the plugin will print out the users based on the \"Posts per Page\" setting under Settings-\u003eReading, but this and many other settings can be changed via the shortcode's parameters. \n\n### Support ###\n\nIf after reading the [FAQ](http://wordpress.org/plugins/simple-user-listing/faq) you still need help, support is handled in the [WordPress forums](http://wordpress.org/support/plugin/simple-user-listing). Please note that support is limited and does not cover any custom implementation of the plugin. \n\nPlease report any bugs, errors, warnings, code problems to [Github](https://github.com/helgatheviking/simple-user-listing/issues)\n\n## Installation ##\n\n1. Upload the `plugin` folder to the `/wp-content/plugins/` directory\n1. Activate the plugin through the 'Plugins' menu in WordPress\n1. Add the shortcode [userlist] anywhere you wish to display a list of users\n\n## Frequently Asked Questions ##\n\n\u003ca id=\"templates\" name=\"templates\"\u003e\u003c/a\u003e\n### How Can I Customize the Output? ###\n\nThe whole reason I wrote this was that other similar plugins had too much control over the output.  You can style the output anyway you'd like by adding your own template parts to your theme.\n\nCopy the files you wish to modify from the `simple-user-listing/templates` folder of the plugin and paste them 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.  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.\n\nFor more details on what is available in the `$user` object [see the Codex reference on WP_User()](http://codex.wordpress.org/Class_Reference/WP_User)\n\n\u003ca id=\"remove-search\" name=\"remove-search\"\u003e\u003c/a\u003e\n### How Do I Remove the Search Input? ###\n\nThere are two ways to remove the search input. The search is added to a hook by the plugin, so you can remove it by adding the following to your theme's `functions.php` file:\n\n\n\tfunction remove_SUL_search() {\n\t    remove_action( 'simple_user_listing_before_loop',   'sul_template_user_search' );\n\t}\n\tadd_action( 'simple_user_listing_before_loop', 'remove_SUL_search', 5 );\n\n\nOr you could copy the `search-author.php` from the plugin's template folder to a `simple-user-listing folder` in your theme (so `simple-user-listing/searcch-author.php`) and remove all the code from it so that it is blank. \n\n\u003ca id=\"parameters\" name=\"parameters\"\u003e\u003c/a\u003e\n### Shortcode Paramaters: How Can I Customize the User Query? ###\n\nSimple User Listing supports most of the parameters of the `WP_User_Query` class as parameters for the shortcode.  For example you can pass it a role defining which type of users you'd like to list.  You can also adjust the number of users displayed per page. Roles must be in lowercase. \n\n\n\t[userlist role=\"author\" number=\"5\"]\n\n\nAs of version 1.2 you can now sort the user list by and of the sort parameters supported by `WP_User_Query()`.  For example, the following would list your users based on number of posts written, with the highest first.\n\n\n\t[userlist orderby=\"post_count\" order=\"DESC\"]\n\n\nAs of version 1.4 you can now list users by a meta key. Be careful with this as this is not exactly an efficient query.\n\n\n\t[userlist meta_key=\"foo\" meta_value=\"widgets\"]\n\n\nAs of version 1.4.2 you can now include and exclude users with a comma separated list of IDs.\n\n\n\t[userlist exclude=\"1,2,3\"]\n\n\nThe full list of supported parameters (shown with default value) is:\n\n\n\t'query_id' =\u003e 'simple_user_listing', // This allows for targeted filtering of pre_get_user which allows for very custom queries.\n\t'role' =\u003e '', // Multiple roles can be defined in a comma separated list [userlist role=\"infield,outfield\"]\n\t'role__in' =\u003e '', // Multiple roles can be defined in a comma separated list \n\t'role__not_in' =\u003e // Multiple roles can be defined in a comma separated list\n\t'include' =\u003e '', // Multiple user IDs can be defined in a comma separated list\n\t'exclude' =\u003e '', // Multiple user IDs can be defined in a comma separated lis\n\t'blog_id' =\u003e '',\n\t'number' =\u003e get_option( 'posts_per_page', 10 ),\n\t'order' =\u003e 'ASC',\n\t'orderby' =\u003e 'login',\n\t'meta_key' =\u003e '',\n\t'meta_value' =\u003e '',\n\t'meta_compare' =\u003e '=',\n\t'meta_type' =\u003e 'CHAR',\n\t'count_total' =\u003e true,\n\t'template' =\u003e 'author' // Corresponds to content-author.php template, can accept different templates per shortcode.\n\n\n\u003ca id=\"meta-sort\" name=\"meta-sort\"\u003e\u003c/a\u003e\n### How Can I Sort the Users by Last Name? ###\n\nAs of verison 1.5.2 you could simply use the following as your shortcode:\n\n\n\t[userlist meta_key=\"last_name\" orderby=\"meta_value\" order=\"ASC\"]\n\n\n\u003ca id=\"meta-search\" name=\"meta-search\"\u003e\u003c/a\u003e\n### How can I search by a meta field? ex: Last Name ###\n\nWhile you could modify the `search-author.php` template, if you are only searching by one field it isn't really neccessary. You will, however, need to modify the shortcode's arguments for `WP_User_Query`.  You can do that by filtering `sul_user_query_args`.\n\nAdd the following to your theme's functions.php:\n\n\n\t/**\n\t * Place this in your theme's functions.php file\n\t * Or a site-specific plugin\n\t *\n\t */\n\t// Switch the WP_User_Query args to a meta search\n\tfunction kia_meta_search( $args ) {\n\t\n\t\t// This $_GET is the name field of the custom input in search-author.php.\n\t\t$search = ( isset($_GET['as']) ) ? sanitize_text_field($_GET['as']) : false ;\n\t\n\t\tif ( $search ) {\n\t\t\t// If your shortcode has a 'role' parameter defined it will be maintained.\n\t\t\t// Unless you choose to unset the role parameter by uncommenting the following:\n\t\t\t//\tunset( $args['role'] );\n\t\t\t$args['meta_key'] = 'last_name';\n\t\t\t$args['meta_value'] = $search;\n\t\t\t$args['meta_compare'] = '=';\n\t\n\t\t\t// Need to unset the original search args.\n\t\t\tif ( isset( $args['search'] ) ) unset($args['search']);\n\t\t}\n\t\n\t\treturn $args;\n\t}\n\tadd_filter( 'sul_user_query_args', 'kia_meta_search' );\n\n\nNow the search will return users that match the entered \"last_name\".  You can adjust as needed or use the `meta_query` array for more complicated meta queries.  \n\n\n\n\n\u003ca id=\"display_name\" name=\"display_name\"\u003e\u003c/a\u003e\n### How Can I Search By Display Name? ###\nBy default the WordPress search relies on username, though wih the `search_columns` parameter can be made to search the user's email or ID. Frankly, I think this is weird, but that's how WordPress works. \n\nIt is much more useful to search by the user's display name, however this requires 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.\n\n\n\t// Switch user search from user_login to display_name via query_where \n\tfunction kia_search_users_by_display_name( $query ) {\n\t\n\t  if ( isset( $query-\u003equery_vars['query_id'] ) \u0026\u0026 $query-\u003equery_vars['query_id'] === 'simple_user_listing' ) {\n\t     $query-\u003equery_where = str_replace( \"user_login\", \"display_name\", $query-\u003equery_where );\n\t  }\n\t\n\t} \n\tadd_action( 'pre_user_query', 'kia_search_users_by_display_name' ); \n\n\n\u003ca id=\"advanced\" name=\"advanced\"\u003e\u003c/a\u003e\n### How to create very complex user queries | How to query multiple meta keys ###\n\nIt isn't worth the effort to get the shortcode parameters to handle complex arrays. And in the end it isn't necessary as there are several filters in place to permit you to run a complex query. The key will be using the `query_id` parameter.\n\nFor example you could pass a specific ID via shortcode:\n\n\n\t[userlist query_id=\"my_custom_meta_query\"]\n\n\nAnd then in your theme's `functions.php` or a site-specific plugin, you could filter the user query args:\n\n\n\tadd_filter( 'sul_user_query_args', 'sul_custom_meta_query', 10, 2 );\n\t\n\tfunction sul_custom_meta_query( $args, $query_id ) {\n\t\t// Checking the query ID allows us to only target a specific shortcode.\n\t\tif ( $query_id === 'my_custom_meta_query' ) {\n\t\t\t$args['meta_query'] = array(\n\t\t\t\t'relation' =\u003e 'OR',\n\t\t\t\tarray(\n\t\t\t\t\t'key'       =\u003e 'billing_city',\n\t\t\t\t\t'value'     =\u003e 'oslo',\n\t\t\t\t\t'compare'   =\u003e '=',\n\t\t\t\t\t'type'      =\u003e 'CHAR',\n\t\t\t\t),\n\t\t\t\tarray(\n\t\t\t\t\t'key'       =\u003e 'first_name',\n\t\t\t\t\t'value'     =\u003e 'bobby',\n\t\t\t\t\t'compare'   =\u003e '=',\n\t\t\t\t\t'type'      =\u003e 'CHAR',\n\t\t\t\t)\n\t\t\t);\n\t\t}\n\t\treturn $args;\n\t}\n\n\nFor complex queries, you will want to read the [WP Codex reference on WP_User_Query](http://codex.wordpress.org/Class_Reference/WP_User_Query#Parameters).\n\n\u003ca id=\"pagination\" name=\"pagination\"\u003e\u003c/a\u003e\n### Does Simple User Listing work with WP_Pagenavi? ###\n\nYes! [WP Pagenavi](http://wordpress.org/plugins/wp-pagenavi/) supports pagination for `WP_User_Query` and I configured the navigation-author.php template to automatically use WP Pagenavi if it is installed and activated.\n\n\u003ca name=\"permalinks\"\u003e\u003c/a\u003e\n### I can't get the search users to work? ###\n\nThe search form will not work with the default permalinks. Try changing your permalinks to some other structure.  The reason is form submits via the GET method and so adding those parameters to the URL seem to clash with the parameters already on the URL from the default permalink setup.\n\n\u003ca id=\"fix-search\" name=\"fix-search\"\u003e\u003c/a\u003e\n### S2 Member Conflicts | The search doesn't respect the shortcode parameters ###\n\nLikely you are experiencing a conflict with another plugin, specifically one that is filtering `pre_user_query` to modify all user queries. The S2 Member plugin is a known culprit of this. To disable S2 Member's modifications on all Simple User Listing lists, add the following to your theme's functions.php or to a site-specific plugin. Ensure you are using at least SUL 1.5.3.\n\n\n\tfunction kia_protect_sul_from_s2() {\n\t\tremove_action('pre_user_query', 'c_ws_plugin__s2member_users_list::users_list_query');\n\t}\n\tadd_action( 'simple_user_listing_before_loop', 'kia_protect_sul_from_s2' );\n\t\n\tfunction kia_restore_s2() {\n\t\tadd_action('pre_user_query', 'c_ws_plugin__s2member_users_list::users_list_query');\n\t}\n\tadd_action( 'simple_user_listing_after_loop', 'kia_restore_s2' );\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhelgatheviking%2Fsimple-user-listing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhelgatheviking%2Fsimple-user-listing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhelgatheviking%2Fsimple-user-listing/lists"}