Drupal 7 hook_theme usage and example implementaion

The hook "hook_theme" enables individual modules to provide theme hooks. The function that implements this hook  returns an associative array with keys of the array representing  the names of the theme hooks and the values(again an array) containing the information about the theme hook. Each information array must contain either a 'variables' element or a 'render element' element, but not both. In this tutorial I will show an example module that implements this hook and provides two theme hooks one using "variables" and another using "render element". For more details on information array visit the page hook_theme .

Module code:  "tghooks.module"


<?php
/**
 * Implement hook_menu().
 */

function tghooks_menu(){

	$items['tg_search_form'] = array(
		'page callback'   => 'drupal_get_form',
		'page arguments'  => array('tg_custom_search_form'),
		'access callback' => TRUE,
	);

	$items['tg_custom_block'] = array(
		'page callback'   => 'tg_custom_block',
		'access callback' => TRUE,
	);

	return $items;
}

// implementing hook_theme.
// Two hooks are provided one using "render element" another using "variables".

function tghooks_theme(){
	return array( 
              'tg_custom_search_form' => array('render element' => 'form'),
		      'tg_custom_block' => array('variables' => array()),
	);
}

function tg_custom_search_form($form, &$form_state){
  $form['name'] = array(
    '#type' => 'textfield', //you can find a list of available types in the form api
    '#title' => 'Name',
    '#size' => 15,
    '#maxlength' => 5,
    '#required' => TRUE, //make this field required 
  );
  $form['age'] = array(
    '#type' => 'textfield', //you can find a list of available types in the form api
    '#title' => 'Age',
    '#size' => 15,
    '#maxlength' => 5,
    '#required' => TRUE, //make this field required 
  );
  $form['gender'] = array(
    '#type' => 'textfield', //you can find a list of available types in the form api
    '#title' => 'Gender',
    '#size' => 15,
    '#maxlength' => 5,
    '#required' => TRUE, //make this field required 
  );

  return $form;
}

function tg_custom_block() {
  return theme('tg_custom_block', array('item1' => 'Android', 'item2' => 'Drupal7', 'item3' => 'Drupal8'));
}



function theme_tg_custom_search_form($variables){
  $form = $variables['form'];
  $output = '<h1>This is the custom Form </h1>' . drupal_render_children($form);
  return $output;
}

function theme_tg_custom_block($variables) {
  $output = '<div>';
  $output .= '<ul>';
  $output .= '<li>'.$variables['item1'].'</li>';
  $output .= '<li>'.$variables['item2'].'</li>';
  $output .= '<li>'.$variables['item3'].'</li>';
  $output .= '</ul>';
  $output .= '</div>';
  return $output;
}

Code Details:

After enabling this module when you visit the page (?q=tg_search_form), the Drupal core performs the following tasks as part of the page content creation.

  1. It invokes "drupla_get_form" with $form_id set to "tg_custom_search_form". By default the Drupal system will look for a function with the same name as the form ID. In our case that function is a part of the module code  shown above.
  2. The function "tg_custom_search_form" constructs and returns a form in the form of a renderable array.
  3. The Drupal system performs further processing on the renderable array, most importantly it sets the "#theme" attribute  to "form ID" (i.e to "tg_custom_search_form") and populates the page content with this renderbale array.
  4. Inside "page.tpl.php" when we perform rendering on content (render($page['content')) the theme hook "theme_tg_custom_search_form" (a function implemented in the module shown above) gets invoked to return the "html" for the page content.

When you implement a theme hook with element "render element" in it's information array, the hook receives the data in the form of a renderable array  and performs rendering on  it using simple render functions. Also the hook can append/prepend some custom content to the rendered html.

In the second case , i.e when you visit the page (?q=tg_custom_block), the Drupal core performs the following tasks as part of the page content creation.

  1.  It invokes the function "tg_custom_block" to set the page content.
  2.  A call is made to the function "theme" with hook name set to "tg_custom_block".
  3.  Which in turn invokes the function "theme_tg_custom_block" to return the actual html for the page content.

When you implement a theme hook with element "variables" in it's information array, the hook receives the data in the form of a simple array that will be  processed to generate target html.
 

Results

When you visit the page "?q=tg_search_form" you should see page content set to the form shown bellow.

When you visit the page "?q=tg_custom_block" you should see page content set to the list shown bellow.