02. Telling Drupal about your module
Main topic described: Let Drupal know your module exists
Drupal hook described: hook_help
In Drupal 5.x the basic information about your module, its name and description, is no longer provided by hook_help. Instead, all modules now need to have a modulename.info file, containing meta information about the module (for details see Writing .info files (Drupal 5.x)). For our example, "onthisdate.info'.
The general format is:
; $Id$
name = Module Name
description = "A description of what your module does."Without this file, your module will not show up in the module listing!.
for our example, it could contain the following:
; $Id$
name = On this date
description = "A block module that lists links to content such as blog entries or forum discussions that were created one week ago."Add the source above to a file named to onthisdate.info before saving in your module's directory at sites/all/modules/onthisdate.
There are also two optional lines that may appear in the .info file:
dependencies = module1 module2 module3
package = "Your arbitrary grouping string"For our example module, these don't apply and we will simply omit them. If you assign dependencies for your module, Drupal will not allow it to be activated until the required dependencies are met. Note, however, that Drupal does not (at the moment) check for added dependencies when your module is updated (if you module is already active), so be careful to document newly added dependencies clearly.
If you assign a package string for your module, on the admin/build/modules page it will be listed with other modules with the same category. If you do not assign one, it will simply be listed as 'Other'. Not assigning a package for your module is normal; packages are only used for modules that are distributed together or are meant to be used together. See the .info handbook page for more detail. If you have any doubt, leave this field blank.
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)
The files use the ini format and can include a ; $Id$ to have CVS insert the file ID information.
For more information on ini file formatting, see the PHP.net parse_ini_file documentation.
We can also provide help and additional information about our module. Because of the use of the .info file described above, this hook is now optional. However, it is a good idea to implement it. The hook name for this function is 'help', so start with the onthisdate_help function:
<?php
function onthisdate_help($section='') {
}
?>The $section variable provides context for the help: where in Drupal or the module are we looking for help. The recommended way to process this variable is with a switch statement. You'll see this code pattern in other modules.
<?php
/**
* Display help and module information
* @param section which section of the site we're displaying help
* @return help text for section
*/
function onthisdate_help($section='') {
$output = '';
switch ($section) {
case "admin/help#onthisdate":
$output = '<p>'. t("Displays links to nodes created on this date"). '</p>';
break;
}
return $output;
} // function onthisdate_help
?>The admin/help#modulename case is used by the Drupal core to linked 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.
More information about the help hook:
Drupal HEAD
Add the source above to a file named to onthisdate.module before saving in your Drupal installation.