Drupal 5 Themes

Drupal 5 Themes Create a new theme for your Drupal website with a clean layout and powerful CSS styling

Ric Shreves

BIRMINGHAM - MUMBAI

Drupal 5 Themes Create a new theme for your Drupal website with a clean layout and powerful CSS styling Copyright © 2007 Packt Publishing

All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews. Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author, Packt Publishing, nor its dealers or distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book. Packt Publishing has endeavored to provide trademark information about all the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.

First published: December 2007

Production Reference: 1171207

Published by Packt Publishing Ltd. 32 Lincoln Road Olton Birmingham, B27 6PA, UK. ISBN 978-1-847191-82-3 www.packtpub.com

Cover Image by Vinayak Chittar ([email protected])

Credits Author Ric Shreves Reviewer Dave Myburgh Senior Acquisition Editor Douglas Paterson

Project Manager Patricia Weir Indexer Hemangini Bari Proofreaders Harminder Singh Chris Smith

Development Editor Rashmi Phadnis

Production Coordinator Aparna Bhagat

Technical Editor

Shantanu Zagade

Ajay S. Cover Designer Editorial Team Leader Mithil Kulkarni

Aparna Bhagat

About the Author Ric Shreves is a partner in water & stone (www.waterandstone.com), a web

development company that specializes in open-source content management systems. He works primarily as a consultant and business systems analyst and is currently on extended assignment with Peace Dividend Trust. He lives in Bali with his wife Nalisa, one dog, two cats, three turtles, and a mind-boggling number of fish. First and foremost, I thank my loving wife Nalisa for her support and patience. It would also be remiss of me to fail to acknowledge my friend (and editor at ComputerWorld) Stefan Hammond, who provides more than a modicum of support and encouragement—together with much-needed reality checks.

About the Reviewer Dave Myburgh started out in computers when entire operating systems ran

on a single floppy disk and 640kb of RAM was a lot! He studied to become a molecular biologist, but never lost his passion for computers. Later, he ran a successful computer company for a couple of years in South Africa, before moving to Canada with his wife. He went back to science on his arrival in Canada, and since discovering Drupal almost two years ago, he has once again started his own company, MybesInformatik. He loves working with Drupal, and is quite handy at theming, as well as hacking modules to make them do what he wants (sometimes, patches even get submitted back to the community). Now, he divides his time—unevenly—between family and Drupal. I would like to thank Dries and the Drupal community for making Drupal what it is today. Without you guys and gals, I'd probably still be "doing static"—I can't wait for Drupal 6! I'd also like to thank my wife for putting up with my frequent late nights in front of the computer. I tell her it's work, but in reality, it's a lot of fun—just don't tell her I told you that.

Table of Contents Preface Chapter 1: The Elements of a Drupal Theme What is a Theme? What is a Templating Engine? The Range and Flexibility of Drupal Themes What You See on the Screen The Big Picture: How Drupal Displays a Page The Importance of Themes in Drupal Key Concepts Build with Blocks Intercept and Override

1 5

5 6 7 8 10 12 12

14 16

The Contents of the Drupal Distro 17 The Theme Files 21 The Files of a PHPTemplate Theme 22 The Files of a Pure PHP Theme 23 Summary 24

Chapter 2: Theme Set Up and Configuration 25

Finding Additional Themes 25 Installing an Additional Theme 28 Configuring a Theme 32 Theme-Specific Configuration Options 33 Global Configuration Settings 37 Managing Modules and Blocks 38 The Module Manager 38 The Blocks Manager 40 Adding PHP to Blocks 45 Theming in Action: Dressing Up Garland 47 Set the Color Scheme 48

Table of Contents

Change Display Settings Upload Logo Global Configuration Enable Modules Manage Blocks Add Some Dummy Content and Links Set Access Levels Create a Custom Block Set Block Visibility Uninstalling Themes Summary

Chapter 3: Working with Theme Engines What is PHPTemplate? How does it Work? Getting Started with PHPTemplate A Look at the Theme Engine Files

A Look at the Key PHPTemplate File Contained in the Theme Two Contrasting Examples

A Basic PHPTemplate Theme—Gagarin A More Complex PHPTemplate Theme—Garland

