WP Users Plugin

Advanced Shortcode Parameters

From version 3.4.4, Parameters are available to overide list settings. If you are not a farly expert wordpress user, please use the settings rather to avoid confusing yourself. The parameters are for more expert users or more complex requirements. For example they allow one to reuse a single list on multiple pages but with different sort or filtering criteria.

Example of shortcode with parameters

• show_heading=1 (or 0)
• show_csv=1 (or 0)
• show_refresh=1 (or 0)
• show_search=1 (or 0)
• rows_perpage=n
• sort=columnname, can be used with
  • dir=SORT_ASC (or SORT_DESC)
• filter=show (or hide to hide the filtered column), must be used with
  • columnname=value
• (or ONLY when you have a complex multifield column): fieldnamefilter=columnname, must be used with
  • fieldvaluefilter=value

Examples:

Parameter use opens up some possibilities that have been requested. EG: currently serach only allows one to search the fields that are in the list. One can now add fields to the list, then ‘hide’ that field by adding a filter ‘*’ (display all with values) to it. Then the search will include that field, but not display it. (Personally I do not recommend this as i think it’s confusing.)

 filter=hide columnname=*

Special parameters:

• start_empty=1,
  • should be used with a search or filteroption to start with a blank list. See example blank user list at start
• show_randompage=1,
  • start at a random page (when transient html updates). Eg: (using url parameter to test) http://directories.wpusersplugin.com/simple-user-list/?show_randompage=1
• shuffle=1,
  • shuffle the results on a page. Eg: http://directories.wpusersplugin.com/simple-user-list/?shuffle=1

Christian asked for what he calls a ‘criteria’ number for his member list, and what others may call a scoreboard ranking, top 10 chart listing etc…..

Basically we want to show the row or list number as displayed.  You can use any user or usermeta field generated by another plugin (or further fields if the necessary add-on is available) to determine the ranking (Eg; post counts?  or for gaming sites, perhaps you have some score field? ).  You can list both the score field and the ranking.

Define the sort order in your normal list configuration.   When the report is run, the formatting function will add one as each user is displayed.  Thus the sort order determines the current ‘ranking’.

The ranking will work for more than one page.  It checks which page was requested and how many rows per page are being displayed.  Then starts the ranking count appropriately, and increments from there.

The add-on is a very simple little example plugin.

Instructions

1. It allows a ranking field to be displayed.  Use “find fields” to bring it up after plugin activation.
2. Then configure your list, scroll down till you see the ranking field.  Add a number to the display column to say which column it should display in.
3. Save
4. Rebuild cache.

Download

The downloads will be accessible to logged in users who have access to amr-users-plus.  If you are not already registered, the most cost effective options are the ‘developer’ memberships as they give you access to the most add-ons and plugins.  Alternatively you can purchase short term access.  Note if upgrades are made after access expiry , membership repurchase or upgrade will be required.

If you have a custom table that has user data in it, you can pull it into a list by writing a little site specific plugin and making use of some of the hooks available in the amr-users plugin.

The hooks you’ll need are:

• amr_get_fields
• amr_get_users (to add users to the list of existing  users) or
• amr_get_users_with_meta (to add data to array of existing users)

Read the filter documentation and see the add-on plugins to see how to use these hooks.  Many of the add-ons use them to add data from a variety of different styles of tables.

See http://wpusersplugin.com/2940/filters/#examples

• Why Cache?
• When to cache? (settings)
• How does the auto cache work?
• Cache Storage
• Cache Log
• Cache Status
• On demand refresh (admin or public)
• Transient Html Cacheing

Why cache?

Cacheing is required because:

• we want to display, query, filter and sort the data BUT
• some plugins that create user data do it in ‘funny’ non wp standard ways
  • they stick all their user data in one user-meta record, sometimes as an object, sometimes as an array…. (eg: ym (yourmembers), although they appear to be moving to standard wp), so we cannot simply ‘select where meta = ‘
  • they store their user data in non wp tables, so that data has to be fetched separately.  This also means that the wp user update actions don’t fire.  So any recaching dependent on that may  not happen.

