Writing Drupal Modules

Set-up and Common Code

*.info file

*.module file

Help Pages

Standard/Basic

You can create your own custom help page by putting this inside yourModule.module

/**
 * Implements hook_help().
 */
function yodesa_help($path, $arg) {
	switch ($path) {
		case 'admin/help#yodesa': {
			$helpMsg = 'Help for this module is displayed using the ' . l("Advanced Help", "https://www.drupal.org/project/advanced_help") . ' module. If you have Advanced Help installed, then you can read the <a href="/admin/advanced_help/yodesa">help document</a>.';
			return $helpMsg;
			break;
		}
	}
}

Advanced Help

advanced_help is a Contributed Module that can display help files using the same theme as your site. It also is much more useful when you have a lot of documentation because you can set-up a hierarchy of pages and write the documentation is regular HTML. After installing Advanced Help, be sure to set the permissions so you can view the help files.

Quick and Dirty Option

Just shove a README.txt or README.md file in the root of your module.

Full Capabilities Option

To create an Advanced Help page:

Create a folder in your module called “help”.

Create a file in there called moduleName.help.ini. Its content would be similar to:

[installation]
title = Installation and Configuration
weight = 1

[features]
title = Purpose and Features of this Module
weight = 2

For each help page (Step 2’s example above has two help pages) listed in square brackets create a corresponding file. In this example, you need to create:
1. installation.html
2. features.html
Build out your help files. These should be HTML snippets, not a fully formed page. In other words, do not use the <html>, <head>, or <body> tags.

Permissions

This hook can supply permissions that the module defines, so that they can be selected on the user permissions page and used to grant or restrict access to actions the module performs.

/**
 * Implements hook_permission()
 */
function yodesa_permission() {
	return array(
		'use-yodesa' => array(
			'title' => t('Can use yodesa form'),
			'description' => t('Is allowed to fill-out the Yodesa form and receive feedback.')
		)
	);
}

Where to Put Your Main Logic

For me, the trickiest part of learning Drupal is where to put your code so it is 1) called, and 2) called at the right time. That is what the hook system is for.

Called on every html page

function myModule_preprocess_html() {

Called on every page that uses template `page.tpl.php` (regardless of current theme)

If you want a piece of code to run, regardless of the current theme, then it must be inside a module. Most (all?) themes use a template file called page.tpl.php so you can create a function in your module’s myModule.module file named:

function myModule_preprocess_page() {

Called on every page that uses template `page.tpl.php` (specific theme)

Similar to above, but place this function definition in your theme’s template.php file:

function myTheme_preprocess_page() {

Note: I have not actually tested this.

API

In the function names below where you see the italicized word hook, that will need to be replaced with your module or theme’s name (generally). If there are dashes in the name, then convert those to underscores. For example, if your module name is “guido-rocks” and you are implementing hook_menu(), then you should define it as guido_rocks_menu().

Common Hooks

hook_node_info(): Creates a new Content type
hook_form(): Used to show a form for node creation/editing
hook_help(): Display online help for a custom module
hook_permission(): Add new permission checkboxes to the admin/people/permissions page

hook_menu()

Implementing the hook_menu() is the primary way (in Drupal 7; this changed in Drupal 8) to:

associate functionality with a URL (callback mapping, think of this as a router)
secure the menu with permissions
customize the menu.

You need to return an array of menu items where each menu item is an associative array. Each menu item is also an array. The example below shows only a small subset of the available properties. See the API documentation for the complete list.

/**
 * Implements hook_menu().
 */
function yodesa_menu() {
	$items = array();
	$items['youth-dev-self-assess'] = array(         //The key is the URL (first part of callback mapping)
		'page callback' => 'yodesa',                 //function to call (second part of callback mapping)

		'access callback' => 'custom_verification'   //security: leave blank to use user_access()
		'access arguments' => array('use-yodesa'),   //security: an array of arguments for 'access callback'

		'title' => 'Yodesa',                         //customize menu (required)
		'description' => 'Launch the Yodesa form'
		'type' => MENU_SUGGESTED_ITEM,
		'menu_name' => 'My menu name'                //optional. Leave blank to include this in the Navigation menu.
	);

	return $items;
}

hook_theme()

This function will tell Drupal about the association between a Render Array (set of data) and theme implementation (how to generated the final HTML).

Common Drupal Functions

url() Makes a safe URL

base_path() Returns the base location of the Drupal install. It will always include the trailing slash. In most cases, this function will always return just a “/” because most installs have Drupal installed to a top level directory of the webroot. Note: Do not combine with path_to_theme() because that function apparently already takes into account the base.

path_to_theme() Returns the directory of the current theme. Example:

<img src="<?php echo url(path_to_theme() . '/img/myPic.jpg'); ?> alt="">