Drupal Themes Create a new theme for your Drupal website with a clean layout and powerful CSS styling Ric Shreves BIRMINGHAM - MUMBAI Drupal 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 (vinayak.chittar@gmail.com) 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 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 5 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 Appendix A The following is a listing of all the selectors in the various style sheets This list reflects the default distro and is current for Drupal 5.2 /modules/system/admin.css Concerns primarily the elements unique to the administration interface Appendix A /modules/aggregator/aggregator.css Relates to the Aggregator Module /modules/block/block.css Relates to the formatting of Blocks /modules/book/book.css Concerns Book node content [ 232 ] Appendix A /modules/color/color.css Relates to the Color Module /modules/comment/comment.css A single selector relevant to Comments /modules/system/default.css Provides basic HTML style definitions common to many areas in the system [ 233 ] Appendix A /misc/farbtastic/farbtastic.css Relates to the Farbtastic color picker /modules/forum/forum.css Concerns the Forum Module /modules/help/help.css Classes for Help items [ 234 ] Appendix A /modules/locale/locale.css One selector for the Locale Module /misc/maintenance.css Relates to the Maintenance page /modules/node/node.css Provides selectors for the Nodes [ 235 ] Appendix A /modules/poll/poll.css Concerns the Polls Module /modules/search/search.css Styling for the various Search functions [ 236 ] Appendix A /modules/system/system.css A collection of common styles [ 237 ] Appendix A /modules/tracker/tracker.css Selectors for the Tracker Module /modules/user/user.css Relates to the User and Profile Modules /modules/watchdog/watchdog.css Concerns the Watchdog Module [ 238 ] Index A additional theme finding 25-27 installing 28-32 Aggregator Module functions theme_aggregator_block_item 87 theme_aggregator_feed 87 theme_aggregator_page_item 87 theme_aggregator_page_list 87 theme_aggregator_summary_item 87 approaches, overrides files, intercepting 111 files, substituting 111 overrides, placing in dedicated files 113-115 overrides, placing in theme template.php file 112 PHPTemplate engine files, modifying 113 B Block Module functions theme_block_admin_display 88 blocks managing 38 PHP, adding 45, 46 blocks manager 40 Book Module functions theme_book_admin_table 88 theme_book_export_html 88 theme_book_navigation 88 C Color Module functions theme_color_scheme_form 88 Comment Module functions theme_comment 89 theme_comment_admin_overview 89 theme_comment_block 89 theme_comment_controls 89 theme_comment_flat_collapsed 89 theme_comment_flat_expanded 89 theme_comment_folded 89 theme_comment_post_forbidden 89 theme_comment_post_preview 89 theme_comment_thread_collapsed 89 theme_comment_thread_expanded 89 theme_comment_view 89 theme_comment_wrapper 89 common form issues, Drupal data labels, form_alter() used 214 data labels, function overriding 215 data labels, modifying 214 data labels, new template creating 215 data labels, node adding 215, 216 images, using for buttons 217, 218 styling of form, form_alter() used 217 styling of form, function overriding 217 styling of form, modifying 216 styling of form, new template creating 217 CSS adapting, Tao theme colors, setting 137, 138 comments, formatting 143 font styles, setting 137, 138 footer, formatting 141 form, formatting 143 horizontal menu, formatting 142 menus, formatting 141 new regions, formatiing 136 output, formatting 143 page dimensions, setting 136 search box, formatting 142 sidebars, formatting 141 vertical menu, formatting 142 D default forms, Drupal default contact forms 223 Poll module forms 228 Poll module forms, Poll Block Form 229 Poll module forms, Poll Page Form 229 search form, Advanced Search Form 227 search form, Block Search Form 226 search form, Page Search Form 226 search form, search results page 228 search form, Theme Search Form 225 search form, versions 224 search forms 224 user forms 219 user forms, Edit User Info Form 222 user forms, Login Block Form 219 user forms, Login Forms 219 user forms, Login Page Form 220 user forms, Request Password Form 221 user forms, User Registration Form 220 Dreamweaver 120 Drupal additional theme, finding 25 additional theme, installing 28 common form issues 214 CSS overrides, working 103, 104 default CSS, overriding 101, 102 default form 218 form functions 203 form functions, Login Form 204, 205 form functions, modifying 206 form functions, override creating 204 form functions, overriding 206 forms, working 203 intercepts 16, 101 overrides 16, 101 overriding functions 105 template files, intercepting 116, 117 themeable functions, identifying 86 Drupal distro about 17 concepts 17, 20 themes 17, 20 Drupal Module functions theme_client_list 90 Drupal style sheets about 83 admin.css 84 admin.css, selectors 231 aggregator.css 84 aggregator.css, selectors 232 block.css 84 block.css, selectors 232 book.css 84 book.css, selectors 232 color.css 84 color.css, selectors 233 comment.css 84 comment.css, selectors 233 default.css 85 default.css, selectors 233 farbtastic.css 85 farbtastic.css, selectors 234 forum.css 85 forum.css, selectors 234 held.css 85 held.css, selectors 234 locale.css 85 locale.css, selectors 235 maintenance.css 85 maintenance.css, selectors 235 node.css 85 node.css, selectors 235 poll.css 85 poll.css, selectors 236 search.css 85 search.css, selectors 236 selectors 231 style.css 86 system.css 86 system.css, selectors 237 tracker.css 86 tracker.css, selectors 238 user.css 86 user.css, selectors 238 watchdog.css 86 watchdog.css, selectors 238 [ 240 ] Drupal theme about 5, blocks 9, 10 building 149, 151 files 21, 22 flexibility 7, key concepts 12 modules 14 page, displaying 10-12 PHPTemplate theme, files 22, 23 pure PHP theme, files 23, 24 range 7, regions 9, 10 significance 12 uninstalling 60 dynamic theming, PHPTemplate theme about 185 CSS styling, creating 191 different template, using for group of pages 188 dynamic selectors, using for nodes 192 elements, associating with front page 189 multiple templates, using 186 page elements 189 section template, multiple templates using 186 selector, changing 192 separate admin theme, multiple templates using 186 specific template, assigning to a specific page 188 specific template, designating to a specific user 189 styling blocks 190, 191 styling modules 190, 191 styling nodes 191 unique homepage template, creating 188 E existing theme, modifying about 119 modifications, planning 120, 121 theme, cloning 122, 123 workspace, setting up 119, 120 F Filter Module functions theme_filter_admin_order 90 theme_filter_admin_overview 90 theme_filter_tips 90 theme_filter_tips_more_info 90 Form functions theme_button 90 theme_checkbox 90 theme_checkboxes 90 theme_date 91 theme_fieldset 91 theme_file 91 theme_form 91 theme_form_element 91 theme_hidden 91 theme_item 91 theme_markup 91 theme_password 91 theme_password-confirm 91 theme_radio 91 theme_radios 91 theme_select 92 theme_textarea 91 theme_textfield 92 theme_token 92 form functions, Drupal block templates 212 custom templates, creating 211 form_alter(), using 207-209 HTML, adding via function attributes 207 overriding, from template.php 209, 210 page templates 211 templates for form output 213 Forum functions theme_forum_display 92 theme_forum_icon 92 theme_forum_list 92 theme_forum_topic_list 92 theme_forum_topic_navigation 92 functional elements, PHPTemplate theme breadcrumb trail, main content area 162 content Region, main content area 164 feed icons, footer 164 [ 241 ] footer 164 footer Region, footer 165 header region, header wrapper 161 header wrapper 159 help, main content area 163 logo, header wrapper 159 main content area, main wrapper 162 main wrapper 162 messages, main content area 163 primary links, inserting 161 secondary links, inserting 159 sidebar left, main wrapper 162 sidebar right, main wrapper 164 site mission, header wrapper 161 site name, header wrapper 160 site slogan, header wrapper 160 tabs, main content area 163 template closing tag, inserting 165 theme search box, header wrapper 160 title, main content area 163 K key concepts, Drupal theme blocks, building with 14, 16 intercept 16 multiple themes 13 override 16 L Locale functions theme_locale_admin_manage_screen 92 M Menu functions theme_menu_item 93 theme_menu_item_link 93 theme_menu_links 93 theme_menu_local_task 93 theme_menu_tree 93 module manager 38 modules managing 38 N Node Module functions theme_node_admin_nodes 93 theme_node_filter_form 93 theme_node_filters 93 theme_node_form 93 theme_node_list 93 theme_node_log_message 94 theme_node_preview 94 theme_node_search_admin 94 O overrides, Drupal approaches 111 Garland theme, PHPTemplate files intercepting 109 Garland theme, themeable functions 110 Garland theme, working 108 overriding fuctions, Drupal overrides, approaches 111 overrides, naming 107 overrides, placing 106 P page.tpl.php file, PHPTemplate theme tag, inserting 157 tag, inserting 156 DocType, inserting 156 functional elements, placing 158 layout 158 raw page.tpl.php file 165-168 Pagination functions theme_pager 94 theme_pager_last 94 theme_pager_link 94 theme_pager_list 94 theme_pager_next 94 theme_pager_previous 94 PHP adding, to blocks 45 PHPTemplate about 61 contrasting examples 77 [ 242 ] Gagarin, PHPTemplate theme 78 Garland, PHPTemplate theme 78 key files 65 PHPTemplate file 71 PHPTemplate file, example 71-76 theme engine files 66 working 62-65 PHPTemplate theme about 22 building 152 extending 179 functional elements, placing 158 new theme 178 page.tpl.php file, building 153, 155 style.css file 169 PHPTemplate theme, extending additional variables 185 dynamic theming 185 template variables, working with 179 variables, intercepting 184 variables, overidding 184 variables in block.tpl.php 179, 180 variables in box.tpl.php 180 variables in comment.tpl.php 181 variables in node.tpl.php 181 variables in page.tpl.php 182 Poll Module functions theme_poll_bar 95 theme_poll_results 95 theme_poll_view_voting 95 Profile Module functions theme_profile_block 95 theme_profile_listing 95 pure PHP theme building 193 pure PHP theme, building document header 196 features, favlcon 196 features, implementing 196 features, logo 197 features, site name 197 features, site slogan 197 footer 200 HTML headers 196 main content area 199 main content area, breadcrumb trail 199 main content area, content Region 200 main content area, help 199 main content area, messages 200 main content area, tabs 199 main content area, title 199 overriding functions 201 primary links 198 secondary links 198 sidebar left 198 sidebar right 199 sidebars 198 theme.engine, elements 194 theme_features(), features 195 theme_features(), theme.engine functions 194 theme_regions(), theme.engine functions 194, 195 theme course 200 S Search Module functions theme_search_block_form 95 theme_search_item 95 theme_search_page 95 theme_search_theme_form 95 System Module functions theme_admin_block 96 theme_admin_block_content 96 theme_admin_page 96 theme_system_admin_by_module 96 theme_system_modules 96 theme_system_modules_uninstall 96 theme_system_theme_select_form 96 theme_system_themes 96 T Tao theme about 123 configuring 127 CSS 123 CSS adapting 135 themeable functions 126 themeable functions, adapting 144 Tao theme, configuring blocks, assigning to regions 134 blocks, configuring 133 blocks, enabling 133 [ 243 ] changes, saving 129 dummy content, creating 129 global configuration settings 128 menus, setting up 129, 130 modules, enabling 128 new regions, adding 131, 132 theme configuration settings 128 user access setting 129 Taxonomy Module functions theme_taxonomy_term_select 96 templating engine theme, configuring about 32, 47, 48 access levels, setting 54 blocks, managing 53 block visibility, setting 56-59 color picker, theme-specific configuration options 34 color scheme, setting 48 custom block, creating 55 display settings, changing 49 enable/disable page elements, theme-specific configuration options 35 favicon settings, theme-specific configuration options 36 global configuration 50 global configuration settings 37, 38 logo, uploading 50 logo settings, theme-specific configuration options 36 modules, enabling 52 theme-specific configuration options 33 themeable functions Aggregator Module functions 87 Block Module functions 88 Book Module functions 88 Color Module functions 88 Comment Module functions 88 Drupal Module functions 90 Filter Module functions 90 Form functions 90 Forum Module functions 92 identifying 86 Locale functions 92 Menu functions 93 Node Module functions 93 Pagination functions 94 Poll Module functions 94 Profile Module functions 95 Search Module functions 95 System Module functions 96 Taxonomy Module functions 96 Theme Module functions 97 Upload Module functions 99 User Module functions 99 Watchdog Module functions 100 themeable functions, Tao theme template.php, modifying 144 template file, creating 145, 146 theme engine files, PHPTemplate block.tpl.php 66 box.tpl.php 67 comment.tpl.php 67 default.tpl.php 67 node.tpl.php 68 theme engines alternative theme engines 80 installing 82 PHPTAL 80 PHPTemplate 61 PHP XTemplate 81 Smarty 81 Theme functions theme_block 97 theme_blocks 97 theme_box 97 theme_breadcrumb 97 theme_closure 97 theme_feed_icon 97 theme_get_setting 97 theme_help 97 theme_image 97 theme_install_page 97 theme_item_list 97 theme_links 97 theme_maintenance_page 98 theme_mark 98 theme_more_help_link 98 theme_node 98 theme_page 98 theme_placeholder 98 theme_process_bar 98 theme_status_messages 98 [ 244 ] theme_submenu 98 theme_table 98 theme_table_select_header_cell 98 theme_tablesort_indicator 98 theme_username 98 theme_xml_icon 98 U Upload Module functions theme_upload_attachments 99 theme_upload_form_current 99 theme_upload_form_new 99 User Module functions theme_user_admin_account 99 theme_user_admin_new_role 99 theme_user_admin_perm 99 theme_user_filter_form 99 theme_user_filters 99 theme_user_list 99 theme_user_picture 99 theme_user_profile 99 W Watchdog Module functions theme_watchdog_form_overview 100 Z Zen theme about 120, 123 changes, implementing 121 cloning 122 CSS 123 CSS files 124 themeable functions 126 turning into Tao theme 127 [ 245 ] .. .Drupal Themes Create a new theme for your Drupal website with a clean layout and powerful CSS styling Ric Shreves BIRMINGHAM - MUMBAI Drupal Themes Create a new theme for your Drupal website. .. 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... 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