09. Letting Drupal know about the new function
Main topic described: Using Drupal Menu system
Drupal hook described: hook_menu
As mentioned previously, the function we just wrote isn't a 'hook': it's not a Drupal recognized name. We need to tell Drupal how to access the function when displaying a page. We do this with Drupal's hook_menu. Remember that we have already used hook_menu in the seventh tutorial in this series. The hook_menu defines the association between a URL and the function that creates the content for that url. The hook also does permission checking, if desired. We will use the hook_menu made previously and continue with it.
<?php
function onthisdate_menu() {
$items = array();
//this was created earlier in tutorial 7.
$items['admin/settings/onthisdate'] = array(
'title' => 'On this date module settings',
'description' => 'Description of your On this date settings control',
'page callback' => 'drupal_get_form',
'page arguments' => array('onthisdate_admin'),
'access arguments' => array('access administration pages'),
'type' => MENU_NORMAL_ITEM,
);
//this is added for this current tutorial.
$items['onthisdate'] = array(
'title' => 'On this date',
'page callback' => 'onthisdate_all',
'access arguments' => array('access onthisdate content'),
'type' => MENU_CALLBACK
);
return $items;
}
?>Basically, we're saying if the user goes to "onthisdate" (either via ?q=onthisdate or http://example.com/onthisdate), the content generated by onthisdate_all will be displayed. The title of the page will be "On this date". The type MENU_CALLBACK tells Drupal to not display the link in the user's menu, just use this function when the URL is accessed. Use MENU_NORMAL_ITEM if you want the user to see the link in the side navigation block.
Permissions
As mentioned before in the seventh tutorial, the menu hook can handle permission checking before rendering the page. The 'access arguments' entry in the menu item array is where this check is done. If you added a value in your permissions array in the perm hook function, you can use that string as a parameter in the user_access function. If the user isn't in a role that has that permission, the page will not render for the user.
Try It Out
If the module has not been enabled, enable it as outlined in tutorial six. If you have already enabled it, in order to reset the menu definitions in the system, you'll need to disable, then reenable it.
Now, navigate to /onthisdate (or ?q=onthisdate) and see what you get.
Enable again
When you make changes to the hook_menu:
* be careful when you clear cache. it can bring down your whole site.
* it seems you need to disable and enable a module for changes to take effect
rinky dink, kinda.
M
Erm, why?
Isn't that what I did when, following the tutorial, I stuck in the perm hook function?
I assumed this meant users would be denied access to this block/page unless they had the view content permission.
The above code has this 'access arguments' thing going on so why would I be calling 'user_access' myself?
I'm finding this permissions stuff kinda confusing here and I don't want to end up missing something and writing insecure code so: Anyone care to explain this to me, or point me to the relevant docs?
Thanks,
Roger Heathcote - www.technicalbloke.com
hook_perm just gives names to permissions
The array you return from hook_perm is used by hook_menu (in the access_argument key) and hook_access to determine which roles have access to which pages or functions at your site.
hook_perm just 'defines' the permissions, it does not actually grants or denies access.
To link roles to permissions you need to visit /admin/user/permissions
Regards.
Alexis Bellido
Ventanazul: web development and Internet business consulting shouldn't be boring
Not only drupal_get_form
As a newbie I copied/pasted stupidly the hook_menu example, but this is important to have a look at http://api.drupal.org/api/file/developer/examples/page_example.module/6 & http://api.drupal.org/api/function/page_example_menu/6 to better understand the different options when using this hook.
using drupal_get_form only works if you use a form in your callback function ;-) , which was not my case at this stage of my module development...
Sounds so logical for advanced users that is not clearly explained, but worth to detail it a bit more for beginners.