So the plugin grabs, extracts, does some magic and stores the data in a separate generic cache table.  Originally this was aimed primary at csv extraction.

When to cache? (settings)

Cache settings

Ideally the lists should be up to date when you see them. BUT for reasons above this may not always be possible.  So consider the following scenarios:

Internal admin access only?

• Consider switching off ALL auto caching.
• Only rebuild the data when you view the list.

Public lists, high level of user updates?

• Strongly suggest do NOT recache on every user update
• Cache at the greatest possible interval (less demand on sql database) – maybe daily ?
• Manual refresh can be made available via an icon link on user list page – see admin refresh link.

Public lists, very low level user updates?

• you must be sure about what plugins are causing user or user meta updates.  If you have a plugin that is tracking the pages people view, or their logins and storing the data in the user meta… do I need to say more?  Re caching on every user update would place a huge sql demand on your system.
• Consider caching on use update only – no scheduled caching.

How does the auto cache rebuild work?

(version 3.4.9 at time of writing)

The cache can be set to automatically update in the ‘background’.  This is achieved using standard wordpress cron features.  If you are new to cron, then basically all you need to know is that it needs some activity on your website to run.  eg: a page request.  A scheduled job will only run on the first page request after the jobs scheduled time.  If you have a very low traffic site, this could be quite late.

A cache update request is initiated via cron on the following wordpress actions:

