Category Archives: amr users documentation

Notes on how to use the amr users plugin

Multi Lingual User Lists

Updated on by

How to setup a multi language userlist with wpml.

  1. Finalise your fields ‘nice names’, your user lists and their headings.
  2. Make sure you have any available wp and plugin translations loaded, or create your own string translations for public facing strings.   The strings within the formatting of the lists can be translated & localised. see demo.
  3. If you have headings on the userlist or directory, either:
    1. create translations for the headings using wpml’s admin text translation feature.  Choose the option ‘amr-users-custom-headings’ – it will have all the headings for all the lists.  See screenshot below.
    2. OR, copy the list and make a version with translated headings.
  4. Last step – do one of the following:
    1. One userlist page for all languages.  All strings get translated in realtime. If you have no additional text on the page that requires translation, this may suit. This is shown here: https://lang.wpusersplugin.com/
    2. One userlist page for each language re-using the same userlist on each of the language pages. Good with translated custom headings as per above or if the userlist is not using headings.
    3. A page for each language with a separate user list for each language page. Copy the list you created for each language and change the headings to suit the language.

Where to get translations:

  • A language pack may be available from wordpress. For status of available language files, please see https://translate.wordpress.org/projects/wp-plugins/amr-users/ and consider contributing translations for the languages you are skilled in. If a language for a plugin has reached 90% complete, a language pack for it will be automatically generated and made available. These are stored in …wp-content/language/plugins.
  • A plugin may provide some translations and load from ‘plugin_rel_path’. Eg: …wp-content/plugins/amr-users/languages.  For amr-users these have been provided by volunteers.  I have no way to judge their completeness or quality. Note: If a rel_path is not provided, wordpress will load translations from the plugins top folder wp-content/plugins/the-plugin
  • a translation editor may offer another way to translate strings and will probably add a filter to ensure that these are uploaded.  WPML stores these by default in …wp-content/languages/wpml
  • Own translations can also be loaded whereever you like and not have them overwritten by a language pack. Use a

Note:

amr-users-plus reuses some of the amr-users translations and the wp translations, so a scan of it’s files will show these domains too.

More info:

Screenshots:

MultiLingual User List Test Demo (apologies for the google translations!)

Custom Heading Translations added with wpml

Before and After text for fields

Updated on by

It is possible to add text to the field value before or after the field value. There are not many good reasons to do this:

  • Repeated static text just clogs up the screen, headings are better.
  • Adding html for styling reasons is not suggested.
  • Better to style with css.

However let us assume for example that you wish to add the text ‘Born: ‘ to every Birthdate field with content. You can add it to the ‘before’ text of the Configure list> Before & After tab. See screen shots below.

Note that:

  • This ‘before’ text is not shown if the field is empty.
  • Note that the text becomes part of the field value.The full text is included in the cache and the csv and excel extracts.
  • It is strongly suggested that you do NOT use this feature for styling. CSS is a better way to style fields. There are a lot of meaningful css selectors offered in the user lists so that one can target almost any field.
  • It is also possible to keep the field values clean for csv and excel and to use css to add the extra text. This can be done using the before and after pseudo elements. These pseudo elements can also be used to hide and replace content as you can see on this user list demo page where the field content can be replaced by text or an image.
Specifying the text to display before a field
The ‘before’ text is displayed when there is a value in the field
In the current ‘cache’ versions the ‘before’ and ‘after’ text is included in the cache and the csv (historical reasons).
An alternative to adding text in the configuration, is to add the extra text via css, so that it does not appear in the csv or excel extracts.

Controlling access to user lists

Updated on by

Define whether lists may be shown in public to non logged in users and whether they may be shown in the admin menu to users who do not have manage users capability.

Summary of access control options:

  • List overview settings:
    • ‘public’ lists (ie lists ticked ‘public’ in the settings) can be viewed by anyone
    • non-public lists can only be viewed by people with ‘list_users’ capability
    • ‘show in menu’ (v 4.48 upwards with matching amr-users-plus) will cause  that list to be shown separately in the admin menu under users for users with ‘manage_options’ and ‘list_users’ capabilities
    • if some lists are not shown in the menu, an ‘all lists’ submenu will show for users who have ‘manage_options’ capability
  • Users with ‘manage_options‘ or ‘manage_user_lists’ can create and edit user lists.

Define public lists for front end

User list overview settings
Who can see list with setting:PublicNot Public
Non logged in User✔❌
Subscriber✔❌
user with ‘list_users’ capability✔✔
user with ‘manage_options’✔✔
User List public setting

Define which lists appear in the admin menu

  • As per the screen shot above, use overview settings available when amr-users-plus is active to remove or select which lists appear in the admin side menu.
  • An all lists menu option is shown to users with ‘manage_options’ or ‘manage_user_lists’ capability.
Organise, sort with drag & drop, rename and renumber list
A menu option will list all lists

Define which roles see which lists in admin menu:

Who can see list in menu with setting:Show in menuDo not show in menu
Non logged in User❌❌
Subscriber❌ ❌
user with ‘list_users’ capability✔✔
user with ‘manage_options’✔✔
User List ‘show in menu’ setting (admin menu) available with amr-users-plus v3.2 upwards. If addon not acrtive, all lists will show in menu by default.

Registered Days Ago and Registration Date

Updated on by

There are two fields that show details of date of registration.  When the plugin started I wanted to see a human based ‘days ago’ view as I found that much more helpful to assess how long a user had been a member.

Thus that is the real wordpress registration date fields default formatting.  If one hovers over the field full details of the actual date will show.

It is also possible for you to write your own formatting function to format the date any way you would like.   For those people who are unable to write their own functions from the example and just want to display the registration date, there is a ‘pseudo’ field created which is called ‘Registration Date’ – it is not a real field though and does not sort well.

 

Days ago for registration date

Days ago for registration date

Registered days ago

  • real registration date field formatted using wordpress’s human time difference date time function
  • has hover text so you can see the actual date
  • will sort by date
  • will display the date in the csv extract

Registration date

  • pseudo field created on the fly in display only
  • doesn’t sort.  Sort by the ‘days ago’ field and then remove the display order to hide the field
  • doesn’t show in csv

Registration and days ago in excel

Registration and days ago in excel

Future

In the future there may be the possibility for one to choose from a range of formats. For  example I can imagine a number of possibilities:

  • a range of date formatting options using php date format options
  • human time diff, days ago
  • birthday (no years)

Adding custom css to a wordpress website for plugin html

Updated on by

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: http://wordpress.org/support/plugin/jetpack
It has a custom css module http://jetpack.me/support/custom-css/   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.

Examples:

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
http://coding.smashingmagazine.com/2007/07/27/css-specificity-things-you-should-know/ .

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 http://browsershots.org/, 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

WordPress themes add unwanted html break tags between links

Updated on by

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

Updated on by

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.

Methods:

  • 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

Steps:

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

Parameters

Updated on by

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

Examples:

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: