Excel user list export

Excel Download from Custom user list

amr users plus version 3.6 up includes the ability to offer a direct excel export of the user list data, instead of, or as well as the .csv export.   It needs the phpoffice/phpspreadsheet library to be available (see below)


excel wordpress user export demo.


  1. Make the phpspreadsheet library available. There is an easy low tech way to do that by adding the cbx plugin https://codeboxr.com/php-spreadsheet-library-wordpress-plugin/ or via composer. For instructions click here.
  2. Tick the ‘xls export’ checkbox in the userslists overview settings. (Similar to the existing .csv option). and then view the list and test it!
excel icon or text link
In the general settings you can specficy the icon or text link for the excel export
Option to display excel export or not
To offer the excel export option in a user list on the front end, tick the checkbox

The XLS export will not function if phpspreadsheet and the writer class are not found.

On demand filtering on a new field

How to filter by a field not currently displayed?

(requires amr-users-plus

  1. Enter some data for some users.  Ideally all users should have a value for that field.  Plugin will show a ‘-‘ for users with a blank value.
  2. Display the field (possibly temporarily)
  3. Define the filtering
  4. Rebuild cache  (will soon no longer be needed)
  5. Location of filter html

Display the field

  • Enter a column number in the display order column for the “First Role”
  • Click update field settings
  • Click Rebuild cache to be sure field shows

This tells the plugin you want to use that field in that list and where to display it.

Adding field to list for filtering

Specify that field should be displayed for now

Check that field works, some values exist:

Define Filtering

  • Click “Filtering”,
  • Select an html input type from the dropdown.  Note some options may require special add-ons.
  • Click Update
  • Click Rebuild cache now (for now, coming version will remove this)

In current version of plugin the list will show with filter but the values will not be there – plugin hasn’t had a chance to  ‘save’ them for filtering yet.


Cache versions of plugin  will use this rebuild to save the possible values of role in your db, including any custom roles, but excluding any for which there are NO  users.

If  values (eg roles) and users with those values (roles) are added over time – a rebuild cache will find and add them.  The filter should now be visible with values for existing users.

Rebuild the cache (Realtime Query version coming)

  • just making sure….. if you do not see the values, then rebuild the cache!
  • still don’t see all values you expect to see ? Is there a user with that value ? No ? Create/update and rebuild the cache.

Filtering Html Location


Setting the location of the filters

In the configure screen in the overview section, under f’iltering’.
  • Select
    • in table or
    • above or
    • none (to switch off while saving settings)
  • Click Update.

Field types and formats

A range of formats are available for each type of field.  The plugin will try work out what type each field is.  If it doesn’t, you can set the type of field (integer, text, post_id etc) yourself in the ‘Fields & Nice Names settings.

As well as the formats, it is also possible to specify a type of link for each field.  There are some predefined link types.   For urls added by third party plugins an addon may be needed.  You can also define your own rule for a link type via filter or pluggable function. See example site specific plugin.


For example:  Date Time fields and Unix time-stamp fields (and even an ‘ambiguous date in case you have inconsistent data) can be formatted as:

  • Date and time
  • Time
  • Date
  • Ago (human time difference)
  • Age
  • Birth month

The actual format of the date, time and datetime options can also be customised.  The options are the usual wordpress options AND the custom options from your general settings screen.

Email example:

user_email field will be formatted with the ‘mailto’ linktype and then each site can tailor this with their own css.  Perhaps use wordpress dashicons to show a email icon? 

You should ensure that your data adheres to the field type specified.  Any invalid data will generally be shown unformatted / raw.

See the screenshots below and the demo sites for more possibilities.

Some Field Types
More Field Types
More Field Types
Image Field Formats
Image Field Formats
Post Id Formats
Post Id Formats
Boolean Formats
Boolean Formats
Date Formats
Date Formats
Url Formats
Url Formats
Email Formats
Email Formats
Phone Formats
Phone Formats
Formatting Post ids – they might be images & they might not!

Roles, First Role, bbpress forum roles, s2member levels…

[2019 Note: Please watch out for major update.  First_role will be replaced by Capabilities/Roles.  There will no longer be a separate first_role field ]

Do users on your websites have more than one wordpress role ?

users with multiple roles

users with multiple roles – requires the amr-users-plus addon

On a basic wordpress install, a user usually has only one role.  At the simplest, many sites only deal with administrators and subscribers.

The free amr users user listing plugin will extract the first role found in the wordpress usermeta capabilities value and present that as the ‘first role’.  This is great for most installs, some may need more reporting possibilities.

WordPress does actually allow for users to have multiple roles.  Add in the bbpress plugin and possibly a membership plugin which may create it’s own set of roles in parallel to the wordpress ones (ie not instead of), then you may find a single user may have many roles even if you actually need them to only have one.

single role fields

single role fields

Depending how/when a user was created in the system, (converted? created before or after the forum etc)  they may/may not have a wordpress default role, they may just have a bpress role for example.     Even more confusingly the ‘first role’ may no longer be useful.  For example, someone may have been created as a forum participant with  while someone else may be wordpress ‘editor’ and then a forum participant.  The ‘first roles’ may then differ, when one might think that they should both have participant.

In such a case, other role fields may be  useful too.    The free amr users plugin will automatically extract all the roles it finds and present each as a field where the user either has a that value (1 or true) or does not.    One can use these to exclude or include users from the user lists, or to interrogate the db looking for users with multiple roles etc.

If you need more than that, then you need the amr-users-plus plugin.  It adds

  • a ‘roles’ field which will list in the one field all the roles a user has.   It also adds filtering functionality where one can do realtime selection.  This will work for any roles stored in the usermeta capabilities record.
  • a first bbpress forum role, in case you just interested in forum access only

Format a field as a link

The configure settings allow one to specify a type of link for each field.  There are

  • predefined link types
  • link types for urls added by third party plugins. an addon is needed for those.
  • You can also define your own rule for a link type via filter or pluggable function. See example site specific plugin.

Predefined link types

link types close up

link types

Hardcoded links

This is an old example of a site specific add-on created specifically for a certain website.

Teachers Website is now a clickable link

Teachers Website is now a clickable link

This site specific plugin adds a formatting function for a custom field created by a third party plugin.  In this case the field is called ‘teachers-website’.  

The formatting function therefore must be called:

ausers_format_teachers_website($v, $u)

This example includes target=”_blank” as that was requested.  However please read what various institutions advise about opening new windows on links: http://webdesign.anmari.com/2820/dont-force-open-new-windows/

Instructions on how to create your own formatting function are here: https://wpusersplugin.com/2645/format-any-field-any-way-you-wish/

amr_format_extra_fields (zip file)

How to find fields produced by other plugins

This is a frequent question as more people seem to turn to my plugins to solve their need to report data created by other plugins.  A list of some of these plugins with comments on how they store the data is here: https://wpusersplugin.com/3195/possible-user-extra-field-or-user-meta-plugins/

Create sample data

In all cases first create some sample data in your test site.  The free amr-users plugin will do it’s best to extract the fields but it needs the sample data – it is not psychic.

How were these custom fields created and stored?

Ideally your custom user fields have been stored in the wordpress user tables in a simple form.  Even if it is not stored ‘simply’, the plugin may still be able to work through an array or object and extract the individual fields.

Run ‘Find Fields’

Go to the settings and run ‘find fields’ (See https://wpusersplugin.com/3221/getting-started-with-amr-users/#find) – data in the wordpress user tables will be found.

If your fields show up – YAY! you are well on your way… see https://wpusersplugin.com/3221/getting-started-with-amr-users/ for the rest.

Fields not found?

If not… – There are some very popular plugins that do NOT store their user data in wordpress tables.  Over time, people have requested that the users plugin read these tables too.  Thus a number of add-ons have been developed to work with the main plugin and extract this data.  See the add-on menu dropdown on this site – it should have all the latest and see https://wpusersplugin.com/related-plugins/amr-user-plugin-add-ons/ (may not list all)

If you suspect your site is NOT using the wordpress user and user meta tables (EG: sample data does not show up when running ‘find fields’), you could use your phpmyadmin tool to look at your database and see what extra tables have been created.

Or if you know which plugin is creating the data, check the add-on list (see the menus) – an add-on may exist to solve your problems.

If an add-on does not exist, one could be written by you perhaps? or by me (charges apply).  Some details here: https://wpusersplugin.com/3596/pull-user-data-from-custom-table-into-list/.


If you’d like assistance with extracting data from custom tables, the more detail you provide up front, the quicker and cheaper a resolution.

  • What plugin creates the fields?
  • Where are the field values stored ? (screen or sql dumps of the tables would help)
  • What kinds of fields ?  – what are the stored values ? what are the displayed values required ?  (yes these are sometimes different – additional lookups may be required )
  • Any translation ability for field values or lables required ? eg: for multi language sites.
  • Any special formatting ? eg: links etc

Note: Fees: http://webdesign.anmari.com/about/fees/


Getting started with amr users plus

How to use:

  • amr users plugin from wordpress must be activated
  • activate “amr users plus”  – the ‘edit filtering’ link becomes functional.
  • From within the admin ‘view list’, logged in as administrator, click ‘edit filtering’

Enter filter settings screen

Define which columns may have which type of filtering

Some columns may not be filterable (eg: id)

Apply filtering

  • Update the filtering settings, Exit Filtering
  • Most Important: rebuild the cache !
    • this is necessary for the plugin to pickup the filter values for display

Public Report ? Check the front end

  • filtering input fields may make table columns wider
  • exact effect depends on your theme and the width of your filter values
  • adjust your css if required

User lists and filtering with s2Member fields

This is not a suggestion to use S2member – there are other ways to add custom fields.   I am NOT an expert on S2member.   This is purely my observations to assist people using S2member and who want to use amr-users to report on the data.

Warning for S2member Custom fields:  These are stored in the db in one usermeta record.  This means that it is not possible to do a SQL query with a “WHERE s2member_customfield=’xxx'”  or to “ORDER BY s2member_customfield”.   Future non-cache versions of amr-users will still be able to extract the data but will not filter, include or exclude or sort by s2member custom fields.

Play around with the S2member field creation options and their interaction with amr-users.  See what works for you.  Choose your values and lables carefully.  You may  find this addon helpful: https://wpusersplugin.com/downloads/amr-users-plus-s2-member/

For S2Member support, please contact S2Member.


  • S2member allows one to create additional user fields for profile or registration
  • S2member stores MANY  of it’s custom fields in one user meta record.  This makes it difficult to query or filter based on the values.
  • amr-users will list the values that S2 members stores for a field, not the labels, however one can also get the lables by using the S2 member addon.
  • think carefully about your choice of field ‘codes’ as these are what appear in the csv extract.

Choosing field types and values

  • S2member multi option boolean (on/off) fields are stored as “on” by their existence (not with a true/false as per other radio button fields), so users who have not yet updated that field are indistinguishable from users who have said ‘no’
  • amr-users can access S2members ‘plain’ fields fairly easily and can list multi option fields – that may be all  you need.
  • Filtering single option in own columns or shared column works √
  • If you don’t want boolean values to show in amr-users, either use
    • the amr users S2 member addon
    • radio buttons – one field for each value you want to display

The following example applies if you are not using the amr users plus S2 members addon.

S2member example configuration

  • sample data :
    • Service types to be recorded. User can have one, many or none of the values:
      • lift passes,
      • rentals,
      • activities
  • 3 representations explored (chosen for the resulting data representation)
    • a multi option (select or checkbox similar)
    • single checkboxes in a section
    • radio buttons in a section

S2 member example configuration

Option values

Note that the option values are entered and what will be listed

s2member detail with section – note option values

In the User Profile (note 3 different options displayed for same data):

All 3 optons in the user profile

In a simple amr users list

Option 1 the multi dropdown

Using Single Checkboxes (in separate columns, see other option below)

Radio button values

Or combine fields into one column!

Combine the 3 values into one column, to achieve similar look as the dropdown multi option.   (Not good for filtering)

3 S2m fields combined into one column

amr-users configuration for shared column:

  • Give them all decimal “x.y” display orders where they all have the same x values
  • Edit the headings to  make it look nicer

Putting separate fields into 1 column

Filtering Options

  • filtering requires the amr-users-plus plugin (v 2.0 about to go up)
  • filter in separate columns (“column values” or “column empty or not”)
  • filter in shared columns (“field values”)

What do we want

Filtering in the reporting view (and/or on the front end):

Filtering checkbox in single column

Filtering with blanks/no blanks only.   This only shows if you have ‘blanks’ in your data.  If there are no blank values in your data, then neither ‘blanks’ or ‘non-blanks’ will show.

Filtering with “column empty or not”

Combining fields into columns does NOT work so well if you also want to filter. (one can only filter on combinations).  Rather keep the fields in separate columns.

Without further coding, filters or pluggables, the values are combined. Due to way S2 stores the detail, it is hard to deliver a generic function – a dedicated S2member answer would be required

Filter configuration for fields in separate columns

Configuration of filter with column values in separate columns

Filter configuration for shared columns (multiple fields in one column)

Filtering with field values in a shared column

More examples:

Collect and show country of residence, using a controlled list of countries

  • each user has one country code
  • consider using a radio button, listing all the possible countries.  then you can control the value stored and displayed.

Collect and show possible multiple countries in which user operates, using country codes, not boolean values

  • each user can have multiple country codes
  • either use multiple separate radio button fields
    • operates in canada/n,  operates in US/n  etc where the positive values are Canada, US etc
    • OR a single checkbox and reformat the displayed boolean to show country code based on field name (complex)

For the more technical:

Filters and pluggable functions exist for further customising. EG:

  • want the boolean ‘1’s to show as a translateable ‘Yes’ , or as the label value ?
  • want to dig deeper into the S2 multi options yourself and do your own processing ? See how the other add-ons work

How S2 stores their data for examples above

Multi Options:

  • “service_type”
    • “Life passes”
    • “Ski rental”
    • “Activities”

Single Checkboxes

  • “rental2”  => “1”
  • “activities2″ =>”1”
  • “liftpass2″=>”1”

Multiple Radio Buttons

  • “Lift passes” =>”Lift passes”;
  • “No lift passes”  => ””;
  • “Activities” =>”Activities”;
  • “No Activities” =>””;
  • “Rental”=> “Rental”
  • “No rental”=> “”

Filters and actions (for developers)

amr-users version 3.2 upwards has wordpress style filters to allow adding in data from other sources.  I use  these myself for the add-on plugins

amr_get_fields  – ($keys)

  • is passed a set of keys or fields that the plugin already knows about from wordpress user or usermet tables or other add-ons
  • your filtering function must return add to t he array of fields to be used when configuring reports and return the augmented array.
  • additional keys or fields will be visible in the nice names list when ‘find fields’ is run

amr_get_users  – ($users)

  • passes the filtering function an array of users with basic user data
  • your filtering function must  return an array of users
  • this is useful if you need to add users that are NOT in wordpress user table. EG: subscribe2 newsletter subscribers.

amr_get_users_with_meta – ($users)

  • passes the filtering function an array of users with basic user data,plus meta data. as required for that report
  • your filtering function must  return an array of users with all the necessary data
  • this is useful for adding in data for users  that is not stored in the wordpress user tables.  Example: cimy plugin data
  • also could be used in the data is stored weirdly.  It gives an opportunity to look at the meta data and work with it (result will be in csv output).  Please also consider using a formatting function as an alternative (result will not be in csv output, but may be more efficient as will only execute for displayed users.)

amr_users_format_value – ( $text, $fieldname, $originalvalue, $user)

  • passes the filtering function :
    • formatted text
    • internal fieldname (see nice names settings page)
    • original value unformatted as found in the database
    • the current user array
  • must return either the origonal text or your special formatting (do  not echo it)
  • working example is amr users plus 2member
  • NB: there is also the option for a special formatting function for your fields.

 amr-users-linktypes – ($linktypes array)

  • passes array of linktypes – name and description for dropdown selection function.. $linktypes[‘name’] = __(‘description’);
  • filtering function must  return an array of  linktypes
  • is passed
    • the chosen linktype when formatting a field (the linktype may be the one you setup above)
    • the user array in case your url is user dependent
    • the field on which the link is to be displayed, in case your url is field dependent
  • must return a url

amr_users_headings – ($cols,$icols,$ulist)

  • passes the filtering function
    • array of current headings
    • array of ‘technical’ column names
    • the list number
  • filtering function must  return an array of  headings

amr-users-export-csv -( ‘list_users’, $ulist)

  • change the capability required to export to csv

amr_users_csv_line – ( $line[‘csvcontent’])

  • modify the csv line before export

amr_users_apply_filter_html ($apply_filter_html)

  • change the ‘apply filter’ html


  •     $lables = apply_filters (‘amr_filter_lables’, $lables, $col, $selected, $type);


  •     $values = apply_filters (‘amr_filter_values’, $values, $col, $selected, $type);



  • runs before the list is executed or cache fetched
  • for example: allows one to force criteria into the request field  (eg: show only logged in user)
  • receives the list number

Example Applications


This add on adds users from an external table:

  • ‘amr_get_fields’ to add the Subscribe2 subscriber table ip address field
  • ‘amr_get_users_with_meta’ to add the Subscribe2 subscribers to the user list.  It maps the subscribe2 data where possible to existing fields:
    • email => user_email
    • user_registered => date
    • user_status => ‘confirmed’ or ‘unconfirmed’
  • and adds the ip address field in for those subscribers


This add on adds additional data from an external table for existing users. i IE: makes the external data look like user meta data.

  • ‘amr_get_fields’ to add whatever fields have been defined in the cimy fields table
  • ‘amr_get_users_with_meta’ to add the cimy data to the existing users, linking the users by the user id