modules/pwn/README.txt

// $Id: README.txt,v 1.8 2010/02/25 04:15:44 ceardach Exp $

PERMIT OWN PERMISSIONS

Users in roles possessing the 'share permissions' permission are given the
ability to access the permissions administration page like a user with
'administer permissions', but they can only see permissions that exist in one of
their roles.

No configuration necessary (or available), except for granting selected roles
the 'share permissions' capability at http://example.com/admin/user/permissions
(where example.com is the URL of your web site).


Installation
------------

Copy the pwn directory into your website's sites/all/modules directory, then
activate the module by visiting your site's modules page.

If you are using drush, you may enter the following commands:
  drush dl pwn
  drush enable pwn


Requirements
------------

  - Drupal 6 or later, though there is no reason it could not be backported


API
----

pwn_compare_permissions($permsA, $permsB)
  Returns TRUE if all permissions in permsB are in permsA, otherwise it returns
  FALSE because permsB has some value that permsA does not have

pwn_get_permissions_for_roles($role_ids)
  Returns all permissions associated with the set of roles provided

pwn_grant_role($rid, $account = NULL)
  Checks to see if the given account could grant the given role when comparing
  which permissions each has.  If the role has any permissions the given account
  does not have access to, then this will return FALSE.

pwn_user_access_any($permA, $permB, ...)
  Returns TRUE if the user has any of the permissions.  Effectively a wrapper
  function for user_access().


Hooks Implemented
-----------------

hook_menu_alter()
  Adds the ability to access the permissions matrix if the user has the 'share
  permissions' permission

hook_form_user_admin_perm_alter()
  Hides all permissions in the permissions matrix that the current user does
  not have themselves

hook_form_user_register_alter()
  Adds ability to grant roles for users with 'share permissions through roles'
  permission

hook_form_user_profile_form_alter()
  Adds ability to grant roles for users with 'share permissions through roles'
  permission

hook_user()
  Validates modifications to form made in hook_form_user_profile_form_alter()


Additional Behaviors
--------------------

Permissions:
  - share permissions
    Allows a user to assign and revoke permissions to roles, where the
    permissions available are only composed of permissions the user currently
    has.
  - share permissions through roles
    Allows a user to assign and revoke roles to users, as long as those roles
    only contain permissions the user current has.  If any role contains a
    permission the user does not have themselves, they will not be able to grant
    or revoke that role from another user.
1	// $Id: README.txt,v 1.8 2010/02/25 04:15:44 ceardach Exp $
2
3	PERMIT OWN PERMISSIONS
4
5	Users in roles possessing the 'share permissions' permission are given the
6	ability to access the permissions administration page like a user with
7	'administer permissions', but they can only see permissions that exist in one of
8	their roles.
9
10	No configuration necessary (or available), except for granting selected roles
11	the 'share permissions' capability at http://example.com/admin/user/permissions
12	(where example.com is the URL of your web site).
13
14
15	Installation
16	------------
17
18	Copy the pwn directory into your website's sites/all/modules directory, then
19	activate the module by visiting your site's modules page.
20
21	If you are using drush, you may enter the following commands:
22	drush dl pwn
23	drush enable pwn
24
25
26	Requirements
27	------------
28
29	- Drupal 6 or later, though there is no reason it could not be backported
30
31
32	API
33	----
34
35	pwn_compare_permissions($permsA, $permsB)
36	Returns TRUE if all permissions in permsB are in permsA, otherwise it returns
37	FALSE because permsB has some value that permsA does not have
38
39	pwn_get_permissions_for_roles($role_ids)
40	Returns all permissions associated with the set of roles provided
41
42	pwn_grant_role($rid, $account = NULL)
43	Checks to see if the given account could grant the given role when comparing
44	which permissions each has. If the role has any permissions the given account
45	does not have access to, then this will return FALSE.
46
47	pwn_user_access_any($permA, $permB, ...)
48	Returns TRUE if the user has any of the permissions. Effectively a wrapper
49	function for user_access().
50
51
52	Hooks Implemented
53	-----------------
54
55	hook_menu_alter()
56	Adds the ability to access the permissions matrix if the user has the 'share
57	permissions' permission
58
59	hook_form_user_admin_perm_alter()
60	Hides all permissions in the permissions matrix that the current user does
61	not have themselves
62
63	hook_form_user_register_alter()
64	Adds ability to grant roles for users with 'share permissions through roles'
65	permission
66
67	hook_form_user_profile_form_alter()
68	Adds ability to grant roles for users with 'share permissions through roles'
69	permission
70
71	hook_user()
72	Validates modifications to form made in hook_form_user_profile_form_alter()
73
74
75	Additional Behaviors
76	--------------------
77
78	Permissions:
79	- share permissions
80	Allows a user to assign and revoke permissions to roles, where the
81	permissions available are only composed of permissions the user currently
82	has.
83	- share permissions through roles
84	Allows a user to assign and revoke roles to users, as long as those roles
85	only contain permissions the user current has. If any role contains a
86	permission the user does not have themselves, they will not be able to grant
87	or revoke that role from another user.