Adding custom css to a wordpress website for plugin html

Do you want to add css for html generated by a plugin perhaps?

Got a Custom Theme?

Do you have a custom theme that you are NEVER going to automatically update?

Then edit the themes css, add your custom css to the bottom of the main style.css.  This should be in your themes folder under wp-content.

Got an Updateable Theme ?

Does your theme have upates occasionally ? If you want to be able to auto update your theme, then it is better to add your css separately.

Some plugin have ways to add a custom css file for that plugin and/or to disable any plugin css so that you may reduce the number of stylesheets.  Do NOT edit any plugin css files unless it is a site specific plugin that will not be updated automatically – you will lose your css when the update is applied.

The easiest way to add custom css if you cannot use your themes style.css is probably by using the official wordpress jetpack plugin:
It has a custom css module   There are other plugins that allow you to do this.

How to work out what css selectors to use?

First you need to work out what css selectors have been provided in the html that is generated.  My plugins generally offer many css selectors in the html.  The various ‘inspect element’ tools are invaluable here.


They help highlight what css is being applied to the html and what is being overwritten.   And of course they help you to see easily what css ‘hooks’ there are to add special styling.

Your custom css needs to work with your theme, so you either need to specify the css tightly enough that no theme css will ever override it, or know that you are not going to be changing themes.

To work out what css to add, ideally you should have a reasonable understanding of css.  In particular the concepts of specificity and inheritance .

You could ask for help from css experts.

When asking for help you should

  • provide a link to the problem page of your site or demo site
  • identify the theme you are using perhaps
  • be clear and specific about the effect you are trying to achieve and your level of skill in editing css

Browser consistency

You should also know that browsers vary in their implementation and while your hack that you worked out or have been given might look beautiful on your apple mac running safari, results can vary greatly.

If you have any pride in your work at all, you should test the result using something like, or risk the site looking really stupid.

Identifying CSS selectors example:

In this example from the amr-users plugin, one can see that:

  • there are id’s specific to a user list, thus enabling one to isolate your css to just the list  (div id=userlist1)
  • there is a general userlist class which enables one to style all such userlists with the same css
  • there are classes per field allowing one to style individual fields
Using Inspect Element to inspect the html and css

Using Inspect Element to inspect the html and css

Disappearing images or avatars in tables in chrome?

A ‘funny’ recently presented itself.   In the chrome browser, avatars were not showing up, despite they being there in the html code.

My first thought when I hear of browsers responding differently is to check html validation – browsers often cope with errors but sometimes not.

In this case, it was the css that turned out to be the problem.

An invaluable tool to debug these things is the ‘inspect element’ firebugs or chromes and the ability to deselect or add css to see what is overriding what.  See

Fairly quickly one could see that somehow the inline attributes were being overwritten.

Image attributes overwritten

Image attributes overwritten

Scrolling back up through the css to see what might be overwriting that css, I paused thoughtfully at a image max-width and unticked and  reticked some css.

As soon as I unticked the max-width the images reappeared in chrome.

Undo Max Width

Undo Max Width


A quick web search showed that others had encountered this before and had some suggestions on overcoming this.  It seems Chrome interprets the rule differently from Firefox. It assumes the image can freely be shrunk, and with a long string of text in the cell next door, it squeezes the images.

So some possible solutions appear to be:

  • remove the max-width attempt to be responsive, or
  • set a fixed table width
  • maybe set a fixed column width


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:

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 – data in the wordpress user tables will be found.

