Specifying a custom permission for a new page
- Drupal version: Drupal 7.x
- Audience: Developers and coders
- Page status: Needs technical review
- Last modified: April 6, 2011
Drupal hooks described: hook_permission(), hook_menu()
So far we have our working block and a settings form. The block displays a maximum number of links. However, there may be more links than the maximum we show. So we'll create a page that lists all the content that was created in the last week.
Custom permission
First, we'll create a custom permission, using hook_permission(). The permissions this hook defines can be configured at People > Permissions (tab), or http://example.com/admin/people/permissions. Only user roles with this permission granted will have access to the page we will create.
Add this to your .module file:
/**
* Implements hook_permission().
*/
function current_posts_permission(){
return array(
'access current_posts content' => array(
'title' => t('Access content for the Current posts module'),
)
);
}
?>
This hook follows the typical Drupal pattern of attributes defined in arrays. The main key is the machine readable name of the permission, which we will use in our hook_menu() implementation. 'title' provides the human-readable name of the permission, to be shown on the permission administration page. This should be wrapped in the t() function for translation. See hook_permission() for all the available options.
Registering the URL and naming the page function
We'll need to edit current_posts_menu() to establish a path and name for the new page. A quick note on function naming conventions in Drupal: If you are creating a strictly private function (i.e. no other module should rely on it being a stable function or call it), start the function name with an underscore: "_your_module_name_". If your function is public (i.e. it would be okay for another module to call it, and you don't intend to change its argument signature or behavior often), start the function name with "your_module_name_" (no underscore). If you are implementing a Drupal hook, you must always name the function "your_module_name_hookname". Likewise, if you are not implementing a Drupal hook, check the hooks to be sure you have not accidentally picked a function name matching a hook.
Page callbacks are good candidates for strictly private functions, so we will start with an underscore, then the module name, and finally the word, 'page'. Add the following code to your current_posts_menu() function as the second item in the $items array. Be sure the code, return $items; is the final line of the function, and remember not to include the php markers.
$items['current_posts'] = array(
'title' => 'Current posts',
'page callback' => '_current_posts_page',
'access arguments' => array('access current_posts content'),
'type' => MENU_NORMAL_ITEM, //Will appear in Navigation menu.
);
?>
This listing mirrors the previous menu item with a couple of exceptions. The first needed a description for the Configuration page. That's less important here, and we are not including it. Because we are creating a page function and not calling drupal_get_form, we have no page arguments to pass. The new permission becomes the access argument. Since we are not using the admin/config path, our item will appear in the Navigation menu.
Check
Enable your module again and check the Navigation menu. You should see a listing for Current posts. If it's not there, try clearing the caches. Because we have not yet written the page function, the link leads to a blank page, and you may get an error message. Remember to disable your module before continuing.