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.

Exclude meta keys, and delete them too

The latest update (3.9) adds a admin screen that allows you to

  • see and change which meta keys are excluded by default from the plugin and
  • exclude more meta keys
  • delete user meta records for selected metakeys (cleanup)
  • see totals of meta records for meta keys

This became essential for anyone using S2member, and handy for anyone using Advanced custom fields which seems to create additional hidden metakeys for every custom field.  Thisplugin will attempt to help you out by default excluding as many unnecessary fields as possible.  You can then update.

The S2member access cap times field is keyed by time, which means that as time goes by there will be more and more sub fields detected by amr-users and the fields and nicenames page will become impossible.

s2member access cap times

s2member access cap times field

This is clearly unworkable.  So a admin page to exclude meta keys was added. This page will also allow you to delete meta records. Be Careful!  This is a confirmation step, but no undo.

excluded meta keys

excluded meta keys

The “find fields and nice names” page has been updated to help highlight what’s going on.

new nice names

updated nice \names

Creating and querying complex meta data in wordpress

The amr-users suite of plugin have had numerous challenges reporting on data created by third party plugins.  The most problems are experienced where a user may have multiple values for a field.  Plugins handle this in a variety of ways.  Discussion below:

Note: As of version 3.7 the plugin treats non-associative arrays (ie arrays with numeric indices) as though they should have been multi meta records with the same key.   This was carefully thought true and if you are up for some technical examples, the thinking is presented below.   Briefly if the plugin does NOT do this, then certain meta data created by some plugins cannot be meaningfully used in a list.

WordPress Meta (user meta post meta, any kind of wordpress meta data)

The key to a well performing system is end to end planning from data entry to reporting and often in the reverse direction makes more sense.  IE work out what you need to report on or do and then gather the data in a way that supports that need.

Many third party plugins create user meta data in a variety of ways without seeming to think about how one might want to query the data.  This causes problems when one tries to list the data.    Which is why the amr-users plugin came about.

How does wordpress support user meta data?

WordPress provides meta tables (in our case say a user meta table) with an index on the meta key. It also offers query functions that allow one to query and select users by user meta. This is all very well when plugins create simple user meta data. The wheels start coming off though as soon as things get a bit more interesting. A common problem that comes up is a need to query a list of users by one of several possible values for a field. EG: say a user offers more than one ‘speciality’.

How should the plugin store these values?

Note: the wordpress Query functions allow for single / unique values and multiple values

http://codex.wordpress.org/Function_Reference/get_user_meta

http://codex.wordpress.org/Function_Reference/update_user_meta
allows for specification of prev value to isolate the meta value that should be updated.

Queries work better with out arrays in the meta values.
http://codex.wordpress.org/Class_Reference/WP_Meta_Query

So should one always store multiple valus for a key in multiple records? What does wordpress do?

wordpress itself uses arrays for some meta keys like

xx_capabilities
a:1:{s:11:”contributor”;b:1;}

manageedit-postcolumnshidden
a:6:{i:0;s:6:”author”;i:1;s:4:”tags”;i:2;s:8:”comments”;i:3;s:0:””;i:4;s:0:””;i:5;s:0:””;}
(represents a unlimited array of post columns that are hidden.)

It is unlikely that one would want to select users by which post boxes they had hidden or which pointers thay have dismissed. So arguably that makes sense to store those in one record.
However the bulk of wordpress meta data is stored simply as single values for a meta key.

 What do plugins do when creating meta data?

Some plugins go overboard. For example ym used to store their user data in a single user meta like this:

O:15:”YourMember_User”:30:{s:22:”account_type_join_date”;i:1381123010;s:13:”custom_fields”;s:0:””;s:9:”rss_token”;s:0:””;s:6:”status”;s:6:”Active”;s:8:”trial_on”;b:0;s:10:”trial_cost”;d:0;s:14:”trial_duration”;i:0;s:19:”trial_duration_type”;s:1:”d”;s:11:”trial_taken”;i:0;s:8:”duration”;i:3;s:13:”duration_type”;s:1:”m”;s:6:”amount”;d:5;s:8:”currency”;s:0:””;s:13:”last_pay_date”;i:1381123010;s:11:”expire_date”;i:1389052800;s:12:”account_type”;s:6:”Member”;s:10:”status_str”;s:20:”User Create: Applied”;s:12:”payment_type”;s:0:””;s:7:”pack_id”;s:1:”2″;s:4:”role”;s:10:”subscriber”;s:19:”reminder_email_sent”;b:0;s:12:”gateway_used”;s:9:”ym_create”;s:16:”hide_old_content”;i:0;s:9:”parent_id”;b:0;s:9:”child_ids”;a:0:{}s:22:”child_accounts_allowed”;i:0;s:28:”child_accounts_package_types”;a:0:{}s:23:”child_accounts_packages”;a:0:{}s:14:”hide_admin_bar”;b:0;s:5:”valid”;b:0;}

This made it almost impossible to query and filter easily. Needless to say they later began to ‘convert’ the data into simple user meta.

What to do with an array like this:

speciality a:2:{i:0;s:3:”Two”;i:1;s:5:”Three”;}
ie:
Speciality => array (size=2)
0 => string ‘Two’ (length=3)
1 => string ‘Three’ (length=5)

Another user record might have:
Speciality => array (size=2)
0 => string ‘One’ (length=3)
1 => string ‘Three’ (length=5)

Ideally these could have been stored as multiple meta records ie multiple values for a key.
Speciality => Two
Speciality => Three

This would aid standardised reporting and querying.

If another plugin stores data in a similar way is there another way to interpret the data ?

These representations might work

  • Consulting Speciality => Individual
  • Consulting Speciality => Corporate
  • Legal Services => International
  • Legal Services => Media

OR even

  • Consulting Speciality => array (Individual, Corporate) or array (Individual=>true, Corporate=true)
  • Legal Services => array (International, Media)

Perhaps if the indices are ‘numeric’, one can assume the values are boolean?
ie treat
Consulting Speciality => array (0=> Individual, 1=>Corporate)

as

Consulting Speciality => Individual
Consulting Speciality => Corporate

Querying, Filtering, Reporting

So how does on query, filter and report on data in a generic fashion, when one has not created the data oneself and the data may be stored in unusual ways?

The amr-users plugin attempts to do this, while allowing for add-ons to handle non-wp third party plugins that do non wp things

It digs into the data and attempts to make sense of what it finds in the user meta values. If a value is not simple, it expands it and creates multiple pseudo fields from the one complex meta field value.
The plugin has special handling for first role (capability) and some other ‘useful’ pseudo fields. Note other capabilities are boolean. Special formatting could present these differently.  The plugin also excludes the pointers dismissed and hidden dashboards etc to keep the number of fields down (although might be interesting to query who has tailored their environments etc).

 

Note:

in working through this the following was identified:
The ACF plugin rather unusually stores an extra hidden meta which has it’s internal field code. THis is the same for every user which raises the question – WHY store it in the user meta records – a more appropriate place would be once in the wp options table?
IE it stores for example:
speciality and _speciality.

In the amr-user general settings > fields & nice names, tick the ‘Exclude from reports’ box for the underscore fields, to reduce confusion!