Drupal 7 Module Development Part 2 - hook_menu and hook_permission

By shane
Thu, 2012-09-27 23:50
Daily Dose of Drupal Episode #17

Share with Others

In this episode we continue learning about Drupal 7 module development by looking at creating menu items with hook_menu() and creating permissions with hook_permission().

In this episode you will learn:

  • How to implement hook_menu() in you Drupal 7 module to create a new page on your Drupal site
  • How to implement hook_permission() in your Drupal 7 module to provide access control to your newly created page

Welcome to another Daily Dose of Drupal, this is Shane and this Episode number 17. Today we’re going to be continuing on the Drupal 7 Module Development basics we went over yesterday and looking at hook_menu and hook_permission or Hooks for Drupal and of course we have our Drupal 7 module here, yesterday we created called My Block.

If you did not follow along with yesterday’s example you may want to go back and look at that or if you have any custom module or you’re familiar with creating at least the basics of a custom module you can go ahead and do that and you can probably follow along without much difficulty.

So hook_menu; what is it and why do we need to use it? Anytime you want to define a Menu Item or a Page Callback inside your Drupal module you’ll need to use hook_menu. This is important for Administration Pages for example or if you have a custom form that you want to build on a custom page and you’ll use this for Ajax Callbacks potentially depending on how you set it up of course or any type of … any setting where you need to access something or some resource from your website from a specific URL.

So for instance if I want to get to a specific URL on a page and I don’t want to use the traditional Content Type to do that I can define something in a Custom Drupal Module and it’s really pretty basic and pretty straight forward but there’s a couple of caveats to hook_menu. A couple of things that you’re going to need is an example; we’ll go ahead and just grab this very first example here; so if we go ahead and inside of our module I’m just going to drop it at the top, add my comment to it and fix the indenting a little bit and let’s go over on what this is doing. In this case we’re defining a URL structure of ABC/DEF and we’re making a Page Callback call to this function so this would be a function we’re going to need to define and we can pass in specific arguments.

For this example; we’re not going to be passing any arguments into our functions so we’re going to get rid of that, we’re going to give it a title which is the actual title of our page, we’ll just call this My Page, for the URL we’re going to access it through My Page, I’ll lower case and for the Page Callback we’ll use myblock_mypage and keep in mind that myblock is just the name of my module so I of course have to change that here and obviously it might not be the best name in this case but this could be whatever your module name is and so generally you’d want to name your functions that you’re creating with myblock or your module name whatever it is, Underscore something so you’ll know how to … where it’s at and how to access that Callback function.

You can define specific types of Menu Items and I encourage you to read the documentation on drupal.org for hook_menu because it’s going to tell you what these different types means … what these different types of menu of definitions mean, Menu normal item, Menu Callback is one that get’s use often.

If you want to integrate within the Drupal Tab system you can have local tasks and a whole bunch of other things and these are defined right down here, talks about Menu Normal Item, Menu Default Local Task, Menu Local Task and it gives you an example that you can take in and use for how that can be useful.
Inside hook_menu on api.drupal.org you’ll see it talks about all the different things that you can add into this array for the specific Menu Item, there’s Title, Title Callback and on down the list. The other one we’re going to look at and you can see there’s a whole bunch … not all of them get used that often but there’s a lot of things there.

The other thing we’re going to add is access argument and you can define a simple array here that’s going to look at the permissions of the current user and see if they have this permission. In this case we’re going to say “can they access content on the website?” So we’re going to go ahead and open up another browser here, get all of this stuff and go to the test website.

So now I’m logged in as anonymous user and as the admin user. So before I can see this page I have to actually create that function, add a simple description there and notice since we didn’t have any page arguments, this is going to be empty. If we had Page Arguments we would have variables in there and here you can just return any HTML you want to be rendered on your page. In this case we’re just going to output some very simple HTML, also we’ll be focusing in a future episode on renderable arrays as that’s kind of the … a new way you should be doing it in Drupal 7 but to keep things simple we’re just going to output straight HTML here. Now if we save this and we come up here to My Page you’ll notice it is not going to work.

You’ll see the requested page cannot be found. The trick here is anytime you change something at hook_menu you need to clear out the Menu cache so I’m going to do this through Drush and in this case the selection is 3, you can also go to Configuration → Performance and clear the cache that way.

Now if I come back to this page you’ll see that I’m able to get to my page, I had this block here which I’m just going to come to my blocks and hide that for now since just kind of getting in the way and now if I come back you can see the title is My Page, it’s also up here and there is my text.

So very simple, the only other thing we’re going to do is implement hook_permission to create our own Permission. And we will go ahead and copy this simple example here, I’m going to paste this at the top, there’s really no specific order you have to implement these Hooks in, it’s more or less however you see it fit but there’s … I have a kind of a general order that I follow for the most part but as long as you’re consistent across your modules that will be easy for you to go ahead and find out or easily locate these different functions.
So I replaced the Hook Text with the name of my module and we get to define our permissions so I’m going to say “access mypage” you can give it a title. So you can give it a title on the Description and that’s all really all there is to it. We can go ahead and save this and obviously you can have multiple here, you can add another one right below here and define a bunch of permissions inside of your module, we’re going to define the 1 and now if we come back here and we go to People and Permissions you’ll notice that if we search for My Page and My Block module there’s now a Permission called Access MyPage.

If we don’t want to go back to this My Page you’ll noticed that it still works because I’m logged in as user 1and make sure of course to actually change the Access Argument here to use your new Permission. Before I forget; so access My Page. Let’s save it and hop over to Drush to clear the Menu cache again I changed that menu Item so I need to make sure that I clear the cache, if I refresh I’m still able to access because I’m logged in as user 1. However; I come over here and I am not logged in I get an Access Denied.

Lets’ go ahead and change that so anonymous users can access that page; we come in to Permissions, find the Permission and we’re going to give access to anonymous and authenticated users, scroll all the way down to the bottom, hit Save. Now if I hop back over here and refresh I can get to the page.

As simple as that. Obviously there’s a lot more to hook_menu and I just encourage you look over that documentation on api.drupal.org on hook_menu as that will be very valuable when you’re trying to learn all the in’s and out’s of what you can do. That’s it for this time; tomorrow we’re probably going to focus on some more Drupal Module Development Hooks and just a little work away through most of the basics.

So if you have any questions or if you want to see anything specific on future episode of the Daily Dose of Drupal go ahead and contact me via Twitter or on codekarate.com, follow me @smthomas3 or sign up for my codekarate.com newsletter. Thanks for watching the Daily Dose of Drupal.