Tags: Drupal ModulesDrupalCMSOpensourceDrupal PlanetIntroduction

For the past five or six months, I've been itching to write a Drupal module. It seems to me to be the final step in attaining that Drupal nirvana, and you gain instant street cred as well at the monthly meet-ups. I've heard it also can up your certified to rock score too, since you get commits added to your history.

Thinking back to my early days learning Drupal, the mythical, magical, modules were those things you didn't mess with. You downloaded them, installed them, and usually they worked. The module developers were the big kids on the playground. The seniors in high school, so to speak. But, because of Drupal's awesome community, they weren't the bullies.

The CacheFlusher isn't my first module. I got my feet wet updating the Apture Module to Drupal 7, with some guidance from @ultimike (Mike Anello). Yeah, he is certifiied to rock a 7.

I learned a few things while I was updating the Apture Module, that made it a bit easier to write my own module from scratch.

What you need

Fist of all, you don't necessarily need to be a PHP guru to write a module. In fact, I am very far from it. You will need some basic, general understanding of programming flow though. I had dabbled in python before, and have been learning some PHP along the way too, but it definitely is not a pre-requisite. You just need a basic understanding of what code does.

You will need three things to write a module:

1. A Drupal Installation
2. A Text-Editor
3. An internet connection (For references to the API)

You can set up a development environment on your local computer using WAMP if you are running windows, or MAMP if you are on the MAC. Linux folks, you most likely already have everything you need. Just make sure you are running PHP5.

Check out these getting started guides to help you get WAMP or MAMP if you don't already:

MAMP: http://www.mamp.info/en/documentation/index.html
WAMP: http://www.wampserver.com/en/

For an even easier setup with no installation, go to webenabled.com and sign up for a free account, although transferring files back and forth for testing might become tedious.

There are numerous text-editors available. A lot are free. Your operating system probably includes one. TextWrangler is my personal favorite for the mac, but you really need to try different ones to decide which one you really like. Windows users can use Notepad++. Some offer syntax and code completion as well as a lot of other nifty features.

Let's Get Started

The Modules Directory

First, if you have installed any contributed modules before, and you have ever peaked inside your sites/all/modules directory, you will see that there are a bunch of other directories with names like “views", “mollom" and “colorbox". These folders contain the code for each contributed module installed on your site. You will also notice that the names generally coincide with the name of the module. This is important, as we will soon learn.

Open one of the folders and look inside. I will promise you that you will see at least two files there along with possibly a README. One has a .info extension and the other has a .module extension, preceded by the exact same name of the parent directory.

This is how Drupal keeps track of the contributed modules available when you visit admin/modules

If you plan on sharing your modules with the rest of the world, (really why wouldn't you), go set up git on drupal.org using the Git Instructions as your guide.

The .info File

After following the instructions, cd into your new module directory. You should see a .info file with your repository name already there. Drupal does this for you when you create your sandbox, and you just cloned it into your directory.

Open that .info file. This is kind of the table of contents for your module and contains some standard entries that every module should have.

What you will see is: name = yourmodulesname

This tells Drupal what the name of your module is. This is also where the information contained in the module overview page at admin/modules comes from.

We should add a few things before we are done here.

Hit enter and start a new line. Add description = a description about what your module does.

This creates the description for your module on the module overview page.

Our next entry is will tell Drupal where to categorize our module. When you view the module overview page at admin/modules you will see some headings for subcategories like “Core", “Services", and “Taxonomy". This helps to keep your modules organized.

Add a new line and type package = administration

The last entry we will need is important so that Drupal knows what version of Drupal this module was created for. Add core = 7.x This tells Drupal that your module is for Drupal 7.

If you plan on sharing your module, don't add a “version" entry. Drupal will automatically do this for you when it is packaged.
Make a new line, and add your final entry, files[] = yourmoudlename.module

This directs Drupal to your actual module code so that it can run.

Save your .info file.

What the .info File will Finally Look Like

Here is what the final version of the CacheFlusher module's .info file looks like:

name = CacheFlusher<br>description = Adds a quick way to flush your cache with a button on the admin toolbar.<br>package = "Administration"<br>core = 7.x<p>files[] = cacheflusher.module</p>
The .module File

If you start up your Drupal installation and go to admin/modules, you will see a new entry for your module on the module administration page. It won't actually do anything yet though.

Next, you need to add your .module file. This is where all of the work gets done.

What are Drupal Modules?

Drupal modules are basically a series of functions, with a majority of them being function calls to Drupal functions. The documentation for every function available to Drupal can be found at api.drupal.org. This is your resource for finding out what each function does and how to use it.

As a newcomer, I found it to be lacking in examples. Sometimes it can be impossible to figure out what the function actually does. Instead of complaining in a comment or forum posting, I added a few entries providing some examples.

After my frustration, I discovered the Examples Project that provides an excellent group of modules that do just what the project name implies--provide example modules for developers that give working code examples of what some of the popular functions actually do. It is an excellent resource and you should add it to your bookmarks toolbar because you will probably refer to it quite often.

I found the best thing to do is to find a module that is very simple, and look through the code. If you are adding a menu entry, find a module that does the same thing and look through the .module file.

Often you might find .inc files. These point to additional code that wasn't included in the .module file. These will be noted in the .module file though with a filename.inc. This references those additional files.

Another good resource is your Drupal installation itself. By browsing to the core modules folder found at /modules, you can search for the function you are looking for by using spotlight if you are using a mac, or search for windows or locate from your nix terminal.

This can often shed some light on the function or at least reveal what function to implement to perform a certain task.

View Your Module in Action

Now that you have your .info file and your directory. You are ready to create your .module file and spin some code up. You can visit your Modules page in your Drupal installation now, and see that you now have a new entry for your own module!

The second part of this article will go through the creation of your actual .module file.

A great resource for continuing your module development education is the Drupal 7 Module Development book.