Category Archives: amr users plus documentation

Excel user list export

Updated on by
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)

Demo

excel wordpress user export demo.

Instructions:

  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

Updated on by

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.

Rebuild!

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.
FilteringSetup
FilteringSetup

Getting started with amr users plus

Updated on by

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

Updated on by

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.

Summary

  • 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)

Updated on by

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

amr_filter_lables

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

amr_filter_values

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

Actions

amr-add-criteria-to-list

  • 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

amr-users-plus-s2

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

amr-users-plus-cimy

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