Ready to watch this entire course?
Become a member and get unlimited access to the entire skills library of over 4,971 courses, including more Developer and personalized recommendations.Start Your Free Trial Now
- View Offline
- Creating your first module
- Interacting with hooks
- Working with permissions and roles
- Controlling access
- Adding a menu item to an admin interface
- Using the Form API (FAPI) to quickly create a form
- Creating custom form validation
- Manually creating a custom content type
- Validating user input
- Importing content using feeds
- Creating a block
- Understanding best practices and coding standards
Skill Level Advanced
Before I create the wind farms administrative interface, I need to describe the location of the interface to Drupal. The menu system, which is distinct from the actual menu module, defines the navigational menus and routes page requests to code, based on URLs. These routes based on URLs are known as paths. The menu module itself provides an administrative interface to allow menus and the routing to be managed. To add a new menu item and routing path to the menu system, I will use hook_menu.
Items added via hook_menu are aggregated by the menu system and assigned a hierarchy. This hierarchy can be initially setting code, but can also be manipulated using the menu module through the admin interface. Hook_menu defines menu items in page callbacks. This means a module can define what items are shown in the menu, the path that is associated with the menu item, ends the callbacks to be used when that path is accessed. The menu system does not access hook_menu very often, instead relying on caches to increase performance.
Similar to when the permission was added, the cache will need to be cleared after hook_menu is implemented. Looking at the hook_menu API I can see that it takes no parameters and returns an array structure. Open the browser and navigate to the Configuration menu. There are a number of groups each with a description and a number of individual menu settings. I will be adding a group for wind farms and an interface for managing wind farms settings to the page. Note the page URL, admin config, this will be used when defining the menu items.
Open the IDE and open windfarms.module. Start by adding a docblock that states that this function will implement hook_menu. Next, create the function itself. The function will be named windfarms_menu; it takes no parameters. I will be adding menu items, so I will name the return value to reflect that. Start by initializing an empty array, when the menu items have been defined they should be returned.
Adding menu items to this particular administrator section is unique, in that, unless the plan is to add a menu item to an existing group, a new group will have to be created. Fortunately, this can be accomplished through hook_menu, the first item I will create is to group any settings associated with a windfarms module. I will start with an in-line comment describing what this menu item is going to do. Note that I'm using the Drupal coding standard for in-line comments meaning that the comment is structured like a regular sentence and ends with a full stop; Admin configuration group.
Next I'm going to add an array to the items array keyed by the path. As the admin page URL is admin config, I will start with that followed by the name of the custom module. Remember not to start the path with a slash; items admin/config/windfarms is assigned to array. There are over a dozen different keys that can be used to configure menu items, but most are optional and have logical defaults so they can be left out.
For an item to appear on a menu, it must have a title, which will be shown to the user as a bold heading. The menu system uses a callback to process the title and the description which defaults to the t function. So wrapping the value in t is not necessary; title Wind Farms. In addition to the title a description of the group should be added. With the default admin view this won't be visible, but some contributed administrative modules do use it and it's a best practice to always include the description; description Administer Wind Farms.
Finally, I need to define who has permission to see these settings. In the previous segment, I created a custom permission. I will use that now, to manage access control there are two parameters; the access arguments and the access callback. By default, the access callback function is user access; meaning it will be checking our permission by name. As I created a permission that is used by user access I can use the default for the callback. I do need to specify the name of the permission to check which I will do with a key named access arguments array administer wind farms.
This completes the configuration group. Now that I have a place to put the custom menu item, I can create it. Start a new comment, this one for the settings menu item; Admin configuration settings. Next add a new element to the items array keyed with a path. I will use the same path as above, with one addition, manage. Which will be the name of the page that I will create to manage wind farms settings; items admin/config/windfarms/manage = array, same as before a title is needed.
Give it a logical name and stay concise. In this case, title Wind Farm settings. The description which will be shown on the regular admin page should be short and to the point; description Manage Wind Farm settings and configurations. Define the access arguments. This can be the same as the previous menu item; copy paste.
As the menu item is actually referring to a place that can be navigated to additional steps are needed to allow this to function. The first thing that is needed is a definition of a page callback. The page callback is the name of the function that displays a web page when a user visits the path. In this case, I'm going to leverage some of Drupal's built-in functionality to quickly add a complete system for building a form, validating the input and handling the form submission. I'm going to describe how to work with Drupals form API or FAPI in the next segment.
For now, all that is needed is the name of the page callback, Drupal get form which is part of the form API, page callback => drupal_get_form. Drupal_get_form takes one parameter, the form identifier. So I will pass that as a page argument, so drupal_get_form knows which form to process. I have not created the form yet. But I can anticipate the name. Forms are defined with hook form. So I know that the function name will start with the custom module name windfarms.
Hook form allows multiple implementations within a module. Each with a distinct name as long as they end with underscore form. This helps with code organization, instead of having one giant hook form with a switch statement. As this is an admin settings form, call it what it is; similar to the other hooks the function name will and in form. Therefore, the full identifier of the form will be windfarms_admin_settings_form, page arguments => array(windfarms_admin_settings_ form') save the module, then return to the browser and refresh the admin configuration page.
Similar to permissions, the menu system also leverages caches. So the new group is not visible yet. Clear the cache as to be able to see the changes by going to the DEVELOPMENT group, and clicking on Performance. Then clear all caches, return to the admin Configuration page and the new Wind Farms group is now visible. Click on the menu item. You'll see two legitimate error messages.
The first means that Drupal retrieve form was unable to find a form by that name. The next message is a complaint that the callback is invalid. Let's create the form in the next segment to make this interface useful.