Controlling who can access what in the site is a big part of Scoop. You'll notice have_perm() and have_section_perm() riddled throughout scoop in conditionals. This section is a quick overview of the functions you'd use to check a users' permissions, either for general stuff (have_perm()) or for story/comment section stuff ( have_section_perm() )
By general permissions we mean permissions that you can give and take from people in the Group3.12->3.11 admin tool. What follows is very similar to the perlpod for Perms.pm, but with more information.
$S->get_perms() | Takes nothing as an argument, but returns an array reference of all of the possible permissions in Scoop. Don't forget to update this list ( hidden in Scoop::Admin::Perms::get_perms() btw ) anytime you add a new permission. If you don't update this list, you won't be able to edit that permission for anyone. |
$S->group_perms($gid) | Takes a group ID, and returns the perms hash for that user. If no $gid is given, it uses $S->{GID} (the users group id). The perm hash has the form where the keys are the perm name, and the value is 1 if they have that perm. |
$S->have_perm($perm) | Optionally will take a group id after $perm. This is the main function used for testing if a user has permission to do a certain action. $perm is one of the permissions returned from get_perms(). This will return true if the user has that permission, and false otherwise. |
Section permissions are how Scoop controls which groups can read or post stories or comments in any given section. There are four main section permissions, and three types of each of those. The four main types are 'read_comments', 'read_stories', 'post_comments', and 'post_stories'. Each of these is divided up into the three subpermissions by appending 'norm_', 'hide_', or 'read_' to the front of the permission.
The intent is this: if a group has the 'norm_*' version of the permission, then they can do whatever that permission is. So a group with 'norm_post_stories' permission in section news can post stories to section news until the cows come home. But a group with only 'deny_post_stories' in that section will get a message from scoop like ``Sorry, but you don't have permission to post stories to that section'' when they try to post a story to that section (they shouldn't get the option in the pulldown menu anyway, but people do crazy things like edit html forms in this day and age... ;). Lastly, if they have the 'hide_post_stories' permission for a given section, when they try to post to that section Scoop will respond with something like ``Sorry, but that section does not exist'', effectively pretending that it doesn't exist. This could be useful for secret admin only sections, if you didn't want anyone to know about them.
Generally this is programmed as follows:
... some code ... unless( $S->have_section_perm('norm_post_comments') { if( $S->have_section_perm('deny_post_comments') { print ``you don't have permission to post comments here\n.''; } else { print ''; } } ... more code...Following is a short summary of the section functions. NOTE: if you pass only the first part of a section permission, like 'read_comments' to one of the section permission functions like have_section_perm(), it will always return true. Be sure to use the full name of a permission in tests.
$S->get_sections() | Similar to get_perms() this returns all of the sections that are in the scoop site. |
$S->have_section_perm($sect_perm,$section,$optionalGID) | Similar to have_perm(), but just different enough to get you in trouble. $sect_perm is one of the permissions listed above in the beginning of this section. $section is a section on your site. The group id is optional, since if you don't supply it it will use $S->{GID}. |
$S->get_disallowed_sect_hash($perm) | Similar to group_perms(). Takes a permission, and returns a hash of all of the sections that the current group ($S->{GID}) has that permission in. The keys are the section names and the values are 1. If they don't have permission in that section, its key doesn't exist. |