Introduction

This is an introduction on how to convert a modern CSS/HTML design to PHPTemplate, the Bryght template language (In addition to PHPTemplate, Drupal has lots of other templating languages; Bryght only offers PHPTemplate because we think it is the most flexible and the best and of course, a Bryght guy :-) wrote it!). It is an introduction and it is therefore not exhaustive in its treatment of PHPTemplate. But, together with the the official PHPTemplate documentation, you should have enough information to convert basic CSS/HTML designs to PHPTemplate and after reading this, you should have a solid foundation for more advanced conversions.

Click on "read more" for the full details!

Prerequisites

• a second admin id with full permissions for your site and the theme editor module must be enabled (administer » modules » check theme_editor box » Save configuration; more details)
• modern CSS Design knowledge i.e. you need to know how to design without gratuitous tables in order to make your site search engine friendly and accessible
• A modern CSS/HTML design

Helpful but not necessary

A rudimentary knowledge of PHP specifically:

• How PHP variables work - instead of hardcoding content you retrieve it from Drupal using PHPTemplate variables
• The PHP if statement - typically used to see which page you are on
• The PHP foreach statement - typically used for navigation bars

Don't despair if you don't know the above or don't understand the web pages that are linked to above. They will be explained in the context of converting a CSS/HTML design below. If you can create a CSS/HTML design, you can easily master the basics of PHP that are required by PHPTemplate!

Step 1. Create your theme using the theme editor

This will be done by customizing one of the existing themes (it doesn't matter which since you will be overriding that theme's files!) which creates a copy of an existing theme and then renaming the copy:

1. Copy one of the existing themes e.g. themex:
   
   • administer » theme editor » "new" tab
   • select any theme; e.g. selecting box_grey "creates a "box_grey customized" theme
2. Rename the theme to something more meaningful e.g. from "themex customized" to "my theme":
   
   • click on the "list" tab » next to the customized theme; e.g. "box_grey customized"
   • click on "rename" » type in new name e.g. "my cool theme"
   • click the "Rename" button

Step 2. Upload your design's graphic files

Your design probably has some supporting graphic files (usually in JPEG, GIF or PNG format). If so, for each graphic file:

1. click administer » theme editor
2. next to your customized theme click on "edit"
3. click on "Browse" under "Upload file"
4. navigate to the graphic and double click on it, then click the "Upload" button

Step 3. Replace your template's CSS file with the design's CSS file

First, you will save a copy of the template's CSS file which is usually called "style.css". Why? To act as a reference and a backup:

1. click administer » theme editor
2. next to your customized theme click on "edit"
3. next to style.css, click on "edit"
4. select all the text in the file, copy and paste into a file on your computer

Then you will replace the template's CSS with the CSS of your design:
In your favourite text editor, open your design's CSS file, select all the text and copy into the browser window with style.css » "Save

Step 4. Replace your template's page.tpl.php with your design's HTML file and replace content with variables

First, you will save a copy of the template's page.tpl.php file. Why? To act as a reference and a backup:

1. click administer » theme editor
2. next to your customized theme, click on "edit"
3. next to page.tpl.php click on "edit"
4. select all the text in the file, copy and paste into a file on your computer

Then you will replace the template's page.tpl.php with the HTML of your design after first editing it to replace content with PHPTemplate variables as follows:

