Drupal Technical

[Drupal] How to create a custom template in Drupal 7?

Muhammed Junaid | | 2 min read

Most Drupal developers know about writing theme functions in Drupal 7. Likewise we can create theme templates too. However Drupal developers rarely create their own templates. Read on to know how to create a custom template in Drupal 7.

Just like in theme functions, the first step in implementing a new theme template is declaring the theme information by implementing hook_theme() for your module, if it does not exist. It is required to provide a value for the 'template' index for the entry corresponding to the theme template. Then the template file will be assumed as <template value>.tpl.php. That means we do not need to provide a .tpl.php extension for that value.

Next you have to specify the value for either 'variables' or 'render element' but not both. If your theme is going to be used by calling the theme() function directly then its better we use 'variables'. You can create renderable arrays too, so that you can provide the default values in the theme declaration itself.

Example

If I want to create a theme 'mytemplate_theme' using 'mytemplate-theme.tpl.php' template file which requires two variables $one and $two. Then my theme declaration will look like.

mymodule_theme() {
  return array(
    'mytemplate_theme' => array(
      'template' => 'mytemplate_theme',
      'variables' => array('one' => NULL, 'two' => 'Default value for two'),
     ),
  );
}

and my 'mytemplate-theme.tpl.php' is:

<p>
  One: <?php print $one; ?><br />
  Two: <?php print $two; ?>
</p>

Then if I want to call this using theme function I can call it like:

$variables =  array('one' => 'One value', 'two' => 'Two value');
$output = theme('mytemplate_theme', $variables);

Instead if I want to create a renderable array then:

$data = array(
  '#theme' => 'mytemplate_theme',
  '#one' => 'One value',
  '#two' => 'Two value',
);

On both cases if we do not provide values for $one and or $two. It will take default values from the theme declaration. In the theme declaration the default value for $one is NULL and for $two it is 'Default value for two'.

In the above example, on the template file we are expecting some variables. We can also expect a single element. Then the theme declaration will be:

mymodule_theme() {
  return array(
    'mytemplate_theme' => array(
      'template' => 'mytemplate_theme',
      'render element' => 'element',
     ),
  );
}

Now the values we pass will be packed as a single element named 'element'. So the template file should expect an element instead of variables.

<p>
  One: <?php print $element['one']; ?><br />
  Two: <?php print $element['two']; ?>
</p>

Now if I want to call this using theme function I can call it like:

$variables =  array(
  'element' => array(
    'one' => 'One value',
    'two' => 'Two value',
  ),
);
$output = theme('mytemplate_theme', $variables);

Instead if I want to create a renderable array then:

$data = array(
  '#theme' => 'mytemplate_theme',
  'one' => 'One value',
  'two' => 'Two value',
);

In this way we can easily introduce new theme templates. These templates can be overriden by theme developers if they want to changes its default rendering.

 

 

Related Topics