Last updated June 4, 2011. Created on January 5, 2008.
Edited by USGolfers, hermes_costell, edugom, aspilicious. Log in to edit this page.

Main topic described: Let Drupal know the module exists
Drupal hook described: hook_help
In addition to the modulename.module file, all modules must have a modulename.info file, which contains meta information about the module.

The general format is:

name = Module name
description = A description of what your module does.
core = 6.x

For this example, the file would be named "onthisdate.info". Without this file, the module will not show up in the module listing. For this example, it could contain the following:

name = On this date
description = A block module that lists links to content created one week ago.
core = 6.x

Add the source above to a file named to onthisdate.info and save it into the module's directory at sites/all/modules/onthisdate.

Note: If you copy and paste this code block, ensure that the description data does not contain a line break (turn off word-wrap on your text-editor to be sure). Otherwise, the .info file will not parse correctly.

Info File Details

name (Required)
The displayed name of your module. It should follow the Drupal 6 capitalization standard: only the first letter of the first word is capitalized ("Example module", not "example module" or "Example Module").
name = On this date
description (Required)
A short, preferably one line description that will tell the administrator what this module does on the module administration page. Remember, overly long descriptions can make this page difficult to work with, so please try to be concise. This field is limited to 255 characters.

description = A block module that lists links to content such as blog entries or forum discussions that were created one week ago.

Note that special characters in this description must be substituted with the HTML entity values. For example, use description = This is my "crazy@email.com" email address instead of description = This is my "crazy@email.com" email address
If the description has single quotes or apostrophes in it then you can simply put the entire string inside double quotes. For example, description = "Please don't use this unless you know what you are doing."

core (Required)
As of version 6.x, Drupal core will refuse to enable or run modules that aren't explicitly written for the right version of core. The .info file must specify which Drupal core compatiblity any module or theme has been ported to. This is accomplished by means of the new core attribute in the .info files.
core = 6.x

Note: the drupal.org packaging script automatically sets this value based on the Drupal core compatibility setting on each release node, so users downloading packaged releases from drupal.org will always get the right thing. However, for sites that deploy Drupal directly from git, it helps if this value is added to the .info files for the module. This is also a good way to indicate to users of each module what version of core the HEAD of git is compatibile with at any given time.

dependencies (Optional)
There are a couple of extra options that may appear in the .info file, one of which are module dependencies. If a module requires another module to be enabled, list each module (filename) required in the following syntax:
dependencies[] = taxonomy
dependencies[] = comment

For the example module, these don't apply and we will simply omit them. If dependencies are assigned for a module, Drupal will not allow it to be activated until the required dependencies are met.

package (Optional)
If a module has a package string, on the admin/build/modules page it will be listed with other modules with the same category. If a package string is not assigned, it will simply be listed under 'Other'. Not assigning a package for your module is perfectly ok; in general packages are best used for modules that are distributed together or are meant to be used together. If in doubt, leave this field blank.
package = "Your arbitrary grouping string"

Suggested examples of appropriate items for the package field:

  • Audio
  • Bot
  • CCK
  • Chat
  • E-Commerce
  • Event
  • Feed Parser
  • Organic groups
  • Station
  • Video
  • Views
  • Voting (if it uses/requires VotingAPI)

For more information on ini file formatting, see the PHP.net parse_ini_file documentation.

Help Hook - a Module File entry

We can also provide help and additional information about our module by implementing Drupal's hook_help(). Because of the use of the .info file described above, this hook is now optional. However, it is a good idea to implement it. To implement any hook in Drupal, replace "hook" in the hook name with your module's short name, and create a function in the .module file with that name. So, to implement hook_help() in our example module, we create a function called onthisdate_help() in the onthisdate.module file:


function onthisdate_help($path, $arg) {

}

The $path parameter provides context for the help: where in Drupal or the module the user is when they are accessing help. The recommended way to process this variable is with a switch statement. This code pattern is common in Drupal modules. Here is a sample implementation of this function:

/**
 * Display help and module information
 * @param path which path of the site we're displaying help
 * @param arg array that holds the current path as would be returned from arg() function
 * @return help text for the path
 */