1. In your favourite text editor, open your design's HTML file (usually called something like index.html or content.html) and do the following edits:
   1. Replace head and body code with code for PHPTemplate header, title, javascript, etc i.e.

      <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
          "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
      <html>
      <head>
      <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
      <title>Welcome to Acme Ltd.</title>
      <link href="mydesign.css" rel="stylesheet" type="text/css">
      <script language="JavaScript" type="text/javascript" src="/js/auto.js"></script>
      </head>
      <body>

      becomes (note the variables in bold; in particular that "Welcome..." has been replaced by $head_title and "mydesign.css" has been replaced by "print $styles"; when PHPTemplate sends a page to a web browser, it substitutes the title of the web page for $head_title and the path to the stylesheet for $styles and so on):

      <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
          "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
          <html xmlns="http://www.w3.org/1999/xhtml" lang="<?php print $language ?>" 
      xml:lang="<?php print $language ?>">
          <head>
          <title><?php print $head_title ?></title>
          <meta http-equiv="Content-Type" content="text/css" />
          <?php print $head ?>
          <?php print $styles ?>
          </head>
          <body <?php print theme("onload_attribute"); ?>>

   2. add "<?php print $directory ?>/" before any image URLs

      <img src="develop.jpg" width="110" height="90">

      becomes

      <img src="<?php print $directory;?>/develop.jpg" width="110" height="90">

      Why do this? The $directory variable is a special one that outputs the path to your theme directory where you have uploaded your images.
      

   3. Add a PHP foreach loop for navigation bars.
      Drupal stores the links for the navigation bars in PHPTemplate variables e.g. for primary navigation, the variable is $primary_links and the for secondary navigation the variable is $secondary_links. Check out our How to Edit Your Site's Navigation Links for more info on this.

      Here's a primary navigation example:

      <div id="navlist">
        <ul>
          <li class="on">Home</li>
          <li><a href="about.htm">About Acme</a></li>
          <li><a href="solutions.htm">Solutions</a></li>
          <li><a href="support.htm">Support</a></li>
          <li><a href="news.htm">News & Updates</a></li>
          <li class="input"><input class="form-text" type="text" size="10" value="" 
      name="keys" /> Search</li>
        </ul>
      </div>

      becomes (note that the hardcoded about.htm has been replaced by $primary links, note the bold text)

          <div id="navlist">
          <?php if (is_array($primary_links)) : ?>
            <ul id="primary">
               <?php foreach ($primary_links as $link): ?>
      	     <li><?php print $link?></li>
               <?php endforeach; ?>
               <?php if ($search_box): ?> 
          <li class="input"><form action="<?php print $search_url ?>" 
      method="post" id="searchform"> 
            <input class="form-text" type="text" size="10" value="" 
      name="keys" id="s" /> Search
          </form></li> 
          <?php endif; ?> 
      
            </ul>
           <?php endif; ?>
          </div>

      This may seem "challenging", but it's not. You are replacing hardcoded links in your navigation bar with links that Drupal supplies when serving a web page to a browser. The PHP is_array function simply checks to see if a variable (in this case $primary_links) is an array which is PHP's term for a list with one or more members.

      If an administrator has defined some primary links, then $primary_links will be an array. In that case, the PHP foreach statement is used to retrieve each of the links that the administrator has defined. In our example, the administrator would define the links as support, solutions, about and news. The ".htm" extension is not needed for Drupal.

      If an administrator has not defined any primary links, then $primary_links will NOT be an array and a nav bar will not be generated.

      The $search_box and $search_url are used to set up a search box. If you would like a search box as part of your nav bar, simply copy this code. More details about the PHPTemplate search related variables can be found on the page.tpl.php documentation page.

   4. Replace hardcoded text with PHPTemplate variables:
      1. $content is the non sidebar content generated by Drupal to be displayed
      2. sidebars: right sidebar content is in $sidebar_right, left sidebar content is in $sidebar_left
      For example, if you have a 3 column CSS design, instead of hardcoded text like "Lorum..." for the middle column, you would use $content. And similarly for the left and right columns you would use $sidebar_left and $sidebar_right. But of course, PHPTemplate doesn't force you to use a 3 column template. It's up to you! You must, however, display the $content and the right and left sidebars somewhere in your theme; otherwise the admin menus won't show up and you won't be able to administer the site!
2. Front page specific stuff using $is_front: Wherever you have stuff that is front page specific, wrap it up in the following code:

   <?php if ($is_front): ?>
   
     ... front page specific stuff
   
   <?php else: ?>
        
       ... stuff for the other pages   
   
   <?php endif; ?> <!-- /! is_front -->

   $is_front is set to true if Drupal is rendering the front page, false otherwise. So you use the above code to put up front page specific markup if you have any (not all themes do!).

   For example you may only want to display the site mission and slogan on the front page. Here's one way you could do do that:

   <?php if ($is_front): ?>
          <div id="homecontent">
             <?php if ($site_slogan) : ?>
                <h1 id="site-slogan"><?php print($site_slogan) ?></h1>
             <?php endif;?>
   
             <?php if ($mission) : ?>
                <?php print($mission) ?></div> 
             <?php endif; ?>
   <?php endif; ?>

   Note that the above code is just an example. You can call the CSS styles whatever you want and put the slogan and mission anywhere on the page.

3. Finally, you must add a PHP print $closure statement at the bottom of the page for any dynamic javascript that needs to be called once the page has already been displayed. i.e. just before the closing body tag add:

   <?php print $closure;?>

4. Select all the text in your design's modified HTML file and copy into the browser window with page.tpl.php » Save

Step 5.Check out your theme's appearance and edit as necessary

You do this by setting your theme to your new theme while you are logged in as a user with admin privileges. Before you do this, make sure you are not logged in as admin. Again, by not using admin, but using another id with admin privileges, you can recover by logging in as admin should a bug in your theme make the site unusable or unreadable.

• click administer » users
• click on "edit" next to your 2nd admin user e.g. admin2
• scroll down to "Theme settings", make sure your theme is selected
• click "Save account"
• Now you will see your new theme.

Step 6. Check all content types and style as necessary

Why do you have to do this? Well, extension modules that implement content types may add their own styles.

For all the content types that you use on your site (blog post, story, event, etc.), view a sample page with that content type and see if everything is styled. If not, view source, find out the style and change style.css or whatever the filename of the CSS stylesheet is.

Step 7. You are done. Eat some mohnkuchen or chocolate

Once you are satisfied with your theme, you must activate it for everybody as follows:

• click administer » themes
• In the "Default" column, make sure your theme is selected
• click "Save configuration"

That wasn't so bad was it? As they say, "you deserve a break today". So take one! Chocolate, mohnkuchen and dancing work for me but your mileage may vary!

The power of PHPTemplate is only limited by your imagination. There's plenty more you could do (e.g. we haven't discussed some PHPTemplate variables that you probably want to use in your template). You have the flexibility and power of CSS and PHP at your fingertips.

This is only a introduction so we have only discussed the page template. Depending on your needs you may want to modify the other templates:

• node.tpl.php - controls the display of a node and a node summary. A node is a content type like a book page, story, blog post, etc.
• block.tpl.php - Lays out content for blocks (left and/or right side of page). This template is optional, and can be overridden by copying the default template and modifying it.
• box.tpl.php - Prints a simple html box around a page element. For instance: The comment view options are surrounded by box.tpl.php
• comment.tpl.php - defines the HTML for a comment block

Consult the official PHPTemplate documentation and go for it!