Extension:RightFunctions/Doc

RightFunctions is an extension that adds permission-based parser functions. Please note that these extensions may be used to superficially hide information from those with certain rights. Also, all of these functions disable the cache on the page they are used in. For installation instructions, please view the main extension page.

Usage
As of now, RightFunctions defines eight parser functions, ifright, ifallowed, userrights, usergroup, ifpageright, ifpageallowed, ifprotected, and getrestrictions.

Ifright
Tests whether the current user has the given right, then displays the appropriate text. If the right doesn't exist, it simply returns else. If no right is specified, it returns then. This function ignores per-page restrictions on a user's rights, so use if you need that functionality.

Usage:  

Ifallowed
Tests whether the given user has the given right, then displays the appropriate text. If the user viewing this function doesn't have ample permissions to view other users' rights, a warning message will instead be displayed (unless you disable them by setting $wgRightFunctionsDisableWarnings). This function ignores per-page restrictions on a user's rights, so use if you need that functionality.

Usage:  

Userrights
Lists all rights in an unordered list either of the current user or of the given user. In order to get the rights of another user, you must have ample permissions (via $wgRightFunctionsOtherUsers), otherwise, it displays a warning message (provided $wgRightFunctionsDisableWarnings isn't enabled) and gives you your own rights when you try to view it (if a user is defined, if not, it triggers on the current user regardless).

Usage:   (for current user) or    (for other users)

Usergroup
Returns the highest user "group" the user belongs to. The groups are defined in lowest-to-highest ranking in the array $wgRightFunctionsUserGroups. Also, this by default does not restrict you from checking other users, but the functionality can be enabled by setting $wgRightFunctionsRestrictUsergroup to true (the permission is controlled, as always, by $wgRightFunctionsOtherUsers).

Usage:   (for current user) or    (for other users)

Ifpageright
Tests whether the current user has the given right on the given page, then displays the appropriate text. If the right doesn't exist, it simply returns else. If no right is specified, it returns then. This function does not ignore per-page restrictions on a user's rights.

Usage:   for testing other pages or    for testing the current page.

Ifpageallowed
Tests whether the given user has the given right on the given page, then displays the appropriate text (again, testing other users is controlled by $wgRightFunctionsOtherUsers). If no user is specified, it checks the current user. If no page is specified, it checks the current page. If the right doesn't exist, it returns else and if no right is specified, it returns then. This function does not ignore per-page restrictions on a user's rights.

Usage:  </tt> for testing other pages or   </tt> for testing the current page.

Ifprotected
Tests whether the given page is protected, then displays the appropriate text. If no page is given, it tests the current page. It will return then if the page is either fully-protected, semi-protected, protected because it is included in a cascading-protected page, or if it is namespace-protected. At the moment, you may control which are tested.

Usage:  </tt> for testing other pages, or   </tt> for testing the current page.

Getrestrictions
Grabs what right is required to carry out the action on the given page. If no page is given, it checks the current page instead. If no right is given, it checks the 'edit' right.

Usage:  </tt> for testing other pages, or   </tt> for testing the current page.

Variables
These variables control how the various parser functions work. There are currently 5 variables.

$wgRightFunctionsOtherUsers
Default value: true

Controls what right is required to get information about other users on the wiki. A value of true means that only those with the sysop right (default sysops and bureaucrats) can get such info, a value of false means that anyone with the * right (default everyone, including anons) can get such info, and any other value requires them to have that right.

$wgRightFunctionsUserGroups
Default value: array('*', 'user', 'autoconfirmed', 'sysop', 'bureaucrat')

An array of rights to test for in. Please note that these are rights, not actual groups (if you check the code, you'll see the definition of each group as having it's own right). Therefore, if you want to add values to this array, make sure that the appropriate usergroups have that right.

$wgRightFunctionsRestrictUsergroup
Default value: false

If set to true, checking other users via #usergroup also requires you to have permissions with $wgRightFunctionsOtherUsers.

$wgRightFunctionsAllowExpensiveQueries
Default value: false

If set to true, using #ifpageright and #ifpageallowed will check the rights more thoroughly (like through cascading protection), so it will produce more accurate results, but it will me more server-intensive to perform.

$wgRightFunctionsDisableWarnings
Default value: false

If set to true, all warnings are replaced with an empty string.

Rights
RightsFunctions assigns rights of groups to that group for "group" testing in. All users are assigned the '*' right, registered user the 'user' right, sysops the 'sysop' right, bureaucrats the 'bureaucrat' right, and bots the 'bot' right. If you have any custom-created usergroups that you wish to check with the Usergroup function, you will need to add in the following before the require_once calling the extension in your LocalSettings.php:

Changelog

 * version 1.2:added four parser functions ifpageright, ifpageallowed, ifprotected, and getrestrictions. Added in variable for hiding warning messages and a variable for enabling more server-intensive queries for the ifpageright and ifpageallowed functions.
 * version 1.1:added safeguard against those trying to access extension directly, and an additional parser function usergroup.
 * version 1.0:initial release defined three parser functions, ifright, ifallowed, and userrights.

Please note that versions less than 1.2 were not placed on mediawiki.org. If you want the source for a version earlier than 1.2, please leave a message on my talk page.