Alternative Theme Engines PHPTAL Smarty PHP XTemplate Installing Additional Theme engines Summary

Chapter 4: Style Sheets and Themeable Functions A Guide to Drupal Style Sheets Identifying Themeable Functions A Guide to Themeable Functions Aggregator Module Functions Block Module Functions Book Module Functions Color Module Functions Comment Module Functions Drupal Module Functions Filter Module Functions Form Functions Forum Module Functions

[ ii ]

49 50 50 52 53 54 54 55 56 60 60

61

61 62 65 66

71

77

78 78

80 80 81 81 82 82

83

83 86 87 87 88 88 88 88 90 90 90 92

Table of Contents

Locale Functions Menu Functions Node Module Functions Pagination Functions Poll Module Functions Profile Module Functions Search Module Functions System Module Functions Taxonomy Module Functions Theme Functions Upload Module Functions User Module Functions Watchdog Module Functions Summary

92 93 93 94 94 95 95 96 96 97 99 99 100 100

Chapter 5: Intercepts and Overrides

Overriding the Default CSS CSS Overrides in Action Overriding Functions Where to Place Overrides How to Name Your Overrides Overrides in Action: How Garland Works Intercepting PHPTemplate Files Overriding Themeable Functions in Garland

Various Approaches to Overrides

Intercepting and Substituting Files Placing Overrides in the Theme's template.php File Modifying the PHPTemplate Engine Files Placing Overrides in Dedicated Files

Intercepting Template Files Summary

101

101 103 105 106 107 108

109 110

111

111 112 113 113

116 117

Chapter 6: Modifying an Existing Theme

119

Set Global and Theme Configuration Options Enable Modules Set User Access

128 128 129

Setting Up the Workspace Planning the Modifications Cloning a Theme First Look at Zen/Tao CSS in Zen/Tao Themeable Functions in Zen/Tao Turning Zen into Tao Configuring the Theme

[ iii ]

119 120 122 123 123 126 127 127

Table of Contents Create Dummy Content Set Up Menus Add New Regions Enable and Configure Blocks Position Blocks

129 129 131 133 134

Adapting the CSS

135

Adapting the Themeable Functions

144

Setting the Page Dimensions Formatting the New Regions Fonts and Colors Formatting the Sidebars and Footer Formatting the Menus Formatting the Search Box Formatting the Comments Form and Output Modifying template.php Creating a New Template File

Before and After Summary

136 136 137 140 141 142 143 144 145

147 148

Chapter 7: Building a New Theme Planning the Build Build a New PHPTemplate Theme Building a page.tpl.php File Insert DocType and Head Insert Body Tags Lay Out the Page Divisions Place the Functional Elements The Final page.tpl.php File

The style.css File A Look at Our New Theme Extending Your PHPTemplate Theme Working with Template Variables Variables Available in block.tpl.php Variables Available in box.tpl.php Variables Available in comment.tpl.php Variables Available in node.tpl.php Variables Available in page.tpl.php Intercepting and Overriding Variables Making New Variables Available

Dynamic Theming

149

149 152 153

156 157 158 158 165

169 178 179 179

179 180 181 181 182 184 185

185

Using Multiple Templates Dynamically Theming Page Elements Creating Dynamic CSS Styling

186 189 191

Build a New Pure PHP Theme Required Elements HTML Headers

193 194 196 [ iv ]

Table of Contents

Head of Document Implementing the Features

196 196

Primary and Secondary Links Sidebars

198 198

Main Content Area

199

Favicon Logo Site Name Site Slogan

196 197 197 197

Sidebar Left Sidebar Right

198 199

Title and Breadcrumb Trail Tabs Help Messages Content Region

199 199 199 200 200

Footer 200 Theme Closure 200 Overriding Functions 201 Summary 201

Chapter 8: Dealing with Forms 203

How Forms Work in Drupal 203 Modifying and Overriding Form Functions 206 Adding HTML via Function Attributes 207 Using form_alter() 207 Overriding Form Functions from template.php 209 Creating Custom Templates for Forms 211 Page Templates Block Templates Templates for Forms Output

211 212 213

Using form_alter() Override the Function Create a New Template Add a Node

