 |
The following applies only to version 2.0 |
Adding the permission
Adding a permission is actually as simple as adding a single line.
This master array in ManagePermissions.php contains the entirety of permissions:
$permissionList = array( 'membergroup' => array( 'view_stats' => array(false, 'general', 'view_basic_info'), 'view_mlist' => array(false, 'general', 'view_basic_info'), 'who_view' => array(false, 'general', 'view_basic_info'), 'search_posts' => array(false, 'general', 'view_basic_info'), 'karma_edit' => array(false, 'general', 'moderate_general'), 'pm_read' => array(false, 'pm', 'use_pm_system'), 'pm_send' => array(false, 'pm', 'use_pm_system'), 'calendar_view' => array(false, 'calendar', 'view_basic_info'), 'calendar_post' => array(false, 'calendar', 'post_calendar'), 'calendar_edit' => array(true, 'calendar', 'post_calendar', 'moderate_general'), 'admin_forum' => array(false, 'maintenance', 'administrate'), 'manage_boards' => array(false, 'maintenance', 'administrate'), 'manage_attachments' => array(false, 'maintenance', 'administrate'), 'manage_smileys' => array(false, 'maintenance', 'administrate'), 'edit_news' => array(false, 'maintenance', 'administrate'), 'access_mod_center' => array(false, 'maintenance', 'moderate_general'), 'moderate_forum' => array(false, 'member_admin', 'moderate_general'), 'manage_membergroups' => array(false, 'member_admin', 'administrate'), 'manage_permissions' => array(false, 'member_admin', 'administrate'), 'manage_bans' => array(false, 'member_admin', 'administrate'), 'send_mail' => array(false, 'member_admin', 'administrate'), 'issue_warning' => array(false, 'member_admin', 'moderate_general'), 'profile_view' => array(true, 'profile', 'view_basic_info', 'view_basic_info'), 'profile_identity' => array(true, 'profile', 'edit_profile', 'moderate_general'), 'profile_extra' => array(true, 'profile', 'edit_profile', 'moderate_general'), 'profile_title' => array(true, 'profile', 'edit_profile', 'moderate_general'), 'profile_remove' => array(true, 'profile', 'delete_account', 'moderate_general'), 'profile_server_avatar' => array(false, 'profile', 'use_avatar'), 'profile_upload_avatar' => array(false, 'profile', 'use_avatar'), 'profile_remote_avatar' => array(false, 'profile', 'use_avatar'), ), 'board' => array( 'moderate_board' => array(false, 'general_board', 'moderate'), 'approve_posts' => array(false, 'general_board', 'moderate'), 'post_new' => array(false, 'topic', 'make_posts'), 'post_unapproved_topics' => array(false, 'topic', 'make_unapproved_posts'), 'post_unapproved_replies' => array(true, 'topic', 'make_unapproved_posts', 'make_unapproved_posts'), 'post_reply' => array(true, 'topic', 'make_posts', 'make_posts'), 'merge_any' => array(false, 'topic', 'moderate'), 'split_any' => array(false, 'topic', 'moderate'), 'send_topic' => array(false, 'topic', 'moderate'), 'make_sticky' => array(false, 'topic', 'moderate'), 'move' => array(true, 'topic', 'moderate', 'moderate'), 'lock' => array(true, 'topic', 'moderate', 'moderate'), 'remove' => array(true, 'topic', 'modify', 'moderate'), 'modify_replies' => array(false, 'topic', 'moderate'), 'delete_replies' => array(false, 'topic', 'moderate'), 'announce_topic' => array(false, 'topic', 'moderate'), 'delete' => array(true, 'post', 'modify', 'moderate'), 'modify' => array(true, 'post', 'modify', 'moderate'), 'report_any' => array(false, 'post', 'participate'), 'poll_view' => array(false, 'poll', 'participate'), 'poll_vote' => array(false, 'poll', 'participate'), 'poll_post' => array(false, 'poll', 'post_polls'), 'poll_add' => array(true, 'poll', 'post_polls', 'moderate'), 'poll_edit' => array(true, 'poll', 'modify', 'moderate'), 'poll_lock' => array(true, 'poll', 'moderate', 'moderate'), 'poll_remove' => array(true, 'poll', 'modify', 'moderate'), 'mark_any_notify' => array(false, 'notification', 'notification'), 'mark_notify' => array(false, 'notification', 'notification'), 'view_attachments' => array(false, 'attachment', 'participate'), 'post_unapproved_attachments' => array(false, 'attachment', 'make_unapproved_posts'), 'post_attachment' => array(false, 'attachment', 'attach'), ), );
The first array contains the general permissions, the second board specific permissions.
Each array specifies 3 or 4 parameters, as listed bellow.
Own/any
required: true/false -> whether the permission has multiple options, either for the permission standing on its own, or whether it has own/any variations. For example, poll_add can be granted either to 'own' (adding to user's own topics) or 'any' (adding to any topic)
Classic group name
required: string. Details which group of 'Classic' permissions the permission gets added under:
- general - General (e.g. View forum statistics)
- pm - Personal Messages
- calendar - Calendar permissions
- maintenance - Forum administration
- member_admin - Member adminstration
- profile - Member Profiles
- general_board - general board permissions (currently only moderate board)
- topic - topic specific permissions
- post - post related
- poll - poll related
- notification - notifications related
- attachment - attachment related
To add a permission to any of these groups, simply state the permission's name as the second parameter for classic view.
"Simple" group name
required: string. Details which group a permission will be added into for 'Simple' permissions.
- view_basic_info - "Use basic forum functionality"
- use_pm_system - "Contact members using the personal messaging system"
- post_calendar - "Post events on to the calendar"
- edit_profile - "Personalize their profile"
- delete_account - "Delete their account"
- use_avatar - "Select or upload an avatar"
- moderate_general - "Moderate the entire forum"
- administrate - "Carry out administrative duties"
- make_posts - "Post topics and replies to the board"
- make_unapproved_posts - "Modify their posts"
- post_polls - "Make new polls"
- participate - "View additional board content"
- modify - "Modify their posts"
- notification - "Request notifications"
- attach - "Post attachments"
- moderate - "Moderate the board"
The fourth parameter is only required if the first was true, i.e. a permission has multiple components. Then, the third parameter names the group in Simple permissions for _own, the fourth parameter is the group in Simple permissions for _any.
The only thing remaining to do is to define the text that will be displayed. This can be done in the ManagePermissions.{language}.php, but is ideally better placed in Modifications.{language}.php.
There are multiple language strings to add, potentially. For a permission named 'do_something', the following entries in $txt can be listed: $txt['permissionname_do_something'] - the description of the permission (this is the only one that is required) $txt['permissionhelp_do_something'] - the help text of the permission (the ? next to it in the permissions screen) $txt['permissionname_simple_do_something'] - the description of the permission for Simple view, not required but will be used in place of permissionname_do_something if declared. $txt['permissionhelp_simple_do_something'] - the help text of the permission for Simple view, again not required but will be used in place of permissionhelp_do_something if declared.
Note also that if a permission is declared as having multiple options (first parameter), do_something would not be correct; do_something_own and do_something_any would be the generated permissions, with do_something being the placeholder for it:
$txt['permission_do_something'] -> the description of the permission (only) $txt['permission_do_something_own'] -> typically "Own {something}" e.g Own replies, own polls $txt['permission_do_something_any'] -> typically "Any {something}" e.g. Any replies, any polls
[b]Adding a permission group[/b] Adding a group of permissions is very simple if placement is not a concern.
Simply add an identifier to the new permissions for their new group - much like 'post_polls' or 'notification', though note that a group cannot be named the same between general and board specific permissions and should not be named the same between simple and classic views.
Once the identifier has been added to the new permission, e.g.:
'do_something' => array(false, 'something', 'something_opts'),
The remaining task is to specify language strings, again in Modifications.{language}.php. This time, the prefix is permissiongroup_ and permissiongroup_simple_:
$txt['permissiongroup_something'] = 'Something'; $txt['permissiongroup_simple_something_opts'] = 'Something that our users can do';
It is possible to modify the order in which groups appear. To do so, find this array:
$permissionGroups = array( 'membergroup' => array( 'simple' => array( 'view_basic_info', 'use_pm_system', 'post_calendar', 'edit_profile', 'delete_account', 'use_avatar', 'moderate_general', 'administrate', ), 'classic' => array( 'general', 'pm', 'calendar', 'maintenance', 'member_admin', 'profile', ), ), 'board' => array( 'simple' => array( 'make_posts', 'make_unapproved_posts', 'post_polls', 'participate', 'modify', 'notification', 'attach', 'moderate', ), 'classic' => array( 'general_board', 'topic', 'post', 'poll', 'notification', 'attachment', ), ), );
Then simply add the new group in the relevant position in that array, using the same group identifier. Note that this is *not* required for just adding permissions; it simply controls where it will be if specific placement is desirable, rather than "at the end".
Checking a permission
No permission will of itself do anything. As part of SMF itself, or inside a mod, the permission must be checked by the code.
allowedTo()
Returns a true/false that indicates whether the user has the specified permission.
[[1]]
boardsAllowedTo()
This will check the permission and if not granted, force an error that will immediately suspend execution. $txt['cannot_do_something'] holds the error message.
For permissions that have own and any variations, the string would be $txt['cannot_do_something_own'] and $txt['cannot_do_something_any'] as necessary.
[[2]]
boardsAllowedTo()
Returns a list of boards in which the user has the specified permission.
[[3]]
groupsAllowedTo()
Retrieves a list of membergroups that are allowed to do the given permission.
[[4]]
membersAllowedTo()
Retrieves a list of members that are allowed to do the given permission.
[[5]]
Allowing permissions in all groups
If you're writing a mod you might want to make your permission allowed by default. You can do this by adding a php code file to your mod, with the following code (adjusted to your permission's name of course!):
<?php
// Initialize the groups array with 'ungrouped members' (ID: 0).
// Add -1 to this array if you want to give guests the same permission
$groups = array(0);
// Get all the non-postcount based groups.
$request = db_query("
SELECT ID_GROUP
FROM {$db_prefix}membergroups
WHERE minPosts = -1", __FILE__, __LINE__);
while ($row = mysql_fetch_assoc($request))
$groups[] = $row['ID_GROUP'];
// Give them all their new permission.
$request = db_query("
INSERT IGNORE INTO {$db_prefix}permissions
(permission, ID_GROUP, addDeny)
VALUES
('my_permission', " . implode($groups) . ", 1)", __FILE__, __LINE__);
?>
To add a board permission, replace the last query with the following:
<?php
// Give them all their new global board permission.
$request = db_query("
INSERT IGNORE INTO {$db_prefix}board_permissions
(permission, ID_GROUP, ID_BOARD, addDeny)
VALUES
('my_board_permission', " . implode($groups) . ", 0, 1)", __FILE__, __LINE__);
?>
'TO BE CONTINUED...
