How Does Drupal 7 Render Out a Page?

Question

How does Drupal 7 render out a page? What's its equivalent to an MVC's view system.

When it comes to the rendering out the final HTML page for a request, most PHP frameworks (MVC based) I've worked with take an approach where a top-level layout/page PHP file sets out the basic document structure, and then renders our various sub-views via includes or view rendering methods.

//Simplified version
Page.phtml
    Head.phtml
    Body.phtml
        Banner.phtml
        Topnav.phtml
        Left.phtml
        Content.phtml
        Footer.phtml

I'm a little confused as to Drupal's take on this. I'm reading through Pro Drupal Development, and it starts off in similar territory with a page.tpl.php. However, it glosses over how the theme engine (is that the right term?) gets the various parts of PHP into this page (not a criticism, the book's taking an approach that different from the path I'm on).

Also, the Drupal 7 themes don't seem to have the page.tpl.php file, so its not clear (to me) where the page skeleton comes from. Also, from what I've read it seems like "Blocks" are involved, but it's not clear to me if "Blocks" makeup the entire page, or if blocks are something used selectively by themes.

So, working from high level concepts (or get as detailed as you'd like), how does Drupal 7 render out a page?

I realize you can, and probably should, start with Drupal without understand how everything ties together. I'm specifically trying to learn how the various Drupal systems come together. Apologies to people tired of reading this disclaimer!

Solution 1

I think there are two questions here. First, how does a single theme/template get rendered/used/displayed and second, how does the whole site come together. I think the second question has already been answered above, so I'm going to try to explain the first a bit more.

First, a module (that's why system.module exists, for all these stuff that only a module can do like implementing hook_menu()) needs to define that a specific theme function/template exists, by declaring it in hook_theme()

Speaking of that, there are two different things which can be used. A theme function, which is a function prefixed with theme_. Often used for smaller elements of a page wich have more complex logic/PHP like theme_table(). And a template, which is a file with the tpl.php like page.tpl.php

To use a theme function/template, you can either call theme() like this:

$output = theme('table', array('rows' => $rows, 'header' => $header));

Or you can use the new, so called renderable array thing. That is basically an array of data + information which theme to use:

$output = array(
  '#theme' => 'table',
  '#rows' => $rows,
  '#header' => $header,
);

The second is preferred because it means that it will be themed as late as possible and other modules can change it in hooks. The result will be exactly the same, drupal_render() will then call theme() itself during the final rendering.

When theme() is called, it looks up the function/file to use, looks if it has been overriden the used theme, if there are so called template suggestions and then uses them.

To override a theme function in a theme, copy it to your template.php file and replace "theme_" with "yourthemename_", if it is a tpl.php file, copy it to your directory.

Now, what the final rendering process is doing is basically building up a large $page array, that is a renderable array (Some documentation of that is in hook_page_alter() and then call drupal_render() on it.

The global structure of the page/template hierarchy (which is not hardcoded, but given through whatever is in $page) is something like this:

html.php.tpl
  head.php.tpl
  page.php.tpl
    multiple regions
      multiple blocks

Almost everything is a block in Drupal 7, including the actual content, which is typically a node. A theme defines which regions it has and then you can assign blocks to it in the UI.

Solution 2

When trying to understand how the templates fit together, the best tool I've found is the Theme Developer module. It works a little like Firebug and allows you click on areas of a page to see the theme functions or template files that are used for various parts of the page, along with the "suggestions" that can be used for overriding them.

Templates can fit together in a variety of ways. Drupal does make some assumptions about how they'll be nested, which are reflected in the default variables that are available in the templates files. However, both the template suggestions and the available variables within them can be modified.

As I understand it, page.tpl.php has been replaced by html.tpl.php in Drupal 7.

The best description I've heard for "Blocks" is that they're what you use to display content that will be re-used in various areas site. The most common use is for sidebars, such as "Recently updated pages" lists or "Who is online now" lists.

Solution 3

Try take a look a presentation on How pages are built on Drupal 7 from drupalcon at http://sf2010.drupal.org/conference/sessions/page-render-drill-down-drupal-7 specially after 5 minutes from start (05:10). Sorry can't specify much detail here cause i still watch it my self. And try to understand it as well. ;)

[Update]

After watch the presentation here is my quick conclusion on how drupal 7 render out a page:

Instead of common approach that you mention from your question

where a top-level layout/page PHP file sets out the basic document structure, and then renders our various sub-views via includes or view rendering methods

Drupal render a page through a rendering flow approach like this

1. bootstrap
2. menu_execute_active_handler
3. page_callback
4. delivery_callback
5. hook_page_alter()
6. drupal_render($page)

However, it glosses over how the theme engine (is that the right term?) gets the various parts of PHP into this page (not a criticism, the book's taking an approach that different from the path I'm on).

that various parts is served starting from rendering flow number 3 (page_callback) through flow number 6 (drupal_render($page)) where its start to return an array of drupal render-able array and then latter in your theme you can use the $page variable (served from drupal_render($page)) to render i.e drupal content.

Comments

[Alan Storm]

Any idea why Drupal 7 stores html.tpl.php in the system module? Can themes have their own custom html.tpl.php ?

[Matt V.]

Yes, any core/system template file can be overridden by copying the file to your theme directory and modifying it as needed. Just be sure to clear the theme cache, in order for the new file to be recognized: drupal.org/node/337176

[Alan Storm]

Watching that video now. It's pretty thorough, and makes it clear a lot has changed since Drupal 6.

[Richard]

I don't think html.tpl.php replaced page.tpl.php. I could be wrong, but as far as I understand it, page.tpl.php is suitable for everything inside <body>, html.tpl.php for <body> and everything outside it.