•     add_action(‘profile_update’,'amr_user_change’);
•     add_action(‘user_register’,'amr_user_change’);
•     add_action(‘deleted_user’,'amr_user_change’); // also for wpmu
•     add_action(‘added_user_meta’,'amr_user_meta_change’);
•     add_action(‘updated_user_meta’,'amr_user_meta_change’);
•     add_action(‘deleted_user_meta’,'amr_user_meta_change’);
•     add_action(‘make_spam_user’,'amr_user_meta_change’);
•     add_action(‘make_ham_user’,'amr_user_meta_change’);
•     add_action(‘remove_user_from_blog’,'amr_user_change’);
•     add_action(‘add_user_to_blog’,'amr_user_change’);

If your install has a user update that does NOT trigger a wordpress action (eg: another plugin stores user data somewhere else), then the plugin has no way of knowing that a user update has happened.

If the other plugin uses its own update actions, you could add a custom function call on that action similar to the above calls.

Alternatively either a regularly scheduled update or a manual on demand refresh may be adequate.

The cache update request attempts to schedule a master cron job.  Many of these wordpress actions may trigger within milliseconds of each other.   The plugin therefore checks whether a cache update is scheduled within the near future to avoid duplicate work.

Master cache cron job shown in amr cron manager

The master cron cache job then schedules individual jobs for each of the reports.  They are scheduled to run separately, not concurrently.  In your cron manager plugin you should see an entry for each job.

When testing, you should therefore do a page request or two approximately minutes apart for each report that you have designed.  Check the cache log in between.

A cron run for each report

Cache storage

(version 3.4.9 at time of writing)

This may change at a later stage for installs that only  use standard wordpress user meta.  Other installs will need the current setupo to deal with their user data created by other plugins.

Currently a generic cache report table in csv format is created.  This made sense originally, however as the plugin became popular more features were requested.  This approach is not ideal for optimum efficiency (especially large high traffic installs).  If one is only using standard wordpress user and user meta data, then the lists could be more efficient.   To cope with non standard data, the curremt approach will have to continue.

Cache Log

The cache log will list the most recent cache rebuild activities.  If you are concerned or not sure how the cache updates are initiated, please pay close attention to the cache log when testing.  For more details see cacheing-the-cache-log

User Meta Update causes cron cache rebuild

Cache Status

The cache status page lists

• the size (lines) of a list
• when the cached list was last built
• how long it took to build the cache
• the peak php memory requirement while running the cache update
• some info on the list

It also has options to totally clear out the various cache records (in case your install gets in a knot), and force the plugin to start again.

Cache Status

The amr users cache log is a useful tool especially when using background (cron) cacheing.

Cache log example, where user master was updated (not meta). A Cache rebuild had been scheduled, but not yet run.

 The cron log

• shows key actions with latest at the top, so read from the bottom up.
• will show more messages if wp-debug is enabled
• does not keep a lot of history – it cleans up after itself.  It’s a testing tool primarily.
• will indicate runtimes
• will indicate batches of updates of the cache records.
• will list why a cache was initiated
  • master user update
  • user meta update
  • background request,
  • else  manual request

Example Screenshots

User meta update request:

• the green text showing the action that causes a request to rebuild cache
• the bolded text controlling background job that setups the cron jobs for each of the lists
• the italic text showing the completion of the cache rebuilds for each list.

User Meta Update causes cron cache rebuild

Change of settings and background run

• the change of setting is listed and the time that the next cron job will run
• the rebuilds of reports 1 and 2 have been scheduled but not yet run

Background request scheduled, preceded by some manual request, also some debug statements on memory

Cron jobs have been run for reports

An update of the previous image – the jobs have now been run.

Why use the cron log?

One can confuse oneself mightily if

• changing settings,  while background jobs are running, or
• on very large data bases if runs take a while
• if you have user update set, but no updates seem to happen (maybe your user updates are not actually to the wp user meta.)
• …

So take it easy – use the tools available.  A good cron manager plugin may also be helpful. There are many around. I like my cron manager plugin because you can reschedule any cron job, eg make them run immediately.  It’s included in developer memberships.

Why use transients ?

To cache the html:

The cacheing process is sql intensive.  It is the way it is primarily because of the way that various third party plugins create user data.  A later version (maybe version 4.0 upwards) will have improved method for those who have standard wp user meta data – yay!   That’s the data not the html.

Querying the cache may also place a load (depending how weird (non wp) your data is and on your report settings).

WordPress offers transients for short term caching. The amr users plugin uses the transients feature to cache the html for the user lists.  If you have a lot of querying activity where people are just browsing the first page, stored  html may reduce the query load on the database.  The transient default expiry setting is 60 seconds.  Later plugin versions may allow you to set this value.

Stored html not used:

Stored transient html is not used (cannot be used) when filtering or sorting or  perform some action on the stored cache data.

It is also not used (obviously) when the cached has just been rebuilt.

Stored html may be used:

The first view after cacheing may store the html in a transient.  If someone requests that self same page before transient expiry, then the stored html may be used.

Arghh, this makes testing hard – how do I know if a transient is used?

Easy.  If you are a logged in admin user when you view a list it will show a subtle exclamation mark. Hopefully not so subtle that you miss it!

Transient html exclamation mark for admin users

To test this,

• login as admin
• view the list
• now refresh the page
• Voila… now hover over the exclamation mark

Hover text on exclamation mark

Refreshing the html, from the cached data

OMG how hard is testing when you don’t know whether the data is the latest or not ?  Tell me about it ! (no really don’t, I know. I’m pedantic, I like to test and check every step of the way and know exactly what’s going on, so of course there is a way….)

Now click on that exclamation mark – magic happens.  It is actually a  link with a little refresh query parameter added:

…./sample-page/user-list/?refresh=1

If you have debug enabled, you may see a little debug message telling you what’s happening:

Debug message

Don’t panic – the message only shows if you have WP_Debug enabled and are a logged in admin.

Hmm interesting, on demand refresh of the cached data huh?

Allow users to request a rebuild of the amr users plugin data?

On demand refresh setting

Setting the refresh setting for a list will cause a refresh icon to show below the list.

Use this cautiously and only if it is imperative that users be able to request a rebuild of the cache.

Refresh icon shown on public list

Customise the refresh link

In the general settings, you can specify what the refresh link should look like and the hover text.   Plain text or image link – it’s your choice.

refresh text or image setting

Code your own refresh link

It’s just html folks – a glorified hyperlink with a url query parameter  You can also add your own link and insert it into the page content below the shortcode.