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 to Theming Basics for Drupal 7

Video loading...

  • 0:07
    Introduction to Drupal 7 Theming Joe Shindelar
  • 0:17
    In this chapter, we'd like to talk a little bit about
  • 0:19
    what theming in Drupal really is.
  • 0:22
    First off, the word theming is pronounced kind of like scheming,
  • 0:25
    and spelled just like it's shown on the screen.
  • 0:28
    Spellcheckers tend to get a little bit confused by it,
  • 0:30
    but that's really the way that we say it, theming.
  • 0:33
    Theming in Drupal is made up of a number of different pieces.
  • 0:36
    One of the things that you're doing is designing the appearance of your website.
  • 0:40
    You might use tools like Photoshop or Fireworks
  • 0:42
    to mockup what the website is going to look like for your users.
  • 0:46
    Another component of theming in Drupal
  • 0:48
    is creating the CSS to control the layout of your site.
  • 0:51
    This isn't something that we're going to cover in this video series,
  • 0:54
    however, creating the CSS is no different
  • 0:57
    than what you would do for creating a static HTML website
  • 1:00
    or creating the CSS design for any other website.
  • 1:03
    The last part and the part that we'll talk about the most in this video is
  • 1:07
    changing the HTML output by Drupal to fit the design.
  • 1:11
    When Drupal creates a page, it outputs a set of default HTML markup.
  • 1:15
    What we're going to talk about is how you, as the themer,
  • 1:18
    can modify that HTML output by Drupal
  • 1:20
    to conform to the HTML that you need for your designs.
  • 1:24
    There's 3 simple steps to creating a theme in Drupal.
  • 1:27
    We'll talk about each one of those in depth.
  • 1:30
    The first step is to create an info file.
  • 1:32
    Info files are metadata that tell Drupal
  • 1:35
    what your theme does and what its name is.
  • 1:38
    The second step are template files or any file
  • 1:40
    that ends in a .tpl.php extension.
  • 1:44
    And the third step, template.php, is a PHP file optional for themes
  • 1:49
    used to replace the variables inside of template files
  • 1:52
    and override theme functions.
  • 1:54
    We won't be talking about the third step in this basic theming series,
  • 1:58
    however, in a coming advanced theming series,
  • 2:01
    we'll go more in depth on step number three.
  • 2:05
    Let's talk a little bit about the structure of a theme.
  • 2:09
    All of our themes, those that we download from
  • 2:12
    or those that we create ourself, live inside of the sites,
  • 2:14
    all, themes directory in a directory that is the name of your theme.
  • 2:20
    Themes are made up primarily of things
  • 2:22
    that are part of traditional web design, things like CSS files,
  • 2:26
    JavaScript files, and images that make up all of the layout of the page.
  • 2:30
    All of these files live inside of your themes directory.
  • 2:33
    And in addition to that, you'll see some files
  • 2:35
    that are specific to creating a theme in Drupal.
  • 2:38
    Things like an info file, optional template files,
  • 2:41
    and an optional template.php file.
  • 2:45
    Again, the .info file corresponds to step number one
  • 2:48
    in creating a theme telling Drupal what your theme can do.
  • 2:52
    Template files like the page.tpl.php file,
  • 2:55
    which are primarily HTML
  • 2:57
    control the overall layout of your site
  • 2:59
    in the general HTML markup
  • 3:01
    correspond nicely to step number 2.
  • 3:04
    And finally, template.php, which is used to set variables
  • 3:07
    and override theme functions, corresponds to our step number 3.
  • 3:12
    Let's take a look at what you might see
  • 3:14
    inside of an info file,
  • 3:16
    the primary thing that an info file does
  • 3:18
    is announce the presence of your theme to Drupal.
  • 3:20
    Without a .info file, Drupal will not know
  • 3:23
    that you've created a custom theme and you'll not be able to enable it.
  • 3:27
    Inside of your info file are a bunch of key-value pair properties
  • 3:30
    that do things like tell Drupal the name and description of your theme,
  • 3:34
    define some of the CSS and JavaScript files
  • 3:36
    that you might use. In addition to that,
  • 3:38
    tell Drupal about features that your theme might provide
  • 3:41
    and the regions that your theme makes available for placing blocks into.
  • 3:45
    A typical info file might look something like this.
  • 3:49
    Again, key-value pairs representing things
  • 3:52
    like the name of your theme and the description and so forth.
  • 3:55
    In Drupal 7, the only 3 required things
  • 3:58
    in a .info file are these first 3,
  • 4:01
    the name, which provides a human-readable name for your theme
  • 4:04
    and a description, which is just a simple one sentence description of your theme.
  • 4:09
    These things are used on the Appearance page
  • 4:11
    when enabling a theme to provide administrators
  • 4:14
    with a friendly name and description for your theme.
  • 4:16
    In addition to that, you also need to specify
  • 4:19
    the version of Drupal core that your theme is compatible with.
  • 4:22
    In this case, we're saying that our theme is compatible with Drupal 7.
  • 4:26
    One of the things that you'll commonly see in a .info file
  • 4:29
    are the stylesheets and scripts lines.
  • 4:31
    This is our theme using the .info file
  • 4:34
    in order to include JavaScript files and CSS files
  • 4:38
    on every single page throughout the site.
  • 4:40
    This is nice for things like CSS files
  • 4:42
    which provide the main layout for the page
  • 4:44
    and that you want to be loaded on every single page.
  • 4:47
    Declaring style sheets and JavaScript files
  • 4:50
    into file also ensures
  • 4:53
    that Drupal is able to use CSS and JavaScript aggregation
  • 4:56
    to include your theme's JavaScript and CSS files.
  • 5:00
    The syntax for including style sheets and scripts
  • 5:03
    is similar to the name and description syntax.
  • 5:05
    However, in this case, we use square brackets,
  • 5:07
    similar to creating arrays in PHP.
  • 5:10
    This allows us to add multiple CSS files or multiple JavaScript files.
  • 5:15
    Finally, the stylesheets line, you can see the word all
  • 5:18
    in the first set of square brackets.
  • 5:20
    This maps to the media attribute and the link tag used
  • 5:23
    when including a style sheet on the page.
  • 5:25
    So you could, instead of using all,
  • 5:27
    use words like print and you would end up with a style sheet
  • 5:30
    that had a media attribute of print
  • 5:32
    and would only be used when someone is printing the page.
  • 5:35
    In addition to adding style sheets and JavaScript files
  • 5:38
    through your .info file, you can also add style sheets
  • 5:41
    and JavaScript in a template.php file.
  • 5:44
    You would do this in scenarios where you had certain style sheets
  • 5:47
    that you only wanted to load on certain pages throughout the site.
  • 5:50
    We'll talk more about that in another video.
  • 5:54
    In Drupal, themes are responsible
  • 5:57
    for declaring all of the regions that are available for an administrator
  • 6:00
    to place blocks into.
  • 6:02
    Regions are declared inside of a .info file.
  • 6:05
    The syntax for creating regions inside of a .info file
  • 6:09
    is similar to creating an array in PHP.
  • 6:12
    You type the word regions and then inside of square brackets,
  • 6:15
    the machine-readable name of a region.
  • 6:17
    And then the value is the human-readable name of the region.
  • 6:22
    A couple of important things to note
  • 6:23
    when creating regions in a Drupal theme.
  • 6:26
    First, regions are optional.
  • 6:28
    You don't actually need to add any regions in your theme.
  • 6:31
    And if you don't add any regions,
  • 6:33
    Drupal will assume a default set of regions.
  • 6:36
    The default set of regions include a sidebar_first,
  • 6:39
    sidebar_second, content, header, footer,
  • 6:42
    highlighted, and help.
  • 6:44
    As soon as your theme declares one region,
  • 6:47
    the defaults are ignored and Drupal assumes
  • 6:50
    that your theme will declare all of the necessary regions.
  • 6:54
    One important thing to point out for Drupal 7 themes
  • 6:56
    is that the content region is required
  • 6:59
    in order for your theme to be enabled.
  • 7:02
    Once you've added regions to your theme,
  • 7:04
    they become available for an administrator to place blocks into.
  • 7:08
    And it looks something like this.
  • 7:11
    You can see I've declared a sidebar_first region,
  • 7:14
    and on the block administration page,
  • 7:16
    I now have an option to add any blocks to that first sidebar,
  • 7:19
    the human-readable name there.
  • 7:21
    And I also have inside of my page template file,
  • 7:24
    in the page variable,
  • 7:26
    the sidebar_first region which will contain all of the blocks
  • 7:30
    that are in that region for that particular page.
  • 7:33
    Another thing that you may or may not see
  • 7:35
    inside of a themes .info file is the declaration of features.
  • 7:39
    Features allow you to create single Boolean variables
  • 7:42
    and a checkbox that maps to those variables
  • 7:44
    on the theme's setting page.
  • 7:46
    You might create a variable for something like logo or slogan,
  • 7:50
    that inside of your page template file or other template files,
  • 7:53
    you can check and see
  • 7:55
    did the administrator of the site click the checkbox
  • 7:57
    that corresponds to my logo feature.
  • 8:00
    If so, I may want to print out some additional markup on the page.
  • 8:04
    If not, I may want to skip printing out that markup.
  • 8:08
    Again, if you don't provide any features in your theme,
  • 8:11
    Drupal assumes a default set of features,
  • 8:13
    those defaults are logo, name, slogan, no user picture,
  • 8:19
    favicon, main_menu, and secondary_menu,
  • 8:22
    and the corresponding checkboxes to turn those things on and off
  • 8:25
    when configuring settings for your theme.
  • 8:27
    Those are the most common things that you'll see
  • 8:29
    inside of a .info file.
  • 8:31
    There are few additional things but we'll talk more about those
  • 8:34
    when we actually get to creating a .info file
  • 8:36
    and editing some of those configuration variables.
  • 8:39
    The next thing that you'll take a look at with theming
  • 8:42
    are template files,
  • 8:44
    template files in Drupal are where the real theming work happens.
  • 8:49
    Template files or any of these files that end in a .tpl.php extension
  • 8:54
    contain mostly HTML and a little bit of PHP.
  • 9:00
    What they are, are HTML files
  • 9:02
    that contain simple print statements
  • 9:04
    to print out the dynamic content
  • 9:06
    provided by Drupal wrapped in HTML
  • 9:09
    that creates the structural markup of your page
  • 9:12
    or things like nodes, blocks,
  • 9:14
    or any element that's displayed on the page.
  • 9:17
    Template files control the overall layout and markup of your site.
  • 9:22
    The majority of things that you will do in theming
  • 9:24
    take place inside of a template file.
  • 9:27
    Here's an example of how these template files work.
  • 9:30
    When looking at a page rendered by a Drupal theme,
  • 9:33
    it's actually made up of a number of different template files.
  • 9:37
    The wrapping portion of the page
  • 9:39
    may contain all of the different regions, the header, and the footer, and so forth,
  • 9:43
    live inside of a template file called page.tpl.php.
  • 9:48
    That template file is used once to theme the entire page.
  • 9:51
    The different components of the page, however,
  • 9:54
    may be run through their own template files
  • 9:56
    before being printed out.
  • 9:58
    For example, in our mockup here,
  • 10:00
    we have 2 regions with blocks in them.
  • 10:03
    The one on the left shows all the nodes on this front page.
  • 10:06
    And the one on the right shows a number of additional blocks
  • 10:08
    presumably placed there by the administrator.
  • 10:11
    Each of those blocks is rendered inside of a region,
  • 10:13
    and that region has a corresponding region.tpl.php.
  • 10:19
    And inside of that region, you have things like all of the nodes
  • 10:22
    that make up the center content of the page.
  • 10:25
    Each one of those nodes when it's printed to the page
  • 10:27
    uses the node.tpl.php file.
  • 10:30
    And each one of those blocks, over on the right,
  • 10:33
    those use a block.tpl.php file.
  • 10:37
    It's important to note that some of these template files,
  • 10:39
    things like node and block, for example,
  • 10:41
    may be used more then once when presenting a single page.
  • 10:46
    This makes it really easy to create markup for something like a node
  • 10:49
    and have it be reused for every single node every time it's printed out.
  • 10:54
    An example of a template file might look something like this.
  • 10:58
    This is the node template file from the Bartik theme
  • 11:01
    that ships with Drupal 7.
  • 11:04
    You can see there's definitely some PHP in there
  • 11:07
    but it's limited to primarily simple print statements
  • 11:09
    and a couple calls to this render function,
  • 11:13
    and then a bunch of HTML that makes up the main markup
  • 11:16
    for any node that's being displayed.
  • 11:19
    One of the things you'll probably notice in this node.tpl.php file
  • 11:24
    is the use of the render function,
  • 11:26
    and also, later on, you'll see the hide and show functions.
  • 11:29
    As we dive in and start looking at template files in Drupal,
  • 11:32
    one of the things that you'll need to learn about
  • 11:34
    are renderable arrays.
  • 11:36
    From the theming perspective, renderable arrays are a mechanism
  • 11:39
    that allows Drupal to delay the rendering of any content to HTML
  • 11:43
    for as long as possible.
  • 11:45
    This means that Drupal tends to pass around
  • 11:47
    pieces of content like a node or a block
  • 11:50
    and all of the different things that make up that node
  • 11:52
    as a large structured array
  • 11:54
    that at the very last moment gets rendered into HTML
  • 11:57
    by using the render function.
  • 11:59
    This makes sure that both modules and themes
  • 12:01
    have a large amount of flexibility
  • 12:03
    when it comes to adding and removing things from the page.
  • 12:06
    In order to really understand
  • 12:08
    why Drupal 7 uses this concept of renderable arrays,
  • 12:11
    I think it makes sense to step back for a second
  • 12:13
    and take a look at how things were done in Drupal 6.
  • 12:16
    In Drupal 6, you might have a node template file,
  • 12:18
    and in that node template file, you have a simple variable named $content.
  • 12:22
    Your template file prints out that $content variable
  • 12:25
    which contains the body of the node
  • 12:28
    and any additional CCK fields or information
  • 12:31
    that may have been added to the body of that node.
  • 12:34
    In our example here, you can see
  • 12:36
    we're printing out one additional field on the page.
  • 12:39
    The problem with doing it this way
  • 12:41
    is that if you wanted to manipulate the HTML for that particular field
  • 12:46
    or, say, move that field to the bottom of the body
  • 12:49
    or place it somewhere else on the page,
  • 12:51
    you'd need to not print out the $content variable
  • 12:55
    inside of your node template file
  • 12:56
    and instead print out each individual field
  • 12:59
    and the body of the node separately.
  • 13:02
    This works great until an administrator comes along
  • 13:05
    and adds a new field to your content type.
  • 13:08
    Once they've done that, all of a sudden, the field that they've added,
  • 13:12
    while it shows up in the form
  • 13:13
    and administrators or editors can add content to it,
  • 13:16
    it won't actually show up on the page
  • 13:17
    until the themer has come back and added that field to the template file as well.
  • 13:22
    In order to get around this problem,
  • 13:24
    Drupal 7 introduced the renderable arrays.
  • 13:28
    Let's take another look at our node template file from Drupal 7
  • 13:31
    and see how we might make use of this renderable arrays in our theme.
  • 13:36
    In Drupal 7, that $content variable
  • 13:39
    that used to be just a simple string
  • 13:41
    is now an array of all the elements that make up the actual content of the page.
  • 13:47
    And now instead of just printing out the $content variable,
  • 13:50
    we actually need to use the render function
  • 13:53
    to wrap the variable before printing it to the screen.
  • 13:56
    The render function will recurse through that content array
  • 13:59
    and take each of the elements inside of it and turn those into HTML.
  • 14:03
    The HTML is then returned and we can print it out on the page.
  • 14:07
    In the example here, you can see
  • 14:09
    that we're hiding the comments and links portion of the content, temporarily,
  • 14:13
    we're then calling print render($content.
  • 14:16
    What this will do is take all of the pieces of that array, minus comments and links,
  • 14:21
    which we said to hide, and turn those into HTML and display them on the page.
  • 14:26
    Then later on in our template,
  • 14:28
    we go ahead and manually render the links portion of the $content variable
  • 14:32
    and the comments portion of the $content variable.
  • 14:35
    This gives us the flexibility to move individual elements
  • 14:39
    outside of the main content into different portions of the page
  • 14:43
    or in the template file, but still render
  • 14:46
    the entirety of the $content variable.
  • 14:49
    This means that when an administrator comes
  • 14:51
    and adds an additional field to our content type in Drupal 7
  • 14:54
    that field will immediately start showing up
  • 14:57
    where we've said print render($content.
  • 15:00
    But we can still have control over individual fields
  • 15:04
    and move those around inside of our template file.
  • 15:08
    The important thing to remember here
  • 15:10
    is the use of the render function.
  • 15:13
    There are number of different variables inside of template files in Drupal 7
  • 15:17
    that require being wrapped in the render function
  • 15:20
    in order to turn their content into HTML
  • 15:22
    before printing it out inside of your template file.
  • 15:26
    Another thing that we'll talk about
  • 15:27
    is the use of dynamic template files inside of Drupal.
  • 15:31
    This is a really powerful system that allows you to do something
  • 15:34
    like, say, take the node template file,
  • 15:36
    which is responsible for printing out all of the nodes on your site,
  • 15:40
    and say that for any node of the type article,
  • 15:44
    I'd like to use a different template file.
  • 15:47
    In that scenario, let's say you have
  • 15:49
    4 different node types on your site
  • 15:51
    and you want all them to use for node template file except for one,
  • 15:54
    you want that one to be slightly different, your article template file
  • 15:57
    because it has tags and images that you'd like to display
  • 16:00
    in a different place on the page using some different markup.
  • 16:03
    You can create a dynamic template file
  • 16:06
    using the naming convention shown,
  • 16:08
    node--the node type, machine readable name,
  • 16:12
    in this case, article, followed by the .tpl.php extension.
  • 16:18
    This is identical to how we did this in Drupal 6 as well
  • 16:21
    which had this concept of dynamic template files.
  • 16:24
    The primary difference between Drupal 6 and Drupal 7 in this case
  • 16:27
    is that Drupal 7 uses two hyphens to separate the base name
  • 16:31
    from the more specific targeted name of your template file.
  • 16:35
    We'll also talk about where you can find
  • 16:37
    all these template files inside of Drupal
  • 16:39
    and how to override those in your theme.
  • 16:42
    Drupal, as we said, provides a set of default markup
  • 16:45
    and it does so by providing default template files.
  • 16:48
    The User module, for example,
  • 16:50
    provides a file named user-profile.tpl.php.
  • 16:54
    This contains the HTML markup for a user's profile page.
  • 16:58
    If you want to override that markup inside of your theme,
  • 17:01
    what you can do is copy that template file
  • 17:04
    from Drupal core into your theme,
  • 17:07
    go ahead and make any changes to that copied version of the template file,
  • 17:10
    and then clear the cache so that Drupal finds your version of the template file
  • 17:14
    and starts making use of it.
  • 17:16
    It's important to remember to copy template files
  • 17:19
    out of Drupal core into your theme and not move them.
  • 17:22
    If you were to move the template file,
  • 17:24
    it would no longer exist inside of Drupal core.
  • 17:26
    And if someone decided to switch to a different theme
  • 17:28
    or disable your theme for some reason
  • 17:30
    and Drupal needed to use its default user profile template
  • 17:34
    and no it longer existed, this would cause errors on your site.
  • 17:39
    Drupal core provides a large number of template files.
  • 17:43
    And this list of template files will grow
  • 17:45
    as you add more and more modules to your Drupal setting.
  • 17:47
    Every module likely outputs content in some form or another.
  • 17:51
    And when it does so, it probably does it using a template file.
  • 17:55
    Throughout the course of this series,
  • 17:57
    we'll talk about overriding and making use of a number of different template files,
  • 18:01
    some of the more common ones like the page template file,
  • 18:04
    block template file, nodes, and so forth.
  • 18:06
    We won't necessarily get into all of them
  • 18:08
    but it's good to know that these exist.
  • 18:11
    What we've seen in this presentation
  • 18:13
    are a number of the concepts that make up the first 2 steps
  • 18:15
    in building a theme for Drupal.
  • 18:18
    Step number 1, info files and step number 2, template files.
  • 18:22
    Throughout the rest of this series,
  • 18:24
    we'll be going through both of those steps
  • 18:26
    and all of these concepts in more depth.
  • 18:28
    We'll be overriding template files, creating info files,
  • 18:32
    and building out an entire Drupal theme as we go.