If your fields show up – YAY! you are well on your way… see 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 (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:


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:


WordPress themes add unwanted html break tags between links

Experiencing wordpress theme or plugin problems with shortcodes generated html such as:

  • unwanted break <br /> tags,
  • horizontal pagination appears vertically (no, it is not just the css)
  • newlines being turned into breaks,
  • shortcode content being altered ?

Unwanted break tags?

Does your website weirdly add ‘<br />’ html when page or post content is displayed with shortcode content?   Does it disappear when you have standard wordpress theme with no plugins?

unwanted breaks

Unwanted horizontal pagination?

Using amr-users and the pagination is vertical instead of horizontal ?  Yup, you guessed it. This is caused by those break tags being added AFTER the shortcode has run.

Vertical pagination

undesired vertical pagination

horizontal pagination

horizontal pagination

Newlines being turned into breaks?

WordPress function paginate_links

My plugin uses the wordpress function paginate_links with formatting option ‘plain’ . This generates a list of links joined with ‘newlines’ :

$r = join("\n", $page_links);

This works very nicely in default wordpress themes, producing nice paginated user lists with horizontal pagination and nicely structured html.

BUT then…..

If Wpautop function applied to the_content

When your pagination is vertical, or your newlines become breaks, then most likely the theme or another plugin is adding the wordpress wpautop function to the_content filter, possibly with a non default priority .

To avoid wpautop affecting shortcodes,  various people have suggested removing it and then adding it with a later priority to get around other problems… BUT adding it back  can just cause more problems.   To be clear it is possible to add  wpautop with an argument that specifies NOT to change newlines.

Remove wordpress filter with same priority

My plugin tries to avoid this problem for you by executing a

remove_filter ('the_content', 'wpautop');

The remove filter will only work if the filter was added with the default priority and arguments.  It the filter was added with any other priority, the remove will not work.   Filters must be removed with the same priority and arguments that was used to add them.  It simply isn’t possible for my plugin to know what your theme or other plugin is doing.  (eg: WP Unformatted plugin apparently used to apply the filter )

How to fix:

Fix the wpautop call

Get rid of wpautop.   Some folks really don’t like it and arguably your theme should not be applying it the way it does. WordPress default themes don’t cause this problem.

Or change the add filter priority to something less than 11 so it executes BEFORE the shortcode filter .

Css workaround – style the break (‘<br />’)

My plugins default front side css in versions after version 3.6.3 will include this css.  It is not ideal, it would be better if the html code was not changed.  This is to cut down the support effort generated by people who do not realise what is going on. (It’s a tricky one).

If you are not using the front end css, or its not yet available (plugin still at v 3.6.3) then add something like this to your css (in theme or custom css):

.tablenav-pages br { 
/* fix those annoying themes or other plugins that insist on adding wpautop filter to post shortcode content */
    display: none

Exclude or selectively include users without displaying the criteria field

Super easy!  It is explained very briefly in the ‘configure’ section and in the How to exclude users from a list.   This is more detail.

Possible example

  • exclude administrators from lists.


  • we could use the first role OR specific ids depending on need.  Role is safer if one is later adding users we do not want to display.
Configure each individual list, add fields

Configure each individual list, add fields


  • Temporarily choose the criteria field for display by adding a display column to it. In this case the first role.
  • Update the list settings.Role will now be one of the columns displayed AND magically now the other specifications are available in the list configuration.
  • Scroll to the right till you see the “include” and “exclude” fields.
  • Enter your criteria:
    • EG: to display only subscribers (not authors etc), enter ‘subscriber’ in the include column
    • EG: to exclude administrators, enter ‘administrator’ in the exclude column.
    • NB if using multiple values, use commas only to separate DO NOT ADD spaces.  In some cases spaces are valid parts of the field values.
  • Update the list settings, rebuild cache, check it works.
  • NOW … remove the display column number for your criteria field.
  • Update list settings, rebuild cache.

List will now use criteria but not display the fields.


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

Example of shortcode with parameters

  • show_headings=1 (or 0)
  • show_csv=1 (or 0)
  • show_refresh=1 (or 0)
  • show_search=1 (or 0)
  • show_totals=1
  • 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       eg: roles=Subscriber
Parameter to show total records

Parameter to show total records


URL Parameter use opens up some possibilities that have been requested. EG: currently search 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:

Pull user data from custom table into list

Several add-ons have been developed to extract data created by third party plugins and not stored in the wordpress user and user meta tables.

Request an add-on (charges apply) or If you some php skills, use the example plugin to write your own addon.

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 may need are:

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.


More details

See one of the add-on plugins or thee xample site specific plugin.  Do NOT cut and paste the code here. It is meant to inform only and will NOT  work as is.

 add_filter('amr_get_fields', 'amr_add_my_fields', 1);
 add_filter('amr_get_users_with_meta', 'amr_get_my_users_data', 1);
function amr_add_my_fields ($keys) {

// write code here to return the list of additional fields
// you'd like to see in your user lists. 
//IE these are fields in your custom table that are 
//NOT in wordpress user or usermeta table.

// the function will be passed the existing list of fields 
//and should add the additional fields to the array.  eg: 

$keys[] = 'newfield';

return ($keys);

// then return the array $keys



function amr_get_my_users_data ($users) {

// write code here to get the user data from the custom tables. Various approaches are open to you.  Either

  • drive from array of user passed to the function, or
  • from the array of user data from your custom table.. then add to the users array passed extradata = sql query to fetch data from custom table keyed by userid;
for each $extradata {

    $users[$userid]['newfield'] =  $extradata['newfield'];

// then return the array $users
    return ($users);


Alternative (or to format nicely)

The function above has to process ALL the users.  The data will then be available in csv export.  If you only need the data to be displayed, then you could use a formatting function  rather.  The amr-users plugin will look for a custom formatting function for each column to be displayed for each user.
function ausers_format_newfield($value, $user) {

  $customdata_maybearray = code to get data ($user->ID);

  $html = implode (', ',$customdata_maybearray)



Cacheing (amr-users)

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

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

Cacheing – the cache log

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

Cache log example

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.

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.

Cacheing – public on demand refresh

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

On demand refresh setting

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

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 setting

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.