Field types and formats

Many fields will have default formats, but what if you want a different format? Or if the field was added by another plugin?    There are add-ons for some third party plugins which may offer suitable formats.   Alternatively from version 4.0 of amr-users and up, one can control the format via the settings.

Tell the amr-users plugin what sort of data you have in your fields (the fieldtype) and the plugin will offer you some predefined formats for that field.   In some cases the option may be greyed out if the format function is not available in the system.

Some formats are available in the free version and some may require amr-users-plus versions >= 3.0 or may require a custom add-ons.

This is for example very useful if dealing with a third party plugin that stores date and time fields as Unix timestamps.  (Why do they do this?, ok I know why, it’s just that if wordpress doesn’t do it, it’s not necessary for plugins to do it is it?.  It obfuscates the data and makes to hard for you when you look at the raw data.)

Priorities

  1. Custom format specified in settings & custom function for that exists
  2. Else Custom format specified in settings – default pluggable function
  3. Else Linktype with default format
  4. Else Custom pluggable field specific function
  5. Else Default pluggable function if available (no settings, no linktype)

Instructions

In the “Fields and nice names” screen, select the field type for the field that the plugin has found.  For example:

  • user registration date is stored in date time format YYYY-MM-DD hh:mi:ss
  • various S2 member date time fields are stored in Unix timestamp format

In the “configure list” screen for each list,  choose formats that make sense for that field-type.   Each list can have a different format. For example, one list might have a high level date format for the user registration date, and another list might choose to include the date and the time.

Date Time fields and Unix time-stamp fields could currently 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:

Usually the 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?  Two format options have also been provided.  If functions are defined for the format dropdown options, they will become ‘available’.  Eg:

  • function ausers_format_email_mailto($email)  or
  • function ausers_format_email_icon_mailto($email)

If a custom format is specified in the settings, these will generally override any coded custom formatting routine (except for amr-users-plus-s2member version 2.0 and lower) and any default formatting.

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

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

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

This is an 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/.

Assistance

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/

 

On demand filtering on a new field

You want to filter by a field not currently displayed?

(requires amr-users-plus)

  1. Display the field
  2. Define the filtering
  3. Rebuild cache
  4. Location of filter html (optional)

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.

Enter number to define field display and sequence

Edit Filtering

Handles custom roles and users with no roles in the current db (possibly due to shared user tables)

Edit Filtering

  • Click “Edit Filtering”,
  • Choose “column value” option for ‘first role”
  • Click Update Filtering
  • Click Rebuild cache now

List will show with filter but role values will not be there – plugin hasn’t had a chance to  ‘save’ them for filtering yet

Choose filter options for fields you want to filter, leave blank for no filtering

Rebuild cache after updating filtering

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

Filter values should now be visible – the values shown depend on the data in your database.

Rebuild the cache

  • 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

If it’s not inside, it’s on top Asides: (the original ad])(en vir die Afrikaners, hier is ‘n Jan Spies version)

Inside:

Filter options inside table structure

On top (above)

Filtering above the list

Settings

To determine filter html location – see the FAR right of the list configure screen in the overview section.
  • Select
    • in table or
    • above or
    • none (to switch off while saving settings)
  • Click Update Overview Settings

Define the filter html location

 

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.

Play around with the S2member various 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)

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 (free)
  • 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 depenedent
  • 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