214 215 215 215

Common Form Issues 214 Modifying Data Labels and Other Text 214

Modifying the Styling of a Form

216

Using form_alter() Override the Function Create a New Template

217 217 217

Using Images for Buttons 217 The Default Forms 218 The User Forms 219 The Login Forms 219 []

Table of Contents The User Registration Form The Request Password Form The Edit User Info Form

220 221 222

The Default Contact Form The Search Forms

223 224

The Poll Module Forms

228

The Theme Search Form The Block Search Form The Page Search Form The Advanced Search Form The Search Results Page

225 226 226 227 228

The Poll Block Form

229

The Poll Page Form 229 Summary 229

Appendix A 231 Index 239

[ vi ]

Preface This book sets out to explain the workings of the Drupal theme framework, and how you can use it effectively. The goal of this book is to explain basic principles, demonstrate practical solutions to common problems, and create a reference for theming. The book begins with an overview of the theme system and an explanation of what is included in the default Drupal distro. We next look at how you can squeeze the most out of the default system. The middle chapters discuss PHPTemplate and introduce using themeable functions and manipulating the Drupal style sheets. To illustrate the principles, we take a common theme and modify it. In the final chapters, we delve into creating themes from scratch and more advanced issues, like forms. For purposes of this text, we focus on the theme engine included in the default distro—PHPTemplate. Similarly, we only touch on creating themes in pure PHP, without the use of a theme engine. This book is all about controlling the presentation layer of your Drupal site; accordingly, we do not cover creating new modules, or writing custom functionality. The author of this text comes from a design background and has only basic programming skills. The explanations given, and the rational for many of the choices, reflect the author's background. In that light, this book may not always satisfy hardcore programmers who expect the technical issues to be explained in detail. It should, however, make the life of many designers a little easier and hopefully, with the reference materials we've included, find a lasting home on the shelves of many Drupal developers.

Preface

What This Book Covers

Chapter 1 covers the elements of a Drupal theme. It also takes a look at the contents of the Drupal distro and examines the different approaches of the default themes. Chapter 2 explains how to set up and configure a theme in Drupal. By way of example, we take a default theme and customize it using only the options provided by the system. Chapter 3 discusses the use of theme engines in general and the PHPTemplate engine in particular. This chapter also lays the groundwork for techniques to modify themes through the system's CSS and themeable functions. Chapter 4 takes an in-depth look at the system's default style sheets and the various themeable functions. Chapter 5 explains the process behind intercepting and overriding the Drupal style sheets and themeable functions. This is a key concept for obtaining full control over the presentation layer—without the necessity of modifying the core files. Chapter 6 provides a hands-on example of the techniques covered in the previous chapters by taking a default theme and then modifying it extensively. Chapter 7 covers creating a theme from scratch with the PHPTemplate theme engine and also looks at the basics of implementing a theme without a theme engine. Chapter 8 discusses modifying the look and feel of the many different forms in the Drupal system. Appendix A is a listing of all the selectors in the various style sheets.

What You Need for This Book

Throughout this book, we will assume that you have the following package installed and available: •

Drupal CMS (version 5.x)

Who is This Book for

The main requirements of this book are knowledge of HTML, CSS, and a touch of creativity! Though this book aims to make Drupal theming accessible to designers, theming in Drupal 5 involves writing some PHP code, and a basic knowledge of PHP will be helpful. []

Preface

Conventions

In this book, you will find a number of styles of text that distinguish between different kinds of information. Here are some examples of these styles, and an explanation of their meaning. There are three styles for code. Code words in text are shown as follows: "We can include other contexts through the use of the include directive." A block of code will be set as follows: title { color: #666; font-size: 1.8em; line-height: 2.0em; font-style: italic;

When we wish to draw your attention to a particular part of a code block, the relevant lines or items will be made bold: [ 73 ]

Working with Theme Engines

This next excerpt begins just inside the beginning of the body of the page The PHP statements here are all conditional—they will only produce output visible to the viewer when the conditions are true. This section includes the optional items controlled by the site administrator, such as the search box, the logo, the site name, and the site slogan. If the administrator has not enabled any of these items, they will not be displayed on the page: