Drupal 7 Module Development Part 3 - Drupal Administration Forms

By shane
Fri, 2012-09-28 13:02
Daily Dose of Drupal Episode #18

Share with Others

Learn how to create an administration form inside a Drupal module. In this episode we work with the Drupal 7 Form API to build out an administration section for a brand new module. This new module (called cronmonitor) will be completed in the next Daily Dose of Drupal episode (number 19).

In this episode you will learn:

  • How to build a Drupal administration form inside a Drupal 7 module
  • How to set the configure option inside your modules .info file
  • How to implement hook_menu and hook_permission to create an administration page
  • How to build the Drupal administration form using the Drupal 7 Form API and the system_settings_form function

Welcome to another Daily Dose of Drupal, this is Episode Number 18. Today we’re going to continue on our Drupal Module Development learning and we’re going to focus on building a brand new Drupal module from scratch. This Drupal module is going to be a little bit trivial and not necessarily a practical use case I guess but it’s going to show you a couple of different things.

The module is essentially going to monitor every time that Cron is run on your Drupal site and it’s going to send you an e-mail, very simple but it’s going to go over how to build an Administration form in a Drupal module, how to use hook_cron to do things periodically on your site when Cron is run and it’s going to talk about how to send e-mails from your Drupal module.

And today’s episode we’re just going to cover the Administration form and next time we will cover hook_cron and the sending of the e-mails. So we’re going to get started; we have our test site here and inside of it we’re going to create a new module, we’re going to call this cron_monitor. Inside there I’m going to create a cron_monitor.info file and a cron_monitor.module file, I’m going to hop over to my Code Editor and open these files up and our .info file we’re going to give this a name, okay in the description we’re going to say that we want it to be 7.x module, we’ll give it a version and we’re also going to give it a configuration page and this is going to be important and I’ll show you why in a little bit but we want this configuration or administration form to be accessed to admin/config/cron_monitor, so we save this and the Info file should be good to go.

The next step is to start on the Drupal module file. So in order to do that we’ll just go ahead and open up the Page View tag; we obviously could add a little file header here but I’m just going to start with implementing hook_menu.

So we’re going to come out with documentation for hook_menu for Drupal 7 and just like last time we’re going to go ahead and grab a copy of … an example of hook_menu to get it started and if you also come back to hook_menu documentation you can see down a ways.

They have an example of setting up an administration configuration page or series of configuration pages with the multiple tabs. So this is important if you want to create or if you need to configure multiple different types of things inside one module. We’re only going to care about this first one here because we don’t need multiple administration pages in our example, we’re going to change the Hook part to cron_monitor which is the name of our module, we’re going to create the URL at admin/config/cron_monitor which of course should match up with this.
The title is going to be Cron Monitor Settings, we’re going to give it a Page Callback and in this example we’re going to be creating an administration form. The Page Callback for that is drupal_get_form and you can read about that here in the API documentation. It basically takes a form ID as the parameter and it will go ahead and it will give you that form.

So you can read about that on the api.drupal.org site and we need to pass in the form ID or the function name for that form as an argument, we can call this whatever we want; I’m going to call it Cron Monitor Admin Form and then we also need to give it an Access Argument.

In this case we’re going to create our own permission called Administer Cron Monitor. So in order to create our own permission just like we did in a previous episode of Daily Dose of Drupal we look up hook_permission, we can come down here and just copy this code over, replace Hook with cron_monitor.

We want this to be the same as what we listed down here below so Administer Cron Monitor, give it a title and we can give it a description Perform Administration Task for Cron Monitor. Now that we have that set up; been pretty basic so far, nothing really new but this is where it get’s a little interesting.
For now we’re going to create our form function and this is going to be pulled right here from the argument that we’re passing in to Drupal Get Form. In the first parameter it’s going to be a Form Variable and the second parameter is going to be form_state and the form_state is always going to be passed by reference you want to make sure that that is there and your Form Variable is going to be pass into that so that’s where you can add your Form Items.

We’re going to … at the end of this; Return system_settings_form and pass in our Form Variable and I’ll go through what some of this is going to mean. The first thing is the Drupal Form API; if you’re not familiar with it and you want to learn to build Drupal modules you will want to take a look at the Form API Quick Start Guide for creating forms and also the Form API Reference Guide which is probably something you’ll either should keep handy or bookmark or maybe even memorize it … I don’t know if I go that far but you get the picture.

