diff options
| -rw-r--r-- | modules/node/node.api.php | 60 |
1 files changed, 29 insertions, 31 deletions
diff --git a/modules/node/node.api.php b/modules/node/node.api.php index abefd752a..a8e5d1e4c 100644 --- a/modules/node/node.api.php +++ b/modules/node/node.api.php @@ -14,15 +14,16 @@ /** * Inform the node access system what permissions the user has. * - * This hook is for implementation by node access modules. In addition to - * managing access rights for nodes, the node access module must tell - * the node access system what 'grant IDs' the current user has. In many - * cases, the grant IDs will simply be role IDs, but grant IDs can be - * arbitrary based upon the module. + * This hook is for implementation by node access modules. In this hook, + * the module grants a user different "grant IDs" within one or more + * "realms". In hook_node_access_records(), the realms and grant IDs are + * associated with permission to view, edit, and delete individual nodes. * - * For example, modules can maintain their own lists of users, where each - * list has an ID. In that case, the module could return a list of all - * IDs of all lists that the current user is a member of. + * The realms and grant IDs can be arbitrarily defined by your node access + * module; it is common to use role IDs as grant IDs, but that is not + * required. Your module could instead maintain its own list of users, where + * each list has an ID. In that case, the return value of this hook would be + * an array of the list IDs that this user is a member of. * * A node access module may implement as many realms as necessary to * properly define the access privileges for the nodes. @@ -31,9 +32,10 @@ * The user object whose grants are requested. * @param $op * The node operation to be performed, such as "view", "update", or "delete". + * * @return - * An array whose keys are "realms" of grants such as "user" or "role", and - * whose values are linear lists of grant IDs. + * An array whose keys are "realms" of grants, and whose values are arrays of + * the grant IDs within this realm that this user is being granted. * * For a detailed example, see node_access_example.module. * @@ -50,29 +52,25 @@ function hook_node_grants($account, $op) { /** * Set permissions for a node to be written to the database. * - * When a node is saved, a module implementing node access will be asked - * if it is interested in the access permissions to a node. If it is - * interested, it must respond with an array of array of permissions for that + * When a node is saved, a module implementing hook_node_access_records() will + * be asked if it is interested in the access permissions for a node. If it is + * interested, it must respond with an array of permissions arrays for that * node. * - * Each item in the array should contain: - * - * 'realm' - * This should only be realms for which the module has returned - * grant IDs in hook_node_grants. - * 'gid' - * This is a 'grant ID', which can have an arbitrary meaning per realm. - * 'grant_view' - * If set to TRUE a user with the gid in the realm can view this node. - * 'grant_edit' - * If set to TRUE a user with the gid in the realm can edit this node. - * 'grant_delete' - * If set to TRUE a user with the gid in the realm can delete this node. - * 'priority' - * If multiple modules seek to set permissions on a node, the realms - * that have the highest priority will win out, and realms with a lower - * priority will not be written. If there is any doubt, it is best to - * leave this 0. + * Each permissions item in the array is an array with the following elements: + * - 'realm': The name of a realm that the module has defined in + * hook_node_grants(). + * - 'gid': A 'grant ID' from hook_node_grants(). + * - 'grant_view': If set to TRUE a user that has been identified as a member + * of this gid within this realm can view this node. + * - 'grant_edit': If set to TRUE a user that has been identified as a member + * of this gid within this realm can edit this node. + * - 'grant_delete': If set to TRUE a user that has been identified as a member + * of this gid within this realm can delete this node. + * - 'priority': If multiple modules seek to set permissions on a node, the + * realms that have the highest priority will win out, and realms with a lower + * priority will not be written. If there is any doubt, it is best to + * leave this 0. * * @ingroup node_access */ |