Understanding Template Files

Some themes have all sorts of template files, while others only have page.tpl. php. So how do you know which template files you can create and have be recognized in Drupal? What naming conventions surround the creation of template files? You'll learn the ins and out of working with template files in the following section.

page.tpl.php page.tpl.php is the granddaddy of all template files, and provides the overall page layout for the site. Other template files are inserted into page.tpl.php, as the diagram in Figure 8-4 illustrates.

Drupal Template Files Diagram

page.tpl.php

Figure 8-4. Other templates are inserted within the encompassing page.tpl.php file.

page.tpl.php

Figure 8-4. Other templates are inserted within the encompassing page.tpl.php file.

The insertion of block.tpl.php and node.tpl.php in Figure 8-4 happens automatically by the theme system. Remember when you created your own page.tpl.php file in the previous example? Well, the $content variable contained the output of the node .tpl. php calls, and $sidebar_left contained the output from the block.tpl.php calls.

What if you want to create different layouts for other pages on your site, and a single page layout isn't going to cut it? There are two best practices for creating additional page templates.

First, you can create additional page templates within Drupal based on the current system URL of the site. For example, if you were to visit http://example.com/?q=user/1, PHPTemplate would look for the following page templates in this order:

page-user-1.tpl.php page-user.tpl.php page.tpl.php

PHPTemplate stops looking for a page template as soon as it finds a template file to include. The page-user.tpl.php file would execute for all user pages, whereas page-user-1.tpl.php would only execute for the URLs of user/1, user/1/edit, and so on.

■Note Drupal looks at the internal system URL only, so if you're using the path or pathauto modules, which allow you to alias URLs, the page templates will still need to reference Drupal's system URL and not the alias.

Let's use the node editing page at http://example.com/?q=node/1/edit as an example. Here's the order of template files PHPTemplate would look for:

page-node-edit.tpl.php page-node-1.tpl.php page-node.tpl.php page.tpl.php

Caution Even if you don't output the region variables ($header, $footer, $sidebar_left, $sidebar_right) within page.tpl.php, they are still being built. This is a performance issue because Drupal is doing all that block building only to throw them away for a given page view. If custom page views don't require blocks, a better approach than excluding the variable from the template file is to head over to the block administration interface and disable those blocks from showing on your custom pages. See Chapter 9 for more details on disabling blocks on certain pages.

■Tip To create a custom page template for the front page of your site, simply create a template file named page-front.tpl.php.

If you need to make a custom page template, you can start by cloning your current page.tpl.php, and then tweak it as needed. The following variables are passed into page templates:

• $base_path: The base path of the Drupal installation. At the very least, this will always default to / if Drupal is installed in a root directory.

• $breadcrumb: Returns the HTML for displaying the navigational breadcrumbs on the page.

• $closure: Returns the output of hook_footer() and thus is usually displayed at the bottom of the page.

• $css: Returns an array structure of all the CSS files to be added to the page. Use $styles to return the HTML version of the $css array.

• $content: Returns the HTML content to be displayed. Examples include a node, an aggregation of nodes, the content of the administrative interface, and so on.

• $directory: The relative path to the directory the theme is located in; for example, themes/bluemarine or sites/all/themes/custom/mytheme. You'll commonly use this variable in conjunction with the $base_path variable to build the absolute path to your site's theme:

• $feed_icons: Returns RSS feed links for the page.

• $footer_message: Returns the text of the footer message that was entered at Administer >■ Site configuration >■ Site information.

• $head: Returns the HTML to be placed within the <head></head> section. Modules append to $head by calling drupal_set_html_head() to add additional markup such as RSS feeds.

• $head_title: The text to be displayed in the page title, between the HTML <title></title> tags.

• $help: Help text, mostly for administrative pages. Modules can populate this variable by implementing hook_help().

• $is_front: TRUE if the front page is currently being displayed.

• $language: The language in which the site is being displayed.

• $layout: This variable allows you to style different types of layouts, and the value for $layout depends on the number of sidebars enabled. Possible values include none, left, right, and both.

• $logo: The path to the logo image, as defined in the theme configuration page of enabled themes. It's used as follows in Drupal's core themes:

<img src="<?php print $logo ?>" />

• $messages: This variable returns the HTML for validation errors and success notices for forms and other messages as well. It's usually displayed at the top of the page.

• $mission: Returns the text of the site mission that was entered at Administer >■ Site configuration >■ Site information. This variable is only populated when $is_front is TRUE.

For more ebook: http://latestebook.com

• $node: The entire node object, available when viewing a single node page.

• $primary_links: An array containing the primary links as they have been defined at Administer >■ Site building >■ Menus. Usually $primary_links is styled through the theme(' links') function as follows:

<?php print theme('links', $primary_links) ?>

• $scripts: Returns the HTML for adding the <script> tags to the page. This is also how jQuery is loaded (see Chapter 17 for more on jQuery).

• $search_box: Returns the HTML for the search form. $search_box is empty when the administrator has disabled the display on the theme configuration page of enabled themes or if search module is disabled.

• $secondary_links: An array containing the secondary links as they have been defined at Administer >■ Site building >■ Menus. Usually $secondary_links is styled through the theme(' links') function as follows:

<?php print theme('links', $secondary_links) ?>

• $sidebar_left: Returns the HTML for the left sidebar, including the HTML for blocks belonging to this region.

• $sidebar_right: Returns the HTML for the right sidebar, including the HTML for blocks belonging to this region.

• $site_name: The name of the site, which is set at Administer >■ Site configuration >■ Site information. $site_name is empty when the administrator has disabled the display on the theme configuration page of enabled themes.

• $site_slogan: The slogan of the site, which is set at Administer >■ Site configuration >■ Site information. $site_slogan is empty when the administrator has disabled the display of the slogan on the theme configuration page of enabled themes.

• $styles: Returns the HTML for linking to the necessary CSS files to the page. CSS files are added to the $styles variable through drupal_add_css().

• $tabs: Returns the HTML for displaying tabs such as the View/Edit tabs for nodes. Tabs are usually at the top of the page in Drupal's core themes.

• $title: The main content title, different from $head_title. When on a single node view page $title is the title of the node. When viewing Drupal's administration pages, $title is usually set by the menu item that corresponds to the page being viewed (see Chapter 4 for more on menu items).

Was this article helpful?

0 0

Responses

  • omar
    How to dispaly the block view details in tpl page?
    8 years ago

Post a comment