Documentation for the Textpattern plugin smd_user_manager by Stef Dawson follows this short message from our sponsor ;-)
If you like my code and find it useful, feel free to show your appreciation with something from my UK Amazon wish list (or US) or donate to the Stef Dawson community coding pot, either via paypal.me/stefdawson or by following the Donate button below to PayPal. Thanks!
smd_user_manager
Complete user / group / privs management. Features:
- Replaces Admin->Users tab
- Add / edit / list users, with content counts alongside each user
- Search, sort, or filter the users (standard Txp pagination result depths apply)
- Quickly find accounts with certain characteristics (e.g. self-registered spam accounts with 0 articles)
- Perform multi-edits: change privilege / reset pass / delete
- All users can edit their own details and change their password
- Create new user groups (a.k.a. roles) if the default six aren’t enough
- Rename existing groups to more suitable names (you cannot delete them)
- Modify Txp’s standard priv areas to alter what each user group can see/do
- Add new priv areas (useful for custom code to save doing it in a plugin)
- A “who’s online” indicator
- Integrates with smd_bio (v0.40+) and smd_prognostics (v0.20+)
Installation / uninstallation
Requires Txp 4.5.0+
Download the plugin from either textpattern.org, or the software page, paste the code into the Txp Admin->Plugins pane, install and enable the plugin. The tables will be installed and populated automatically unless you use the plugin from the cache directory; in either case, visiting the Admin->User manager tab will install and populate them.
To uninstall the plugin, first assign all your users to groups in Txp’s first six, then delete the plugin from the Admin->Plugins page. The tables will be deleted automatically. If you do not reassign users to those default groups, you may have users with ‘dangling’ (i.e. no) privs. The outcome of what happens when such users log in is thus undefined: at the very least you’ll get admin-side errors thrown.
Visit the forum thread for more info or to report on the success or otherwise of the plugin.
Admin side overview
Visit the Admin->User manager tab. The default view (for admins) is a list of users. There are buttons at the top of the screen: Change password, Users, Groups, Privs, and Prefs. Each of those displays an area for the management of that component.
Please note: The plugin tries to remove the Admin->Users menu, but depending on your installed theme this may not be possible. If the menu item remains, it will perform the same function as clicking the User manager tab.
User management (Users button)
View / search the installed user base. Change the number of users you wish to see per page by using the ‘per page’ dropdown below the list. The columns on display are:
- Login — user name
- Real Name — full name
- E-mail — e-mail address
- Privileges — user group
- Last Login — month & year of last access to the Textpattern admin side
- Articles — number of articles authored by this user
- Images — number of images uploaded by this user
- Files — number of files uploaded by this user
- Links — number of links created by this user
Click New user (admins only) to create a new user account and automatically send a randomly-generated password to the nominated e-mail address.
Click a login name (privileges required) to edit the details about that user. If you have any smd_bio fields set up, they can also be edited (and hovering over the login name will retrieve some extended biographical info).
Click an e-mail address to launch your e-mail software to send a message to the user.
Click an article / image / file / link value to see the content owned by that user.
You may sort the columns by clicking the headings. Click once to sort in ascending order, click again to sort in descending order. An arrow shows the sort direction. Your sort column and direction are remembered next time you visit the panel.
You may also search users by login name, real name, e-mail address, privilege level (number or name), or content count. A few notes about searching:
- When searching privileges by name, only the first matching group will be returned — the privs are searched in order of their ID.
- You may search privileges and content counts by specifying an exact value, for example Article count: 0 shows all accounts with no articles (perhaps a self-registered spammer or malicious user?)
- You may also search these fields using greater-than or less-than symbols to find users with the matching number of assets. For example, Image count:
>=50
shows all users with 50 images or more.
You can also perform multi-edits by selecting the rows to alter via the checkboxes and using the dropdown immediately below the list to make mass changes. The options are:
- Change privileges: set all selected users to the given privilege level. When you choose this option, a further dropdown appears to allow you to choose which level to apply.
- Reset password: send a new password to all selected users.
- Delete: remove all selected user accounts. A further dropdown appears with a list of user accounts in it: choose one to transfer over any content that belonged to the deleted user(s).
A common use is to find any users with 0 articles, and then use the multi-edit tool to delete them all.
Group management (Groups button)
This panel allows you to alter the names of Txp’s built-in 6 groups to suit your application. It changes the Titles in the currently installed language only.
You may also add a new group using the input controls and accompanying Create button at the top of the panel. If you choose to only enter a Title, a name will be automatically generated (lower case, with most non-ASCII characters replaced by safe characters). Alternatively, you can type your own name, though please stick to ‘simple’ letters and numbers to make things easy on yourself later. If you choose an existing group from the based on dropdown, the privs for that group will be copied across to your new group.
Custom groups can be deleted using the ‘x’ button alongside each. Any users that were assigned to that group will have their privileges reduced to ‘None’. Either visit the Users panel and alter their priv level to something suitable, or set their level to something else prior to deleting the group.
If any group contains at least one user, the group ID values are hyperlinked back to the Users panel to show only those users in that group. This is handy for reassigning priv levels before deleting a group. If you hover over the priv ID, a tooltip will display the number of users assigned to that privilege group.
Priv management (Privs button)
From this panel you may alter which user groups can access which parts of the admin side interface or perform certain types of action. You will see a list of ‘area’ headings. Click one to expand it and see the privileges it contains; click it again to collapse it. The open/closed state of the areas is remembered next time you visit the panel.
Each area has a row of checkboxes alongside it. If a checkbox is ticked in a column corresponding to a privilege group, that group has access to that feature of the interface. You may alter who sees what by changing the tick boxes and hitting one of the Save buttons that appear to the left of each area heading; all the buttons do the same thing: they save the entire list of privileges. You must confirm the action, because the change is immediate.
You may change checkboxes in batches by selecting rows/columns and then using a keyboard shortcut to make changes to all highlighted checkboxes. Firstly, choose which checkboxes to apply your changes:
- click a column heading to highlight that entire Group
- click a row heading to highlight that entire Priv set
- click the top left-hand corner of the collapsible table to select all checkboxes
You can select multiple columns/rows from multiple areas if you wish. Clicking a row/column/corner heading again will toggle its status.
When you are ready to make changes to the selected checkboxes, you can use the following keys:
c
to check all selected boxesu
to uncheck all selected boxest
to toggle the status of all selected boxes (checked become unchecked, and vice versa)d
deselects all rows / columns you have highlighted
The area headings merely group the areas for convenience and make the page look less scary! Any plugins you have installed will be shown under an area heading of the author’s three-letter prefix. Note that altering privs here overrides the privs as set by the plugin so you can customise who sees what, as long as the plugin in question is loaded before smd_user_manager. Check the plugin load order values if things aren’t working as you expect.
The ‘tab’ area heading governs which user groups have access to the primary navigation areas (content, presentation, admin, extensions and any custom tabs such as those created by smd_tabber). Note that giving access to these tabs does not automatically give access to the secondary navigation elements; you must turn those on independently. By contrast, giving a user group access to a secondary navigation item does allow them to use that feature but they won’t be able to navigate to it using the primary navigation button unless they have also been given access to that tab.
For example, if you grant the ‘page’ privilege to Freelancers but don’t give them access to the Presentation tab, they could type ?event=page
in the URL to get to the Pages panel but they would have no means of navigating there by clicking the mouse. Since the primary ‘Presentation’ tab is missing, the secondary tabs are all missing too, even though some of them may be permitted for that group of users.
If you wish to add your own priv area, type a new one in the box at the top of the panel and hit Create. Your area will be created under the appropriate heading, e.g. if you specified smd_test
it would appear under the smd
heading, or if you created a file.trusted
privilege area, it would appear under the file
heading. Core areas are normally specified by a dotted notation but you are free to choose any notation that makes sense to your application.
Note that:
- some plugins may not show up in the list due to factors such as plugin load order or the mechanism by which the plugin is written.
- the
[R]
column is a special Reset indicator. Checking any row in this column will ignore any privilege checkboxes you may have set or altered and will reset the corresponding privs to their defaults after you click Save. - by default you may not add
smd_um
privs to override the functionality if this plugin, although you can adjust who can edit what so be careful not to open the permissions too widely. A preference setting governs whether smd_um can have its own privs altered. - you can create priv areas that may be tested from the public side using the smd_um_has_privs tag.
Preference management (Prefs button)
Administrators can set global preferences that govern the behaviour of the plugin:
- Assume hierarchical groups
- Textpattern does not normally have the notion of escalating privilege levels. A Copy Editor is not greater than a Staff Writer, for example, they just have different permissions to fulfil the relevant role.
- You may set this preference to yes to force Textpattern to treat your levels as a hierarchy, i.e. lower numbers are “more powerful” than higher numbers (with the exception of 0: None which is always ‘no privs’).
- Once set, logged-in users may not create or edit any other users that are ‘above’ their assigned privs, e.g. Copy Editors cannot modify Publisher or Managing Editor accounts. Further, it is not possible to alter your own privileges, nor can you create a user with a greater priv level than you possess.
- Default: no
- Protected administrator group
- Nominate a group that you wish only administrators to be able to alter/create.
- Once set, the nominated group is off-limits to all users apart from those already in the selected group. In other words, non-admin users cannot create, modify, alter (or mass-alter) any privilege setting using this group.
- Can be used in tandem with or independently of the Assume hierarchical groups setting.
- Default: 1 (a.k.a. Publishers)
- Maximum user search result limit
- Maximum number of search results to return when filtering the User list.
- Default: 500
- Password length (characters)
- The number of characters in newly-generated passwords. The higher the better (up to a point).
- Default: 12
- Activity timeout (seconds)
- Number of seconds within which someone has to perform an admin-side action to remain visible on the Active Users list. For high activity sites, you can lower this value and receive a more responsive (accurate) list, at the possible expense of more perceived fluctuations in user activity when the timeout is exceeded. Lengthening the value will keep online users in the list longer, even though they may not actually still be active.
- Default: 60
- Allow smd_um privs to be altered
- Set this to yes to allow smd_um privs to be changed from the Privs panel.
- Default: no
Non-admin users
User accounts without privileges to list users will automatically be shown the Edit screen for their own user account. This is the only account that can be edited. If smd_bio is installed, additional biographical information may also be edited.
Users may also change their password using the button at the top of the screen.
Active users
At the bottom of each smd_user_manager panel is a list of currently active (“online”) users. Each user is hyperlinked to the Users panel to show you the info about just that person, which is a convenient shortcut to find out about a logged-in author.
An active user is one who has performed some admin-side action in the past N seconds, where N is defined in the Activity Timeout plugin preference.
Developer callbacks
The plugin honours as many existing Textpattern callbacks found on the Admin->Users panel as it can. In addition, the following callbacks are defined:
Event | Step | Pre | Payload | Comments |
---|---|---|---|---|
smd_user_manager | password.reset | 0 | array comprising user name, password and email address | Return some string from your callback function to bypass the internal send_new_password() call. The returned string will be announced in the UI. Returning an empty string (or null) will still trigger the default password reset behaviour |
Public side tags
Tag: <txp:smd_um_has_privs>
Use this conditional tag to check if the currently logged-in user has permissions to perform some action. If they have, the contained content is executed. Supports <txp:else />
.
Note that the plugin does not have a public-side logging in/out facility, it merely allows you to test whether someone who has logged in via the admin side (or via a third party login plugin) has necessary privileges.
Attributes:
- name
- Check the current logged-in user’s name against this list of names.
- IMPORTANT: Case sensitive.
- group
- Check the current logged-in user’s group (privilege) level is in this list of numbers.
- You can specify
>
and<
symbols before any value to indicate you wish to check if the user has privileges higher or lower than a given number, respectively. - If checking priv values less than a number, 0 (a.k.a None) is never included: you must add it to the list explicitly if you wish to test for it.
- Example:
group="11, <4"
means “does the user have privs of 11, 1, 2, or 3?” - area
- Check the current logged-in user has the ability to access one of the given areas in this list.
- Example:
area="sports_hall, chemistry_lab"
would only perform the contained content if the logged-in user’s priv level was present in either the sports_hall or chemistry_lab priv areas.
Notes:
- You can combine the attributes in any way: the contained content will only be executed if the logged-in user matches all the criteria.
- Without any attributes, the contained content will be executed if anybody is logged in, regardless of their name, privs or assigned areas.
- Again: login
name
s are case sensitive
Author / credits
Written by Stef Dawson. Thanks to the beta test team jakob, mrdale, alanfluff, maverick, Destry, redbot, and rsilletti for their willingness to let my code loose on their servers.
Changelog
- 10 Nov 2013 | v0.21 | Only save privs if they differ
- 16 May 2013 | v0.20 | Updated for Txp 4.5.0+; added callback smd_user_manager > password.reset to allow interception of reset messages (thanks MattE)
- 25 Jan 2012 | v0.12 | Fixed smd_um_has_privs multiple area check ; fixed prefs options from Plugins pane
- 03 Nov 2011 | v0.11 | Added smd_um_has_privs tag to check privs/areas ; added preference to allow editing of smd_um privs; fixed handling of users with privs=None
- 27 Jul 2011 | v0.10 | Initial public release
Source code
If you’d rather dive in and out of functions, you’ll need to step into the view source page.
Legacy software
If, for some inexplicable reason, you need a legacy version of a plugin, it can probably be found on the plugin archive page.
Experimental software
If you’re feeling brave, or fancy going bareback, you can test out some of my beta code. It can be found on the plugin beta page.