Module Development: Drupal 7 Theme functions and templates

By shane
Tue, 2012-10-30 22:00
Daily Dose of Drupal Episode #40

Share with Others

Learn how to add theme functions and template files to you Drupal 7 module. This episode builds upon the my_example module created in the last episode and adds in a hook_theme implementation along with simple examples on how to create a theme function and template file in your module.

In this episode you will learn:

  • How to add a hook_theme implementation to you your Drupal 7 module
  • How to add a theme function in your Drupal 7 module
  • How to create a theme template file (.tpl.php file) in your Drupal 7 module

Welcome to another episode of the Daily Dose of Drupal, we’re on Episode Number 40. If you watched the previous episode you’ll notice we did a little bit on module development and talked about Drupal Renderable Arrays or Render Arrays and we went over that in Drupal 7 and we came up with this module that you see here.
It has a Hook Menu Implementation, has My Page – HTML page and a MY Page – Renderable page. The first one just output straight HTML, similar to how … at least I used to do it a lot in Drupal 6 and the other one uses the new Render Arrays of Drupal 7 and shows a quick examples of how to do that.

So you can watch that episode if you want to learn more about that, as always I am Shane @smthomas3 on Twitter so go ahead and follow me there, also go to, sign up for the newsletter if you are not signed up already.
Alright so today we’re going to go over Hook Theme and how you can use Hook Theme in your module and you … we’re going to show an example how to build a theme function in your module and a simple example of how to use a template file within your module and if you’re not familiar with the very basics of Drupal Theming you may need to come to and read some of the documentations but we’ll get through most of it right now.

So we’ll go ahead and come back to our site and you’ll notice we have a pretty basic Drupal 7 site, we have our module installed so we’re good to go on that end and we will go ahead and get started by creating a Hook Theme Implementation. So go ahead and add our comment here and we’re going to go ahead and grab this code here as just a very rough starter, we’re going to be getting most of this out but it’s a good placeholder, I’m just on the Hook Theme documentation on and replace hook with the name of your module and in this case our module is called My Example and I’m going to go ahead and get rid of all of these bottom ones here except for these two and we’re going to create two different examples here; the first one we’re going to call My_Function, we’re going to have a variable called Text 1 and we’ll have a variable called Text 2.
Like I said; this is going to be a very simple example to show you how a theme function and a theme template file can be used in a module and this can of course be called whatever you want, I generally start mine with the name of the module first, it’s not necessarily required but it’s usually a good practice to follow. So we’re going to get this to be basically identical for the most part.

Now the big thing we’re going to add here is we’re going to add template and we’re going to go ahead and give our template file a name. So I’m going to call My_Example_Template and this can be anything you want that you want to name your template file, if you’ve come to the Hook Theme Documentation you can see all of the different … various keys that you can add to this array that you return.
So variables defines any variables that are going to be used in your Function or Template and this template value is the name of the actual template so you can find that here and it says if it’s specified this theme implementation is a template and this is the template file without an extension. So do not put the .tpl, .php on the file because it will be added automatically.

The next step here is we’re going to come down to this page which …or this callback function which is called … when you go to My Page – HTML and we’re going to revamp this a little bit here; we’re going to go ahead and use a define or Text 1 and we’re going to return theme. So this is actually going to be calling our theme function, we’re going to call My Example function which we haven’t defined yet, we’ll do it here in a second and we give it an array of the variables that we want to pass in.

So for Text 1 we’re going to go ahead and pass in our variable and as another example for Text 2 we’ll go ahead and just add a static string and you should be using the T Function that Drupal provides but we’ll just hurry up and freeze to this. One thing to note is like I said before, we haven’t define this yet and this isn’t really a realistic use case, if you’re going to do this, I mean, there’s probably easier … you couldn’t go ahead and call the theme function from the page callback but what I’m assuming here is in this step, you’re going to maybe be pulling values from the database doing some processing where you actually needed to populate or pull out what these values are going to be.

In this example we’re just using some static text but you’ll get the idea. The next step is to actually go ahead and define this Theme Function; I’m going to come down to the bottom and any Theme Function that you’ve define in your module always starts with Theme_ and after you’d enter in the Theme_ you’re going to pull out the name of the actual theme function and this is just the default that you can actually … in Hook Theme you can define the function name but if you do not it will go ahead and name it Theme_ whatever the theme name is, so we got Theme_My_Example_Function and it’s going to take one variable, we’re going to Variables.

So the next step is we’re going to go ahead and add some output here that we’re going to be printing to the screen, we’re going to keep it relatively simple here and your variables are going to be passed in inside of that Variables Array. So you can see I’m referencing Text 1 which is going to be passed in this value here, Text 2 will be this value here. You can see this is somewhat similar to how it was done before and the reason you want or one of the reasons you’re going to want to use Theme Functions versus just printing out the HTML here is by adding a Theme Function you’re allowing theme developer to override this output in their template.php file.

So on the actual theme that means one theme may define it to be output one way where another theme could of course output it a completely different way using these same variables that you’re passing in. So you notice I’ve add an H2 tag with Text 1 in it, add a paragraph tag with Text 2 and then you have to return the output. So there is that one, we’re going to go ahead and take a look at that first, it’s important now … anytime after you declare a new theme functions or declare a Hook Theme Implementation you need to go ahead and clear cache so I’m going to hop into Drush and go ahead and run Drush, so you see I clear the cache, I probably need to clear out the theme registry but I’m going to clear everything just to be sure and I’m going to come over here and go to My Page – HTML.

You’ll notice very simple, has this as Text 1, Text 2, if I examine the HTML of it, just an H2 and the paragraph tag right there, pretty simple. Next step if of course the Template File approach; so we’re going to go ahead and revamp this a little bit, we’re going to get rid of this section and we are going to declare a variable at the very beginning, as I said before this would most likely be pulling out some values, for the output we’re going to go ahead and just create an array with a theme function, in this case it’s going to call the Hook Theme Implementation of My Example template and the type in this case we’re going to go ahead and do mark-up and we are then going to add our variables and this is just going to go ahead and add our variables in, just like that.

And what this is going to do in this example is it’s going to call our Theme template and generate some mark-up that’s going to then be displayed on the page. This is just one way of doing it, there’s a whole bunch of different ways that you can … in theory you can layer a whole bunch of different ones like using the Renderable Arrays to their fullest extent which is probably what you should be doing but if you just want a simple template to take over your entire page this would be one approach to do that.

It may not be using the Renderable Arrays to their full capabilities but at least gives you an idea of how that’s going to work. The next step is going to be actually create our template as shows here, it should be My_Example_Template and we have to add the .tpl.php extension and I just drop this template that I created into the Modules folder so it’s exactly in the same level as myexample.module and file.

So just sitting in there with that and edit the same thing, just add a little php with a comment and I add an H3 tag with php print statement to Text 1, as you can see it’s … the variable get’s pulled out and it becomes it’s own variable, so it’s $Text 1, $Text 2, I added a class here so we’re going to be able to differentiate between the other page, I’m going to clear the cache for good luck, hop back over here and go to My Page – Redererable, as you can see the title has changed, everything else looks about the same, it’s now an H3 with our class on it, you can also see there’s a paragraph tag with Text 2.

So that’s just one of many ways to use Templates files, there’s many other uses than just that and as I shown before there’s also an example of how to create a theme function. Both this Template File and this Theme Function can now be overwritten in your Theme. So for instance if you created this module, gave it to someone else, they can copy this Template File, put it in their theme in either the base theme or the actual theme directory or theme templates directory and they go ahead and modify this HTML and are able to them override your Theme Functions.

That’s it for this time, next time we’ll be talking about a whole another topic. As always; follow me on Twitter @smthomas3 and we will see you next time. Thanks for watching.