Check your version

This video covers a topic in Drupal 7 which may or may not be the version you're using. We're keeping this tutorial online as a courtesy to users of Drupal 7, but we consider it archived.

Introduction Advanced Theming in Drupal 7

Video loading...

  • 0:05
    Advanced Theming in Drupal 7
  • 0:06
    Introduction to Advanced Theming in Drupal 7
  • 0:07
    with Michelle Lauer
  • 0:17
    In the previous series, we discussed .info files,
  • 0:21
    which are the configuration files for your themes,
  • 0:23
    which tells Drupal that you are a theme,
  • 0:26
    what regions you have, what CSS file you have,
  • 0:29
    and what JavaScript you have.
  • 0:30
    We also discussed template files.
  • 0:33
    Those are the files ending in .tpl.php, like
  • 0:36
    your page.tpl or your node.tpl.
  • 0:40
    But in this series, we're actually going to talk about template.php.
  • 0:45
    This is the file where all of your functions live,
  • 0:48
    and we are going to discuss preprocess functions
  • 0:50
    and overriding theming functions.
  • 0:54
    So what if there isn't a variable for what
  • 0:57
    you want to do in your page.tpl or in your node.tpl?
  • 1:01
    You've already done a dump of all possible variables,
  • 1:04
    and it's just not there.
  • 1:05
    You've got something else unique and custom.
  • 1:08
    Well, I'm sure you've heard this on multiple occasions,
  • 1:10
    but you actually don't but complicated
  • 1:12
    PHP code in your .tpl files.
  • 1:15
    You put some more complicated logic in your template.php.
  • 1:21
    So we are actually going to discuss today
  • 1:23
    how to create those new variables and override existing ones.
  • 1:27
    So welcome to template.php, the theming ninja's weapon of choice.
  • 1:33
    So here, like I said, we are going to set
  • 1:35
    new variables that you will have access
  • 1:38
    to in any of your tpl.php files.
  • 1:43
    So template.php-- it's all PHP code.
  • 1:47
    There is no HTML.
  • 1:49
    It's the exact opposite of a tpl.php.
  • 1:54
    It's the place where you put extensive logic
  • 1:56
    and even sometimes write SQL queries.
  • 2:00
    By separating out all of this PHP functionality into a unique file,
  • 2:06
    you're now keeping your node.tpl and your page.tpl
  • 2:10
    files very, very clean.
  • 2:11
    It actually makes it easier for a designer
  • 2:13
    to come in and change the markup and work with the CSS
  • 2:17
    that's associated with that.
  • 2:21
    Template.php, like I said before, provides
  • 2:23
    all of the variables for you that you
  • 2:26
    have access to in your TPL files.
  • 2:29
    And also, we can go in and we can override
  • 2:31
    some of Drupal's functionality.
  • 2:33
    There are several functions, like theming a user name, that we can
  • 2:37
    go in and say Drupal does it pretty well,
  • 2:40
    but I want to do a little bit better.
  • 2:42
    I want to add another character in there,
  • 2:43
    change the markup a little bit.
  • 2:45
    And in your template.php, you can override any of those.
  • 2:50
    First thing I want to talk to you about are preprocess functions.
  • 2:55
    This is where you create new variables
  • 2:58
    or override existing variables.
  • 3:01
    The first function is commonly known as the themename_preprocess.
  • 3:08
    Now, you would replace themename with the name of your theme--
  • 3:11
    for example, bartik_preprocess.
  • 3:15
    Or you can go ahead, if you're following our tutorial,
  • 3:17
    do 960robots_preprocess.
  • 3:21
    This function gets called all the time.
  • 3:25
    It's the biggest global function.
  • 3:27
    To save on resources, you actually can go ahead and do a switch
  • 3:31
    and check and say, OK, well, if it's actually a page, let's go ahead
  • 3:35
    and call that function.
  • 3:37
    You can be even more specific.
  • 3:38
    There is themename_preprocess_hook, where that hook would be replaced
  • 3:44
    with something like page or node.
  • 3:47
    So anytime a page is loaded, your bartik_preprocess_page
  • 3:52
    will get called.
  • 3:54
    You'll notice that in both of these examples, $vars is being passed in,
  • 3:59
    and that is where all of your variables
  • 4:02
    are that then in the very end get sent to your template files.
  • 4:06
    So you can go ahead and say $vars my new variable equals
  • 4:11
    some sort of value, and that will then be available to you
  • 4:14
    in your other files.
  • 4:17
    Another thing that template.php is useful for
  • 4:20
    is overriding theme functions.
  • 4:23
    The most common example would be theme_username.
  • 4:27
    That is, for example, in the top of the node when you say,
  • 4:31
    oh, submitted by Joe on this date.
  • 4:35
    So the "submitted by Joe" part, the way that Joe is written,
  • 4:38
    that's their username.
  • 4:40
    So if you don't like how that's being handled,
  • 4:43
    you can go ahead and copy that function
  • 4:46
    from core in and rename the theme username to whatever yours is.
  • 4:52
    So it could be bartik_username, and then it gets called.
  • 4:57
    So very simple-- you go ahead and you find the original function.
  • 5:01
    You copy it into your template.php file,
  • 5:04
    and you rename any of the prefixes-- amendments-- as you need fit.
  • 5:09
    Don't forget to clear the cache, though.
  • 5:12
    So the way Drupal looks at theme functions is in the code,
  • 5:17
    in a module, theme(breadcrumb) is written.
  • 5:21
    And immediately, it goes and looks and says,
  • 5:23
    hey, does the current theme have any specification
  • 5:27
    about what that means?
  • 5:29
    So it goes and looks for mytheme_breadcrumb.
  • 5:32
    If it finds it, great-- goes ahead and use it, and that's the output.
  • 5:37
    If it doesn't find it, it then moves on
  • 5:39
    to the default of theme_breadcrumb and whatever the output of that is.
  • 5:45
    Previously, in Drupal 6, there was also phptemplate_breadcrumb,
  • 5:49
    but you don't need to worry about that any longer.
  • 5:52
    So theme functions allow your theme to have
  • 5:55
    the last crack at the outputted HTML,
  • 5:58
    and you have complete control over that.
  • 6:02
    Just by naming your function, following a certain pattern,
  • 6:07
    that's what gives you the power.
  • 6:09
    So theme functions themselves are never directly called.
  • 6:15
    You never call theme_username.
  • 6:18
    You never even type in your modules to call a specific variation
  • 6:22
    of it, a bartik_username.
  • 6:25
    You always utilize the syntax of printing theme parentheses,
  • 6:33
    and then in single quotes, whatever type of theme function that is.
  • 6:37
    And the reason you do that is that actually triggers the Drupal system
  • 6:41
    to go ahead and to look for-- does the current theme have
  • 6:45
    an implementation of this and to utilize that first.
  • 6:49
    And if not, then to go find what the default behavior should
  • 6:53
    be-- very, very, very powerful.
  • 6:56
    The theme override system allows you to completely control all HTML
  • 7:02
    output, just by typing something very, very
  • 7:04
    simple in your template.php file.
  • 7:08
    So the theme function itself will always call the correct version.
  • 7:15
    So when do you know to use a tpl.php file
  • 7:20
    or to use your template.php file with theme
  • 7:25
    functions and preprocess functions?
  • 7:28
    First bit to think about-- a tpl.php is for markup.
  • 7:34
    It's for HTML and very, very simple print statements only.
  • 7:40
    This is the kind of file a designer could
  • 7:42
    pick up and go, OK, I need to change this div to an h2
  • 7:47
    and work with that.
  • 7:50
    The theme functions in template.php and preprocess functions
  • 7:56
    in template.php are very, very PHP code heavy-- limited markup
  • 8:02
    in there because whenever possible, your modules are also
  • 8:06
    going to be providing these TPL files,
  • 8:09
    and then your themes can override them.
  • 8:12
    Complex logic always will take the place
  • 8:16
    in your template.php to create a variable to pass to your tpls.phps.
  • 8:23
    Just to recap what we have done in the previous series,
  • 8:28
    and what we're going to talk about going forward,
  • 8:31
    is there are three steps to theming.
  • 8:33
    The first is your .info file.
  • 8:36
    This is where you say, hey, I'm a theme.
  • 8:38
    I have these different kinds of CSS files and JavaScript files.
  • 8:43
    Then, there's also the template files.
  • 8:46
    This is your page template and your node template,
  • 8:50
    or even your node article templates.
  • 8:53
    And then, going forward in our advanced theming series,
  • 8:55
    we are going to discuss template.php, where we can create
  • 9:01
    new variables to pass to our template files,
  • 9:03
    where we can change variables, and also where we can adjust markup
  • 9:09
    for simple functions that are used regularly, like theme_username
  • 9:13
    or theme_breadcrumb.
  • 9:15
    I want to take a moment to compare the two different kinds of files,
  • 9:20
    the TPL files and template.php.
  • 9:25
    If we take a look at bartik, the theme that comes with Drupal core,
  • 9:30
    and we go ahead and open our page.tpl and our template.php,
  • 9:38
    will be able to notice some differences.
  • 9:40
    For our page.tpl, the biggest thing you're going to notice
  • 9:45
    is that we throughout the file have opening and closing PHP tags.
  • 9:52
    So this few lines right here is a PHP statement
  • 9:57
    that says if $logo exists, then we need to print what's
  • 10:03
    on the following lines, and then simply saying,
  • 10:06
    OK, that's the end of our if statement.
  • 10:09
    So a tpl.php file is full of if a variable exists, print something--
  • 10:17
    potentially that variable, with markup around it--
  • 10:20
    and then your and/if statements.
  • 10:22
    There's no complicated logic in here.
  • 10:25
    Differently from that, if we open our template.php file,
  • 10:30
    you'll notice that there is an opening PHP tag, and that is it.
  • 10:35
    All of the contents of this file is 100% pure PHP.
  • 10:40
    There's no markup in here.
  • 10:43
    There are functions followed by functions
  • 10:46
    followed by functions in this file.
  • 10:48
    And what I wanted to really show you is that if we go back,
  • 10:52
    a designer can open up a tpl.php file and very easily say,
  • 10:58
    you know what?
  • 10:59
    I really don't want this to have a div ID of site-slogan.
  • 11:05
    I want it to be something else-- and go
  • 11:07
    in and make those changes to the file
  • 11:09
    without any problems whatsoever.
  • 11:12
    There's no complicated logic going on.
  • 11:14
    If you go to a template.php file, there's no markup.
  • 11:18
    So this is where variables are being set and also changed.
  • 11:23
    The biggest thing to remember with theming in Drupal-- markup
  • 11:27
    goes in tpl.php, and then PHP logic goes in template.php,
  • 11:34
    and I find it very, very confusing that the nomenclature for these
  • 11:37
    are so similar.
  • 11:39
    So just remember, a template file is your page.tpl, your node.tpl.
  • 11:45
    And template.php is where all of your functions live.

Introduction Advanced Theming in Drupal 7


In this series, we talk about template.php, the file where all your functions live. We’ll also discuss preprocess functions and overriding theming functions. You’ll learn how to create new variables and override existing ones using template.php. With these tools you can allow your theme to have complete control of outputted HTML.

In this video you’ll learn when to use a tpl.php file or your template.php file, and we’ll look at differences between them. We’ll also review the three main steps of theming.

Log in or sign up to download companion files.
Additional resources: