=== amr users ===
Contributors: anmari
Tags: user, users, reports, lists, members, membership, csv, export
Version: 4.18
Requires at least: 2.7 
Tested up to: 4.9.4
Stable tag: trunk

User listings, member directories, search, filter, export.  Digs deep into data created by other plugins to produce unified user listings.  

== Description ==

List, sort, filter almost any user data stored in the user meta.  Use hooks and add-ons to extract user data stored in other tables and present it as though it were user meta.

Helps developers to analyse, slice and dice user data without coding a whole application.  

Helps non-coders pull together various plugins and present member data cleanly for small to medium sites. NB See note about larger sites below.  Has ability to include, exclude and sort user data generated by a variety of other plugins who may NOT be using wordpress user meta as they should, thus making it hard to query their data.

Features:

*  Highly configurable user listings by meta keys and values, as well as additional computed fields, comment count and post count.
*  User search, bulk actions like delete, configurable action links, display, inclusion, exclusion, sorting configuration and an option to export to CSV. 
*  Make some lists public to use in a shortcode.  
*  Add-ons and filters available for integration with other user data tables and for special requirements (subscribe2 integration, cimy extra fields interation, multi site, ym (your members) )
*  Cacheing is used to improve the response for large user sites.  Cache can be updated on update of user records, or by cron job, or on manual request. Be aware that too frequent rebuilds of the cache may place a load on your system - choose carefully.
*  Pre-configured examples to get you started - you can add more or change these.  
*  Export and import settings from other systems
*  Show any list in a widget.