Introduction to Theming Basics for Drupal 7


Theming Basics for Drupal 7 will provide a solid foundation for translating designs into Drupal themes. You'll learn to work with .info and tpl.php template files, how to add CSS and JavaScript, how to work with the render system new in Drupal 7, how to override templates, create regions, and use the Theme Developer tool. You'll start with the original HTML, CSS and JavaScript template files that were provided by the designer so that you can follow along in translating the design into a Drupal 7 theme. The video explains Drupal's design vernacular, concepts, and special needs. We'll show you how to associate the proper CSS & Javascript files, add all of the necessary regions, and control the HTML output through page and node-specific templates. You'll learn about the best tools and strategies for controlling the look and feel of your Drupal website.

This series will cover the basics of Drupal theming while the more advanced theming topics of working with the template.php file will be covered in the Advanced Theming for Drupal 7 series. These videos pair with each other, and will finish the complete implementation of the 960 Robots theme used in both videos. You can download the theme we're building from 960 Robots.

Examples in this video are based on Drupal 7 and its variants.

In this introduction video, we set the stage for the Theming Basics series. We give an overview of what Drupal theming is, the common files we will work with, and the overall steps involved. Then we start off by defining and taking a look at the .info file and HTML template (tpl.php) files. We talk about regions and theme features, introduce the render() function, and explain dynamic templates. While we are teaching Drupal 7 theming, we also make sure to point out the important differences between Drupal 6 and 7.