It’s very important and it will help you anytime you need to build Forms, Alter Forms inside your Drupal module. So the first thing that we’re going to do is in our Administration Form we want two things; we want a checkbox to either turn the monitoring on or off and we also want the message that can be sent with each e-mail that’s going to get triggered, we’re going to create two Form Fields for that; the first one is going to be the Checkbox and the next one is going to be a Text area.

Because it’s an administration settings page we’re going to make use of the Drupal Variables table so there are few variable functions that will write and read information from that Drupal Variables Database Table. The first thing we’re going to do is click on checkbox here; it’s going to give you a little example of a Checkbox Form Item. Go ahead and copy that in just to give us a good starting point, here we give it a name and this should … in an Admin Form corresponds to what you want to call your Variable. We’re going to call your Variable cron_monitor_enable.
It’s a checkbox and we want the title to be Enable Cron Monitor, we also need to now add a default value and this is where the variable Table and Variable functions are going to come in. We do a variable_get which you can read the documentation right here, it’s going to return a Variable and we go ahead and do cron_monitor_enable because that’s what we want to call our Variable, this is how it’s going to be stored in the Variable’s table and next we give it a default as you can see here.

This is what the variable is going to default … it’s the default value that use a variable has never been set so this is brand new. We want to default this to 0 which is going to be disabled, we could default it to one which would default it to enabled but in this case we’ll default it to 0. And the reason we … the system_settings_form; let’s take a look at that; System Settings Form is great for Administration Forms, it goes ahead and it adds a default buttons to a form, it sets it’s prefix and it does … a lot of the standard stuff that you’d have to do on a typical Drupal Form. In this case it’s an Administration Form, it’s relatively straight forward.

All we want to do is when you click the Save button we wanted to go to this variable, that’s in the Variable’s table and write out the value depending on if we check the box or we don’t check the box. The next time you refresh the Form page it’s going to load the default value. So if everything goes through it and it’s set then it’s going to go ahead and pull out the current state of that checkbox, so we’ll save this, we’ll come to our test site now, click on the module’s page and search for Cron Monitor, you can see that it’s down here; notice that there’s nothing here for operations, has our description, everything looks good, we’re going to save this.

Now if you come back to Cron Monitor you can see there’s the Permission’s page and the Configure option and this is Configure option is courtesy of this line that we put in our Info file so that’s why that is important to just make it easy to get to the Administration page, you’ll notice we now have a checkbox, notice how it defaults to Unchecked which is 0, if we check it then hit Save; it says the Configuration Options have been saved and now notice that it’s checked.

I can come back to this page and refresh and it’s still going to be check so it’s perfect. We’re almost done; the only thing that we’re going to do left … the only thing we have left to is we’re going to go ahead and add a Text area and do the same thing; as you can see we have a Text area here; this is an example, we’re just going to pull through the same as we did before, we’ll drop this in right after our enable checkbox here, you got to do a little bit of clean up and we’re not going to need this longer descriptions so we’ll go ahead and bring that down and the default value is of course going to change.

So let’s start with what we’re going to save this as a Variable. We’re going to save this Cron Monitor … it’s a good rule of thumb to use the module name of your module in the Variable and the actual Variable name.

So we’re going to do cron_monitor_email_text or it could be whatever we want. Type as a Text area and then we have to set our default value which we’re going to take the same idea from up here and apply it down here, we’re going to change this to our variable name which is e-mail text and instead of defaulting to 0 we’re going to default it to an empty string, and go ahead and save this, if we come back to our administration page you’ll see we now have a text area, has our title on it, has our description, notice there’s nothing in here by default, we enter some text here, hit Save and you’ll notice that the text is still there and that’s it, we now have the Administration Form on our Drupal site that is setting variables in the Drupal Variable Database Table and if you have the ability to look at the database I urge you to do that, look at how these values are stored, they’re stored in a serialized PHP Variable.

So it’s a little bit different, it’s going to look a little odd when the first time you look at it but it’s a good idea to just to take a look at how these … how your actions in code actually affect the Database. So that’s it for this time, next time we’ll cover hook_cron and how to send e-mail from your Drupal module, until next time, thanks for watching the Daily Dose of Drupal.