More information: [wpusersplugin.com](https://wpusersplugin.com/).

Demo site (includes plus functions: [user list demo](http://directories.wpusersplugin.com/) 

You may also be interested in:

*  amr-user-templates [a wordpress user admin screens plugin](http://wpusersplugin.com/related-plugins/amr-user-templates/). Simplify the admin screens (dashboard boxes, screen options etc) of any new users (or reset existing) by role. 
*  amr-cron-manager [wordpress cron job management and tools plugin](http://wpusersplugin.com/related-plugins/amr-cron-manager/)
*  amr-personalise [wordpress email and content personalisation plugin](http://wpusersplugin.com/related-plugins/personalise/)
*  helpful add-ons [amr-users addons for integration with other plugins](http://wpusersplugin.com/related-plugins/amr-user-plugin-add-ons/)


Note 1:If you have a extremely high user volume with high updates, a custom written, lean, mean solution may be more appropriate than this general solution.  That said,  the plugin has cacheing of user data and wp transient cacheing of the html generated to minimise performance load of extracting data from multiple sources, particularly for those on small shared hosts.  Set the cacheing side of the plugin up carefully considering your frequency of user updates OR rebuild the cache on request only.

Note 2: If you are thinking of using this to extract and report on S2member data, please read http://wpusersplugin.com/3086/user-lists-and-filtering-with-s2member-fields/ and be wary of using multi option fields. See also http://wpusersplugin.com/?s=s2member for other info.

== Changelog ==
= 4.18 =
*   improve inadequate protections against SQL injection risk on search strings

= 4.17 =
*   added provisional css class to be able to highlist active alpha navigation index - no actual styling.
* tested on 5.0 alpha

= 4.16 =
*   remove sortable html entity from RHS of sortable fields - inconsistent appearance
*   change sort direction html entity to use &uarr; and &darr;  for more consistent appearance.  CSS classes are available so you can override the appearance using css contet pseudo classes.

= 4.15 =
*  tweak to sorting to include numeric sorting for fields defined as numerical while still supporting UTF-8 special character locale based sorting
*  add indicators to column headings to indicate what column is being sorted.

= 4.14 =
*  emergency update - a user getting a parse error not experienced on other servers - missing bracket.  

= 4.13 =
*  re worked the multi dimensional array sorting to cope with UTF 8 characters and use the php collator class to sort arrays of user data as the locale would expect.  Note that different locales will sort different. Eg: sweden pushes some special characters to the end of the alphabet, wherees other locales will sort them closer to their Ascii equivalent.

= 4.12 =
*  some default css tweaks
*  some fixes to try cope with meta data stored in arrays and where filtering is desired
*  will  list array values as csv list in wordpress user listing if field is chosen for display there.
*  move some filtering message to debug only (ie when in debug mode & admin users)


= 4.11 =
*  Change table html - move tfoot to after tbody to suit html5 doctype validation which default wordpress themes use.  Non html5 doctypes may give a table validation error now.
*  Tweaked some css to make it look better in some wp themes. Plugin still generally tries to let the theme determine the look. 

= 4.10 =
*  Change css: remove tooltip class on user registered days ago span to prevent clash with bootstrap
*  Tweak: minor tweak to field types to prevent people changing wp field types and thus mucking up format options.  Also allows add-ons to addin field type settings. 

= 4.9 =
*  Fix:  CSV Filter (subset) will now have headings.  CSV of non public lists will be available but only to logged in users with 'list_users' capability. IE the csv will be realtime - no csv file will be created. The capability is filtereable in case you wish to impose a restriction.

= 4.8 =
*  Tweak: to add on updates page
*  Added a debug for situations when no records found for criteria, to look for interference

= 4.7 =
*  Fixed: If grouping config was saved, but then grouping plugin deactivated, plugin had wrong colspan as it still detected the saved grouping option and adjusdted colspan for it.
*  Fixed: If a search, or filter, or combination returned no records, pagination will no longer show (!) and message will appear in table as a full width column, and not as a error message before the list.  Thanks to Philipp Wiebe for picking this up.   

= 4.6 =
*  Fixed: Adding a new blank list will now allow you to choose fields.  Previously only copying a list gave you fields
*  Change: Excluded meta keys will sort by excluded keys first, then alphabetically.

= 4.5 =
*  Fixed: Fields that were not displayed could not be modified in the include/exclude screens - fixed.
*  Change: Emphasised fields/meta keys that do not exist for all users 
*  Change: Minor links added to assist admin users finding their way around the settings
*  Tweak:  Minor tweaks to multisite code, no major changes, but please check in case you were using a 'bug' where depending on the query setting selected, users not in a subsite may have been included in the list. 
*  Change: small changes to faciliate changes for amr-user-plus users - included navigation and filtering settings in the field settings screens

= 4.4 =
*  Fixed: Wordpress does not load admin text domain in front end. So if a website is not in English and a list includes roles, then the roles were not translated when the cache was refreshed in front end, but was in back end.  very confusing!
Plugin will now load the wordpress admin text domain IF it is being run in the front end, IF the locale is not en_US and, if the first role or roles is required in the list.

= 4.3 =
*  Fixed: a recent fix broke alpha navigation querying.  Tricky to debug and still keep possibility to have alpha nav and grouping working at same time as possibly also displaying the fields being used. Various combinations of settings tested and I believe the combinations work now.  Thanks to klaus_hh for flagging this.

= 4.2 =
*  Fixed: small bug where if using 'direct query' in network admin with amr-users-multisite, then only main site users were selected instead of all users in multisite.  If not in network admin then only the 'site' users are selected.
*  Fixed: id anomaly, which made it hard to use user_id in a list.  was a problem with array_unique.
*  Fixed: 'new' custom format bug where custom function was not being used when it existed.
*  Added text in config format screen to highlight that plugin needs to know the 'type' of a field before it can add custom format options.
*  Fixed: if headings were used in a grouping list, the grouping field heading was not being properly removed, particulary in front end of multisite
*  Initialised some variables better to remove notices if there were unsaved options

= 4.1 =
*  Fix of bug introduced in 4.0, where submitting update for format setting for fields, reset the sort settings
*  Changed message issued when bad data was sent to a date format routine.  Will only display to admin users and will fail silently for non admin users.  The bad data will display instead of date formatted data.


= 4.0 =
*  NB: Please check your use of "user registration date" or "registered days ago" after this update. You may need to choose a format. 
*  minor bug fix. Display of user_registered date was reported directly from the database and not converting wp's UTC date and time to the current timezone of the website.
*  minor bug fix - export wasn't exporting all the settings for a list (I guess not many folks using this as no one had complained except me!)
*  added ability to tell the plugin what kind of data a field held (see Fields & nice names far left)
*  added ability to choose from possible formats for fields that have a field type defined as per the previous point
*  merged and converted 'registered days ago' and 'user registration date'.  They are actually just format variations of the same field.  Therefore you can now choose the format for the user_registered field.  Basic format options available in amr-users.  More available in amr-users-plus and further more available over time.   These formatting functions are all 'pluggable', so you can write your own versions.
*  partial restructure of the configuration screens to reduce what appears on the screen while configuring because it got a bit too cluttered with the addition of the 'format' option. 


= 3.31 =
*  php 7 updates: standardised line endings and changed use of 'clone' to key word, not function.
*  some code tweaks to facilitate custom filtering for ranges, specifically for date ranges on date fields amr-users-plus-date-range

= 3.30 =
*  fixed fatal error that showed on some systems not others (not my local or my remote test system sadly.  was for an unusual addon setting. )

= 3.29 =
*  Added logic to permanently exclude without option to include, some meta keys to avoid the excluded meta keys screen being overwhelmed. [Mingle forum doing something that causes many, many metakeys to be created.]
*  Bug Fix in export list tool
*  Slight tweaks in default css for better amr-users-plus filtering options

= 3.28 =
*  Change: Increased display order field size as requested.
*  improvement to auto update for add-ons
*  simplified some of the config and overview admin pages, allowing one to press return on the configure page instead of having to remember to click the 'update' page.
*  Add: a mimetype (filetype) check on the list settings import - in case .txt not allowed (eg: multisite default)
*  Add: a filter 'amr_users_csv_before_export' to allow folks (eg S2member with their unix timestamps) to preformat before csv.
*  minor admin changes in attempt to simplify screens

= 3.27 =
*  Fix: non-english sites may not have been able to save excluded meta keys, and alternate 'nice names' if translations existed for buttons - due to stupidly overzealous submit field checking.  Thanks for Club corvette of sweden for highlight the bug. Tack!

= 3.26 =
*  Fix: some invalid html in admin - meta keys and find fields pages

= 3.25 =
*  improvement on fix to cater for include/exclude of numerical values of varying lengths in csv multi value fields

= 3.24 =
*  fixed exclude values in csv multi value fields
*  for websites whoe $_REQUEST is not functioning as wp expects, fixed bulk delete 

= 3.23 =
*   Change in various cases from using $_REQUEST to $_GET - some sites do not have their php setup so wordpress works as expected (wordpres merges $_GET an $_POST into $_REQUEST) and some sites have cookies overwritting $_REQUEST.  Sorting for example is only done via $_GET at moment.
*   Fix for situation where grouping users was breaking alpha navigation
*   Custom no access message for non public lists was not being used. Will now be used.
*   Tested on wp 4.4

= Version 3.22 =
*    minor tweaks so that default excluded meta keys can be 'unexcluded' should you wish to use them.

= Version 3.21 =
*   reversed out an extra escurl that was double escaping in pagination and causing problems when paging search results past page 1
*   add additional css so that lists of less than one page of users (ie no pagination appears)

= Version 3.20 =
*   verifying tested for 4.3 on php 5.4.3.  Double checked PHP 4 constructor situation.
*   tweaked page navigation css as something has changed and it was looking a little odd.
*   re-enabled 'own query' setting option that does not use the wp query to access user meta.  May be better for some especially if they dealing with missing user meta.

= Version 3.19 =
*   replaced help links to http:// with https://
*   fixed problem where wordpress was grabbing searches on homepage before the plugin could deal with the form
*   spaced out admin reset buttons a bit more to avoid accidental pressing

= Version 3.18 =
*  fix stripslashes that were added to deal with apostrophes in filtered values had to become 'deep' to cope with multiple choices for input selection. (eg: checkboxes)

= Version 3.17 =
*   checked all instances of add and remove_query_arg, added esc_url where necessary or for comfort sake
*   fixed an odd occurrence where if you clicked rebuild under the overview section it had not loaded the pluggables file.  It had been loading on other rebuilds which is why it was so puzzling. Aplogies for not picking this up before (I never use that admin link!)

= Version 3.16 =
*   reversed out recent addition of version number showing on update license page as it was messing up some update checks

= Version 3.15 =
*   some updates to the add on updates license page, to show version numbers and more informative error message
*   Fix: sometimes filtering location setting was greyed out when it should not have been

= Version 3.14 =
*   edit user link type will go to normal edit user unless the list is being run in network admin, in which case the url will be the network admin url.
*   will now deal better with apostrophe 's and ampersands in data when you are filtering on the data 
*   a fix for annoying gf address fields broke some s2member capabilities when there were single roles (yes roles and first riles still worked, but if you wanted to show or select by a single capability / role field that was broken when there was only one role (weird I know, but the best bugs are!)

= Version 3.13 =
*   updated 2014 11 22
*   tweaked filtering to allow realtime selection of multiple values for same field. (Needs amr-users-plus for full functionality or own html)
*   added settings page for add-on users only to enter update keys for automatic addon update checking
*   quick test on 4.0.1

= Version 3.12 =
*   updated 2014 11 02
*   restested with add-on functions to ensure pluggables working as intended, uploading as new version to avoid confusion with forum message. very minor code changes only with no major effect on functionality.

= Version 3.11 =
*   updated 2014 11 01
*   make the pluggables folder load later to make the functions truly pluggable
*   added aliases to queres with joins to avoid potential confusion.
*   added a phone field formatting function (currently only used for S2member phone field in add-on)

= Version 3.10 =
*   updated 2014 10 10
*   facilitated addition of a roles (multiple roles field) and a first_forum_role if you have bbpress installed, and you are using amr-users-plus 2.12 or higher.
*   improved sorting of fields on list configuration screen
*   improved the magical ability to generically dig deep into strange user meta and deal with double serialised gravity forms user meta that contain associative arrays inside numerically keyed arrays.  For now it will only extract and use the first numeric entry.  Examples used were 'Emergency contact' that had 4 associative fields.
*    hide a debug message unless you are admin and site is in debug mode
*   added ability to filter row css so that one can add one's own css classes based on the values in the row or for the user for that row. add filter for: amr_add_css_class_for_row($class, $line, $user)
*   added odd and even css classes to users (rows or alternating divs for the html5).  Of course for the rwos you could use the tr:nth-child(odd) pseudo classes, but for the html5 option this does not work (although if they had been setup as lists it might have.

= Version 3.9 =
*  added ability to exclude user meta keys from the plugin. This became necessary for folks using S2member access cap times.  It seems S2member store an array of these keyed by the time.  When the generic 'find fields' attempts to break out this meta-key into it's components, we end up with an ever increasing list of 'fields' as time goes by.  This update allows you to exclude that meta-key and others from the plugin so it will not bother trying to dig deeper into that data.  See also: http://wpusersplugin.com/4147/exclude-meta-keys-delete/
*  added ability to delete meta records for selected metakeys (help cleanup)
*  added totals to fields and nicename admin screens and highlighted that some meta keys excluded

= Version 3.8.6 =
*  small fix on csv export of empty lists to remove warning (thanks Joe!) and cleaned up code to ensure any existing .txt files also deleted when a list is no longer public.
*  comment count has changed: it is now pluggable so you can write your own query function. The existing query function now queries and totals by userid only.  If a registered user changes their email address this will not affect the comment count. However comments made when unregistered will not be included even if it was with the same email.  Comments from unregistered users are not currently included.  This could be done with an add-on (not yet available) if desired.
*  comments by author link has changed.  It no longer links to wp stats.  It now links to the edit comments author page (so admin users only) and passes the current email only.  Note that the comment page will show comments posted by a person when they used that email address. They may have changed email addresses, they may have registered after they posted comments.  Thus the list may vary from the comment count in the list. 


= Version 3.8.5 =
*  small fix  for anyone who absolutlty has to use 'field' value filtering (where field is one of many in a column).  Rather use column value if you can.  Avoid urlencode call on an array (when saving filtering values in urls for sorting and pagination while filtering.)

= Version 3.8.4 =
*  fixed recently (?) introduced bug where after certain sequences of filtering, sorting and then going to anything other than first page, a blank page was returned
*  Clear filters will now clear the search term too
*  You can now search and filter at the same time (and yes also sort)
*  moved 'before' and 'after' fields to far right of configuration table to make include/exclude and sort columns more visible.

= Version 3.8.3 =
*  fixed start empty that stayed empty after 3.8.2
*  fixed sort bug on some fields that began recently
*  restored ability to switch off sorting
*  restored ability to hide headings

= Version 3.8.2 =
*  fixed search count bug / pagination related bug introduced in 3.8.1.
*  improved some ability to do search and filter together.  
*  widened css for filtering form labels(the 'above table' version)
*  added help in custom headings configure page so people will rather use nice names unless combining fields - else confusion may happen.

= Version 3.8.1 =
*  Change: Moved to submenu options some settings that were behind tabs on general screen.  As requested by various folk to improve access to "find Fields" and "overview"
*  Fix: very minor fix to delete option if value is empty rather than updating it - this was causing an update option failure result (non serious).
*  Fix for ampersands in values - moved esc_attr to close to output to avoid impacting comparing filter values. (Note filtering with values with encoded ampersands in DB (eg in some wp fields like 'last name') will not work now due to wp default filters. See trac issue 11311.  These fields should not be stored in db with escaped &, as the & is only 'special' with respect to output, html and urls.
*  Fix: added some missing text domains

= Version 3.8 =
*    UNSTABLE
*   filtering is more 'tight' now - there was some fuzzy filtering becuase some fields had comma sepated multi value strings and some had comma space separated multi value strings. Plugin will detect and handle accordingly.  It will also now deal better with filter on fields with numbers of varying lengths eg: 1,10,100
*   bug fix when filtering on numeric fields of vaying lengths with possible multiple values per user (eg: if your codes were numeric and inconsistent lengths)
*   small bug fix on date time displayed in cache status when no cache entries available.
*   tidied up some spacing on cache settings page in chrome.
*   Fix: if no field was chosen to add to default wp list, this gave a warning. Fixed.

= Version 3.7.1 =
*   added code to deal with sites who have not yet saved their timezone string and/or have a blank timezone string.  Defaults to UTC.
*   made multi site network admin detection better - avoid inadvertently thinking one is in network admin if there was a 'network' in the url! (duh)
*   added code to cope better with the nested s2 member custom fields - including the multiple value custom fields.  The code in 3.7 that coped with non associative arrays kinda broke the S2 member custom fields.  Please don't use the S2 custom fields if you can help it - until such time as they store them as normal user meta.
*   added space to comma between certain multiple value fields so they looked prettier.

= Version 3.7 =
*   adds ability to extract a csv version of a filtered list.  Works with version 2.9 of amr-users-plus which has csv extract of filtered admin lists.
*   changed handling of user meta values that are not associative arrays.  The values will now be treated as though they should have been stored as multiple meta records with same key.   This gets around a problem with the way that ACF stores multi value fields (select etc)
*   reset and refresh of the 'fields and nice names' will reset some related options.
*   added some debugs for a person with possible corrupted options
*   added code to deal with situation where list 1 deleted and/or ALL lists deleted

= Version 3.6.8 =
*   reversed out the new wp user list sorting until further testing - affecting some sites with warning on array keys.  

= Version 3.6.7 =
*   fixed double quote bug (clash between db escaping and csv requirements).  Both csv and list display with before and after fields that have quotes should work
*	fields that can be added to the main wp user list are now sortable (if they are simple user meta fields)
*   fields that are not simple user meta fields are highlighted in the 'find fields' settings
  
= Version 3.6.6 =
*   removed db query to check wp user table names. Plugin will use precoded known user master fields for main wp user table.  The check kicked in after wp 3.3 and was adding unnecessary query load.
*   allow user activation key and user status fields to be used if desired (were previously excluded)
*   added ability to mark fields for inclusion in the main wp user list. Useful if for example you wish to show the id or the user registration date in the main list. See general settings > fields and nice names.  Rudimentary implementation to start.  It simply includes the fields using the formatting routine.  This will only work for fields in the user and user meta tables, or fields related to those (eg: registration date has two formats).  

= Version 3.6.5 =
*   fixed bug introduced in 3.6.4 - handle single quotes in text fields and double quotes in csv double quoted fields. 

= Version 3.6.4 =
*   add css workaround for sites that use themes that insist of adding wpautop filter and webmasters who don't know how to get rid of the wpautop on post content after shortcodes applied. (Too many support questions that think it is a plugin bug. It's not!   The css styles out the break <br /> that happens if wordopress wpautop function is applied to html produced by wordpress paginate_links function.
*   fixed bug which happened on includeonlyifblank
*   replaced $wpdb->escape calls - now deprecated
*   added user_registration_date as a standard field.  For compatibility with prior versions and not to mess existing users up.  user_registered is staying as showing 'days_ago'.  Run 'find fields' to get it to show up.
*   tested on wp 3.6

= Version 3.6.3 =
*   Tested with amr-users-plus 2.7
*   Removed use of &nbsp; for empty cells.  If you have tables with borders in your front end, please check that your css handles table empty cells acceptably.
*   Added: a remove filter wpautop in the shortcode - some folks having problems in their setups with possibly other plugins or themes adding wpautop which then adds stuff we don't want.
*   Changed: changed code that deals with filtering, exclusions/inclusions in attempt to tighten code for folks whose systems are experiencing problems.  I have not been able to replicate the said problems on my system, however could see some room for minor code improvement. Hopefully this will help.
*   Added: id="usertable" to the html table as per request to be able to use jquery datatable for consistency.
*   Added: As per request added option to show record totals (and css to float it to the right).  Use shortcode parameter show_totals=true to add record total to front end list.  

= Version 3.6.2 =
* Fix: CSV and TXT export for non-public lists for users who have at least list-users capability fixed.
* Add: Filter added for csv export capability. $capability = apply_filters('amr-users-export-csv', 'list_users', $ulist);.   Filter function will receive the list number too.  This means you can therefore customise capability by list if you wish.
* Improvement (I hope):  more 'human' time for some time related fields.  I have some very 'old' users and it was driving me nuts seeing large numbers of days.  Will now show probably the two highest of years,months, days, minutes.  It is pluggable so you can override this should you wish. See the pluggables file.  For php 5.3 users only as it uses the datetime intervals.
* Tweaks: for an improved login logger and failed login simple plugin - see wpusersplugin.com
* Add: formatting for ip address fields.

= Version 3.6.1 =
* Fix: for multi-site users using the multisite add-on. (Should be no affect on non multisite). There was a clash between the network admin and the primary blog in some circumstances. I have tested back/forth resetting all over, however please test carefully for your multisite.  The network admin level will probably need to be built again.  Apologies, however an essential fix for multi site users who were running the plugin at network admin and in primary blog.  Note: do not need to 'network_activate' amr-users, only amr-users-multisite.  The amr-users-multisite addon will pickup the code from amr-users if it in the plugin folder.   Network activating  forces all sub sites to have user lists.  If they do not want / need this and don't delete the default lists, this may place unnecessary load on the system.  The plugin can be separately activated by subsite admins if desired. 
* Add: can now add-in social media profile links.  (It's an add-on to enable complete styling to your theme, without making the main plugin more complicated and retaining ability to upgrade.) See http://wpusersplugin.com/related-plugins/amr-user-plugin-add-ons/amr-users-plus-social/

= Version 3.6 =
* Minor fix to link type generation
* Added a filter to enable add-ons to add selection html within the 'form'.  This was specifically for a request to be able to count posts within two entered dates
* Formatting for Social Media links using css sprites will be available within days.  It will be implemented as an add-on because the look and style are quite theme dependent.  Add-ons alow you to customise the add-on and retain the ability to upgrade the core plugin.  The formatting functions are all pluggable.

= Version 3.5.5 =
* Change (minor): analysed and tweaked some wpdb calls in view of wp adding 'warning' on 'prepare'.
* Add: ability to call or use network user lists (with amr-users-multisite 2.3) in a public way using shortcode
* Fix: csv link went wobbly in certain situations 

= Version 3.5.4 =
* Add: ability to search with multiple keywords (ie default 'or' type search ala google) or  to use quotes to force a phrase search 
* Tested: with version 2.5 of amr-users-plus, should work with earlier versions too.


= Version 3.5.3 =
* Fix : some language translation domain inconsistencies


= Version 3.5.2 =
*  fix - for translators as requested by Keisys Shimizu (Japanese translation).  Some text strings were not properly setup for translation.
*  fix (in amr-users-plus 2.4) - escaped the unencoded ampersands appearing the alpahbetical navigation urls.
*  add (in amr-users-plus 2.4) - added a "novalues" span class to the alpahbetical navigation.


= Version 3.5.1 =
*  fix - a small change (from checkbox to radio button) to make the caching on user update setting more obvious was not adequately tested. Not my usual standard - Apologies and many thanks to Gill for reporting it.

= Version 3.5 =
*  fix public csv multisite link bug.
*  add ability to request an empty start page - results to show on request only.  use start_empty=1 in your shortcode. ie: [userlist start_empty=1]
*  add some randomness.  Note using mysql order by rand is inefficient and could be a problem for large data bases. So alternatives are used. See http://snippetsofcode.wordpress.com/2011/08/01/fast-php-mysql-random-rows/ and http://stackoverflow.com/questions/1244555/how-can-i-optimize-mysqls-order-by-rand-function
*  add ability to request a random start page ( a semblance of random for large lists).  Add show_randompage=1 to shortcode or url for testing.  [userlist show_randompage=1]. Note: Specific page requests or Pagination will override.
*  add shuffle of page results (aimed at either small lists that are fully displayed, or giving a semblance of randomness - possibly use this with start random page).  Only the subset of results to be displayed are shuffled, not the whole list. Ie ona given page the same users will be shown at any point. [userlist shuffle=1]

= Version 3.4.10 =
*  fix little bug if you have lots of lists and have deleted some lists in between others.
*  make user update cache setting a radio button for clarity

= Version 3.4.9 =
*   tweak to bbpress profile link to pickup forums and users slug from the bbpress options in case they are changed.

= Version 3.4.8 =
*   Argh: seems other plugin developers have also tried to get around the sometimes missing is_plugin_active function which then causes clashes - workaround designed not to clash and still use wp function when it can.
*   Add: added a bbpress user profile linktype as per request
*   Change: changed default NOT to cache on user update - causes too much load and is not necessary for most.  Also highlighted text that emphasies potential system load if too frequenct cacheing is enabled.
*   Add: set default exclusion from report config of some usermeta fields that one would not usually  need.  You can switch them back on if you really want to!
*   Fix: Delete from configure screen was not working - is now.  Overview screen delete was working.
*   Fix: for complex cimy addons with multivalue fields combined in a column
*   Fix: set priorities for calls to filters, so they always work in same sequence regardless of plugin activation sequence - was affecting alphabetical navigation with cimy fields

= Version 3.4.7 =
*   Fix: is_plugin_active wp function not available on front end and declared late in backend ... painful


= Version 3.4.6 =
*   Fix: non public csv will work form ore than just list one now!
*   Fix: if 'amr-plus-grouping' deactivated, but configuration data still there, will treat as deactivated.
*   Change:  On Update of overview settings (includes public tag), all public csv lists will be purged.  They will be rebuilt on refresh of the public lists.
*   Change: some minor changes to test queries

= Version 3.4.5 =
*   Fix: small fix, last version broke the plus alpha navigation filtering

= Version 3.4.4 =
*   NB: Tested with wp 3.4.1, amr-users-plus 2.2
*   Add: for advanced uses: add parameters to shortcode
*   Add: ability via plus module to list users 'grouped' by a field, requires amr-plus-grouping
*   Add: ability to switch pagination off and only show the 'top' x results
*   Add: some flexibility in the widget - switch off pagination and link to a member list page
*   Change: Added a html selector on the list footers so that one can use css to clear the floats. Added default css too.
*   Fix: widget defaults cleaned up
*   Fix: make search string sanitisation slightly less restrictive and consistent with with wordpress normal search string sanitisation.
*   Fix: import list access problem that had crept in
*   Fix: Copy option back on admin overview



= Version 3.4.3 =
*   Change: "rebuild now" will rebuild and view instantly
*   Change: tweaked some of the admin UI a little (minor)
*   Change: added a little bit of oomph to default css  for non table.  Avatar shadow ala stack overflow and bigger display name ala smarterer.com 
*   Tested on 3.4 and latest nightly build for 3.5
*   Add: flexibility of display by making more of the display functions pluggable. See http://wpusersplugin.com/documentation/formatting-and-pluggable-functions/


= Version 3.4.2 =
*   Add: a formatting filter so you can add special formatting, useful for example to format S2member registration times that are stored in unix time stamp.  See example going up soon (free) amr users plus s2member. Usage add_filter('amr_users_format_value','yourfunction')  Your function takes 4 parameters: ($text, $fieldname, $value, $user);
* 	Fix: handling of ym(Yourmembers) object usermeta got briefly 'lost' is fixed now. 


= Version 3.4.1 =
*   Fix: finding new fields had a bug due to a bad debug statement left in - fixed.  Thanks for flagging elurie!
* 	Change: added a 'distinct' to the schema lookup on main user fields so it only finds them 'once' (hah!)

= Version 3.4 =
*   Add: new html style for simpler nontable directories - makes for more interesting layouts with css 
*   Add: Tools to export /import user list settings
*   Add: ability to limit the provided css to certain pages rather than all pages on front end  
*   Change: slight changes to html to aid seo of public lists for google rich snippets
*   Change: default lists have changed
*   Change: settings menu structure hopefully neater
*   Fix: some problems with exclusions 
*   Fix: multi value fields not always well handled wrt filtering - depends how they were setup.  To cope with more scenarios, a filter will match if the value is 'in' the field eg: Filter on "Dentist" will return "Holistic Dentist" and "Dentist".  To avoid that, use unique values rather. eg: "Holistic Dentist" and "Normal Dentist".

= Version 3.3.6 =
*   Fix: a bug in 'including' ie filtering users with some user meta fields
*   Fix: foreign characters will work in before/after fields
*   Fix: cached html was preventing sorting when cache in use.  Transient Cached html will not be used when sorting
*   Fix: Delete uninstall had a bug - fixed
*   Add: More enabling for custom navigation like alphabetical navigation coming soon in 'plus'
*   Change: Moved out of the 'general' tab, the stats section that check queries against your db.  Large db's on slow or low memory sites may have problems when testing the stats.  This can make access to settings awkward.

= Version 3.3.5 =
*   Dummy update to see if wp will update the version number
*   Includes provisional code for custom or alphabetical navigation available soon in amr-users-plus

= Version 3.3.4 =
*   Add: Some changes for better multisite integration if amr-users-multisite available
*   Add: some html cacheing using transients for initial display only
*   Fix: pagination on filtering, searching

= Version 3.3.3 =
*   Fix: if using amr-users-plus-ym addon, and had ym fields then checkbox was aimed at ym, not bulk delete - now will cope with either.
*   Fix: removed ability to hide 'ID' from configuration.  If someone hid the id, then checkboxes etc do not function.  Id need not be displayed, but must be available.

= Version 3.3.2 =
*   Fix: multi level sorting went a bit loopy after a change for php 5.3.  Fixed.  Can now sort up to 5 levels deep.
*   Change: main settings - the info boxes will be closed on initial viewing
*   Enable: ability to do ym (your members) plugin updates in bulk from a bulk selection in list added.  This appears if there is a ym field in the user list. Requires the [amr-users-plus-ym addon](http://wpusersplugin.com/related-plugins/amr-users-plus-ym/) .

= Version 3.3.1 =
*   A version upgrade check and a Deactivate will now drop the cache and logging tables.  Don't panic - they will be created again when necessary. This ensures that any table changes required will be done. It also helps reset the autoincrement counter too which was causing some problems in larger, more active sites.
*   Reset all options will also drop tables (resets autoincrement).  
*  	Clear all cache entries will truncate tables (emptying them and resetting the auto increment).
*   Add: added option to switch off auto cache on user update - cron or manual cacheing only.  For sites with lots of user activity and possibly other plugins causing frequent updates.
*   Fix: an incorrect message when no search records were returned
*   Change: flag set so will only do cache update request once per page updates (It can trigger on user update and  meta update - batch update request will only trigger on first one. 

= Version 3.3 =
*   Add: use transients to better prevent runs overlapping
*   Change: changed array sorting to avoid php 5.3 call_user_func_array bug when using using array_multisort
*   Tested: on wp 3.3

= Version 3.2.1 =
*   Add: ability to copy and delete list individually
*   Fix: Refresh link text & overview settings temporarily got stuck - fixed

= Version 3.2 =
*   Added: alternate method to fetch data to hopefully use less memory - tested so far with 8,860 users, 117,839 user meta records and 34 different user meta keys - used 118 Mb, took 4-10 seconds.
*   Change: cache updates now done in batches of 1000 to avoid mysql time errors
*   Change: changes to admin screen to allow quotes, slashes etc.
*   Changes as requested by S2Member users who have multiple choice custom fields (ie an array as the nested value)
*   Changes to reduce memory usage and mysql usage (exclude any nicename excluded mainfields)
*   Add: Changes to allow addition of filter functionality if add on plugins are activated (for filtering or s2 integration)
*   Change: Search tweaked a bit to allow search as 'or' on search terms.
*   Fix: top checkbox will now check all checkbox lines if ticked
*   Fix: bottom bulk action was not working correctly - fixed


= Version 3.1 =
*   Add: custom headings, instead of nicenames.  See edit headings link from configure screen or view screen.
*   Add: improved verion change checking - auto rebuild of nicenames when upgrading.
*   Fix: foreign language characters were displaying strangely in admin before/after fields. fixed.
*   Removed: facebook like inside the plugin - decided I did not 'like' (huh!) that one could get people to like a page that they were not on.  Changed to a link to plugin website.

= Version 3.0 =
*   Add: search within cache.
*   Add: bulk delete from selection
*   Add: filter the list from the url query parameters, hide or show the filter column ?filter=hide&column_name=value
*   Add: front end download of csv file (public reports only)
*   Add: per page specification from list
*   Add: exclude some fields from all list configuration - slight reduction in memory, and simpler lists.
*   Add: memory tracking code when cacheing when WP_DEBUG on
*   Fix: pagination on last page not quite right - fixed.
*   Change: if report not cached will rebuild in realtime immediately, do not have to request

= Version 2.3.14 =
*   removed use of WP_PLUGIN_URL and _DIR as when not defined, other constant setup went slightly wonky.
*   also on some php hosts, the sequence of includes meant that the !function_exists test did not always work as expected.

= Version 2.3.13 =
*   dummy update as it looks like a file previously uploaded was corrupted and svn would not reupdate without a change.

= Version 2.3.12 =
*   add code to trap and handle odd warnings experienced by some users on subscription.

= Version 2.3.11 =
*   tweak to allow pluggable functions so you canformat each field any way you like.  Existing formatting functions are pluggable and you can add your own using the technical field name and prefix with ausers_format_xxxx_xxxx.  See the ausers-pluggable.php file.

= Version 2.3.10 =
*   added code back to cater for wp < 3.1 still using deprecated functions
*   added check for tables required in settings as activation hook in wp does not always fire.   

= Version 2.3.9 =
*   fix to prevent warn ing being issued when all reports rescheduled on user update (allow no list parameter
*   found and replaced another deprecated wp function

= Version 2.3.8 =
*   renamed a function that clashed with another plugin's function
*   change WP_SITEURL to siteurl()
*   removed some deprecated code
*   fixed (i hope) the cacheing status 'in progress' bug that was happening for 2 and 3rd reports 
*   fixed the rss news bug

= Version 2.3.7 =
*   small one line fix for when sorting lists - ie initial sort is fine, but sorting columns when viewing gives error.  Bug was introduced when a change made for php 5.3 users - sorry!

= Version 2.3.6 =
*   A quick fix - need highlighted by Phil wanting a custom gravatar url to produce an img tag.  Before and after html will now cope with double quotes.  Please note if you have special before/after code, this will be in yiour csv file too. A way around this would be to have a separate simpler list for csv export.
*   Now you can build reports on custom post types too!  Amazingly useful for one of my other projects that I'll be telling you about soon.
*   The admin settings screens will now not show a field if it is not switched on, or used for ordering or selection - the page should render faster now. 
*   Option to switch off the css provided - see settings overview


= Version 2.3.5 =
*	Can now deal with content that has quotes etc - add slashes and strip slashes.  And of course foreign characters work too - just make sure you have all your encodings sorted in your wp site and open office or excel. See the plugin site formore info 
*   CSV Filtered option renamed as .txt export option with some other tweaks too - see the hover text.  Aimed at those poor ms excel users... maybe it will help a bit. 
*   Added ability to request regular rebuild of cache for those who have plugins that do not trigger the update of the user profile.   

= Version 2.3.4 =
*	Changed display order to allow decimals and interpret decimals as follows: 3.1 and 3.2 mean the first and second values in the third column.  This should give a lot more flexibility in formatting, although I think still need flexibility in applying links, and in css without having to mdofiy theme etc - it's coming....
*   Added 'before' and 'after' fields so you can add html around the values, especially if combining fields. Eg: a "&nbsp;" or a "<br />".  
*   Bug Fix on sorting, now sort values before applying links etc, and before paginating!

= Version 2.3.3 =
*	Bug Fix - Plays better with S2member now - I'm embarrassed, I'm not even going to tell you what it was.   
*   Fixed a few other minor details that were annoying me - highlight some text on the log screen etc.
*   Add option to rebuild cache for ALL reports in one go.

= Version 2.3.2 =
*	Added option to not have sorting links on the lists.  Specify this next to list name in main settings.
*   If you run lists without configuring nice names, plugin will attempt to make column headings look nice anyway.
*   Bug & Feature Request Tracking Proper Bug notes with adequate detail and Feature Requests may be logged or voted for at [bugs.anmari.com](http://bugs.anmari.com).  the $vote is an indicative amount to indicate how much you want a feature.  

= Version 2.3.1 =
*    fixed bug for versions less than 3.0 that do not have the list-users capability.  User List access also allowed if user has 'edit users' access.
*    switched defaults headings request for shortcode, so that by default headings will be shown.  If you do not want headings user headings=false in the shortcode.
*    Added option to have "carriage returns" filtered out of your csv export lines as requested by [wjm](http://webdesign.anmari.com/exporting-a-wordpress-user-list-to-a-csv-file/#comment-4311)
    
= Version 2.3 =
*    Widget is now available in a rudimentary fashion.  Please ensure that you design reports carefully, not too many columns, and not too many entries.  It is using the same code as the shortcode, without the headings.  Some themes do not take kindly to tables in the sidebar, so please test thoroughly with the size of data and theme you expect to use.
*    Changed capabilities to use new in 3.0 'list_users'.  So now if user can 'manage options' they can configure the reports.  If they can 'list users' they can access the user lists and export to csv too.
*    Fixed 'privacy' bug - an editor or person able to publish posts would have been able to access the user lists via shortcode even if they did not have capability to 'list users'.  Each list now has a public checkbox.  Only 'public' lists may be accessed via the shortcode by people who do not have the 'list users' capability.  If the shortcode requests a non public list, rather than display a visible error,  a comment will be written to the page for your information when testing.
*    Removed forced ID in first column on display - still appears in csv. Is required in cache for additional field functions on display.
*    The user url column will now contain clickable urls if you request that column to be displayed.
*    CSV export link had the wrong hover text, although it did the right action - fixed.
*    Removed the superfluous links at top of view user lists - use the links in the side menu.  These were causing a problem for some people in some browsers.


= Version 2.2.3 =
*    fixed situation where many lists, or long names caused the nav menu to be off the page in some browsers.  Added whitespace: normal to override wordpress admin default styling.  Thanks to wjm for bringing it to my attention and his suggested code. See http://webdesign.anmari.com/exporting-a-wordpress-user-list-to-a-csv-file/comment-page-1/#comment-4311
*    other minor html generation and/or css changes.
*    tested in wp 3.0.  Added some additional "excluded" fields added or changed in wp 3.0 to avoid cluttering up the list of possible fields.  See ameta-includes.php for the list.

= Version 2.2.2 =
*    CSV bug fix - last line was being missed on csv export!


= Version 2.2.1 =
*    Apologies - a little bug got introduced when users do not values in some fields - use version 2.2.1 or 2.1.

= Version 2.2 =
*    Applied a bit more rigour to the code, no major functionality change.
*    Added the limited comment total functionality back with a warning about it's usage - see href="http://webdesign.anmari.com/comment-totals-by-authors/
*    Fixed bug where htmlentities was used instead of htmlspecialchars.  This messed up foreign characters.
*    Added security check that only users who can edit-users may rebuild cache etc. NOTE: there is no seurity check on who can see lists via the shortcode.  If you create a list and make it availble via shortcode, you are responsible for controlling access and/or determining the data displayed.


= Version 2.1 =
*    Fixed bug for people using php < 5.3 (me! too) and who may have had a comma in their user meta data.  The php function str_getcsv does not exist until php 5.3, and  my quick pseudo function did not anticipate commas within the user meta data (bad).  It now does although still a simple function tailored to this specific use.  So it has been renamed and if another plugin has defined a str_getcsv function, (or if using php 5.3 up), then that function will be used.
*    Also ran quick test using a wp 3.0 beta instance and all seems fine. 

= Version 2 =
*   Major change for sites with many users - all reports are prepared in background and cached.  New cache requested after every user update (at this point std user events only).  You can also request your own updates.  Currently no regular cache update set, but most likely this iwll be done in a future version.
*   Background Events are logged for visibility of what caused a cache request.  Log is cleaned up regularly.
*   Cache Status page 
*   'Role' added - this is not actually stored in the user meta tabel, but is 'prepared' or calculated by wordpress.  Many roles are allowed for.  The current version of wordpress just pops the first role up and serves it up as the role.  I have therefore called this 'first role' in case anyone has configured others.  You can of course change the name via the nice names settings.

= Version 1.4.5 =
*   Allowed for less than wordpress 2.8 for non essential plugin news in admin home
*   Allowed for situation where user has not configured 'nicenames' at all

= Version 1.4.4 =
*   Added exclusion of deprecated duplicate fields (eg: wordpress currently returns both user_description and description, regardless of what is in the database. Only the latter is required now).
*   0 post counts and comments will not be listed
*   if plugin wp-stats is enabled and a stats page has been specified in it's settings, then any non zero comment counts will link to a list of comments by the author (Note this only applies to registered users)
*   Fixed problem where updated nice names where not being correctly accessed.

= Version 1.4.3 =
*   Fixed addition of extra lists - now uses prev list as default entries.  NB Must configure and update before viewing.
*   Added RSS feed links to highlight any plugin related news

= Version 1.4.2 =
*   Hmm now using get_bloginfo('wpurl') not get_option!! - otherwise if no WP_SITEURL defined in config, admin loses colours!

= Version 1.4.1 =
*   Defined WP_SITEURL if not defined, using get_bloginfo('wp-url') (not 'siteurl') so both wordpress relocated, and standard wordpress will work.

= Version 1.4 =
*   Changed get_bloginfo('url') to get_bloginfo('siteurl') for those that have wordpress relocated
*   Put the CSV export back - got temporarily lost due to adding possibility of not having it on the front end 
*   Thanks to kiwicam for quick pickup and detailed specific response!

= Version 1.3 =
*   Changed WP_SITEURL to get_bloginfo('url') for those that do not have WP_SITEUEL defined (was in edit link)
*   Added column titles to the csv file
*   Made some updates as suggested by http://planetozh.com/blog/2009/09/wordpress-plugin-competition-2009-43-reviews/.  Note that as we are not running any DB update queries, some of the comments are not strictly relevant.
*   added ability to access a list via shortcode. Your Themes table styling will apply.
*   improved ability to select data - can include only blanks, or exclude if blank.
*   the following fields will automaically be hyperlinked as follows:
*       email address - mailto link
*       user login - edit user link 
*       post count - author archive link

= Version 1.2 =
*   Fixed bug that had crept in where some aspects were not updating in the admin pages
*   Fixed problem with multiple exclusions and inclusions
*   Changed empty to check to null check as 0 is considered empty, but may be a valid inclusion or exclusion value.
*   Changed admin area to separate pages in attempt to simplify the setup.

= Version 1.1 =
*   Allowed for situation where there may be no user meta data for a user record.
*   Tested on 2.8.4

= Version 1.1 =
*   Fixed an inappropriate nonce security check which caused a plugin conflict.

= Version 1 =
*   Initial Listing

== Installation ==

After activation default lists are available. 
  
1.  Create sample data for your users for any new fields
2.  Goto Settings, see 'find fields'.  Execute to find any extra user fields you may have (NB: sample data must exist in your install).  If your fields are not found, you are probably using a third party plugin that does not store it's data in the wordpress user meta.  There are add-ons for these.  See at http://wpusersplugin.com/
3.  Configure the default lists or add listings in the settings panel.   Your newly found fields will be available when you configure the list.  Do not add more lists than you need, unless you are manually cacheing them.
4.  For public lists, create a page or post, enter the shortcode in text [userlist list=n].  Note some minor css is added but can be switched off or set for user list pages only.

Later: Think care fully about the cacheing options - consider the number of users you have and volume of updates.  If lists are admin only - they can be manually rebuilt as needed rather than updating all the time.


Before: Please check your system meets the following requirements:

*	PHP > 5.2 
*	The filter extension is enabled by default as of PHP 5.2.0 http://au.php.net/manual/en/filter.installation.php
* 	The DateTime Class enabled (should be in php 5.2) http://php.net/manual/en/function.date-create.php



== Screenshots ==

1. Default list 1
2. Default list 2
3. Meta Keys - exclude and delete tool
4. Fields, nice names and option to show in wp
5. Select fields to display and sort order
6. Format fields 
7. Include or Exclude
8. Simple list with filtering (needs plus add-on)
9. Simple list with navigation (needs plus add-on)
10. Configure a simple list to put in the widget.
11. List in twenty twelve theme wih no additional css.
12. Add on social media profile links. available via add-on so it can be tailored totally to your theme.