function onthisdate_help($path, $arg) {
  $output = '';  //declare your output variable
  switch ($path) {
    case "admin/help#onthisdate":
      $output = '

'. t("Displays links to nodes created on this date") .'

'; break; } return $output; } // function onthisdate_help

(note the closing ?> should not appear in your code)

The admin/help#modulename case is used by Drupal core to link from the main help page (/admin/help or ?q=admin/help). You will eventually want to add more text to provide a better help message to the user.

See Also

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

tmsimont’s picture

I wasted quite a bit of time trying to get my .info file to be recognized to discover that although Notepad++ was showing me line breaks, opening the .info file with Notepad showed strange characters instead of line breaks, which was how drupal saw it, too.

I'd recommend using the most basic and boring text editor you can possibly find to create the .info file to avoid this trouble.

ksweet’s picture

For future readers:

If you're using Notepad++ and realize you have this problem, don't fear! Go to Edit -> EOL Conversion -> Windows Format, and voila: all of your line breaks are CRLF. You can check by going to View -> Show Symbol -> Show End of Line.

executex’s picture

Sometimes when you copy and paste a sample module code from drupal.org into notepad++ when creating a .info file, it turns into "CR" line breaks. However, if you simply open a new document and start typing, it creates "CR" "LR" line breaks. THAT is what you need. If you have "CR" only linebreaks, then your module will not show up.

You can tell by clicking view > "Show Symbol" > "End of Line" , or you can open the same document in regular Notepad and you'll see it look like one long line of words. With [][] in place of end of lines.

Pav’s picture

My module wasn't showing either. Following your instructions I checked my .info file and .module both contained CRLR. I changed the file so it only contains the LR now and shows up fine. Also the CRLR in .module file was causing it to "white screen" in the later stage of the tutorial when enabling the module. Changing that to LR only solved the issue.

uuf6429’s picture

For what it's worth, it's actually called "CR LF" - carriage return + line feed.

gozigzag’s picture

I'm using Notepad ++ 5.6.8 here. Seems like most modules I see use the UNIX End of Line format (just LF). You can convert any document to this by selecting Edit > EOL Conversion > UNIX Format.

zilverdistel’s picture

When you use quotes around the description, there appears to be no problem with the newlines

E.g.:

description = "A block module that lists links to content created 
one week ago"
end0rama’s picture

I think that for people who approch module development these lines can be confusing...

$output = '';  //declare your output variable
    $output = '

'. t("Displays links to nodes created on this date") .'

';

Infact $output in the second line is = to his content, while i think would be clearer using .= ( because $output is already declared on first line and string concatenation seems to me the best way to do that ).
This way is easier to add more line to help content avoiding the risk of mistakes...IMHO

hermes_costell’s picture

It should be mentioned that you will need to also have a .module file present (at least I DO ... on 6.x).

Therefore if your module is named "my_module" then you will need to have both:

my_module/my_module.info and
my_module/my_module.module

present before your module will be recognized by Drupal.

This may be taken for granted by many - but nowhere in the text of the tutorial is this mentioned as of this writing, which is bound to have many people trying to learn - upload only their .info file and see nothing on the /admin/build/modules/list page, bringing frustration.

Also your .module file apparently only needs to include

<?php

in order to suffice for Drupal to include it in the modules list.

rblindore’s picture

Even after checking so many time the new module is not getting listed in the module list of the Drupal. Please help. What mistake I may have done?

mpoplin’s picture

I'd like to think that people making modules for Drupal - not a trivial task - can figure out that a .module file needs to be present for a module to be recognized. That's just me though.

hermes_costell’s picture

May I suggest that neglecting to state the trivial is a bad direction to take when making a manual for beginners?

alphadog’s picture

I am very new to developing Drupal modules so my comment may as well be inappropriate. In such case please accept my apologies in advance.

Is there a specific reason why you recommend using switch for verifying the path?

Granted that switch is a lot more effective(about twice more) at matching a value in a large set of elements then when using if-elseif, I think in this case you still evaluate a single condition and cannot see how the 2 statements would be different in terms of performance.

I always find that a function structured like below is easier to read as it uses less nested blocks of code:

function onthisdate_help($path, $arg) 
{
    $output = '';  //declare your output variable
    
    //verify exit condition(s)
    if (strcmp($path, "admin/help#onthisdate") != 0) return $output;

    //function execution if exit condition was not met.
    $output = '<p>'.  t("Displays links to nodes created on this date") .'</p>';
    return $output;
} // function onthisdate_help

However, if the switch statement is required to satisfy a certain requirement or avoid a known pitfall that may need to be documented here. Thanks.

Timon Davis’s picture

It seems to me that the switch is used here because, as your list of possible paths grows, the switch block is much easier to manage and read than a series of 'else if' control statements.

rrmeo’s picture

This is a great tip, and is still a necessary workaround (as of Feb 2012)