Adding and Customizing Themes for Drupal ( Drupal 6 Introduction - Part 4)

/*--- holy mAcar00ns!! --- */

Quick and dirty notes for:

BUILDING ONLINE COMMUNITIES WITH DRUPAL, PHPBB, AND WORDPRESS, 2006 Douglass et al.
==================================================================================

Chapter 5 - Adding and Customizing Themes
==========================================

themes may have different features and options because they're based on difft theming engines

theming engines:
- phptemplate
- Smarty
- PHPTal
- XTemplate

look in templates/engines -- actually i don't think that exists any more in drupal 6

but apaprntye theare are difft theming engines.

iwell now he says that PHPTemplate is now the standard theming engine

never hack on files outside of your theme folder!

the book is pretty much dated, obsolete. i don't see any reason to use it, considering that the documetnation online is reasonably complete.

http://drupal.org/node/171194

i guess use it to get an overivew...

best to star tout by modifying theme. don't start from scratch.

drupal 6 theme anatomy:
-------------
http://drupal.org/node/171194
- folder with theme name
- .info file with theme name (better be unique to both themes and modules)
- template files (.tpl.php)
- template.php (not rquired, but use to keep logic out of templates -- preprocessors; override theme functions here), omit the closing php tag


Themable functions
----------
- can be overwriteten
- starts with theme_


# The contents of the .info file is cached in the database so altering it will not be noticed by Drupal. (Do not confuse this with the theme registry.) To clear it, do one of the following:

1. Clear button located at "Administer > Site configuration > Performance".
2. With devel block enabled (comes with devel module), click the "Empty cache" link.
3. Simply visit the theme select page at "Administer > Site building > Themes".

maybe that hd to do with our problem with the image assist and stuff?

.info file
-----
http://drupal.org/node/171205

To suppress a check box, omit the entry for it. However, if none are defined, all the check boxes will display due to the assumed defaults.

The example below lists all the available elements controlled by the features key. By commenting out the primary_links and secondary_links elements, their check boxes are suppressed and are not seen by site administrators.

features[] = logo
features[] = name
features[] = slogan
features[] = mission
features[] = node_user_picture
features[] = comment_user_picture
features[] = search
features[] = favicon
; These last two disabled by redefining the
; above defaults with only the needed features.
; features[] = primary_links
; features[] = secondary_links

Traditionally, themes default to using style.css automatically and could add additional stylesheets by calling drupal_add_css() in their template.php file. Starting in 6, themes can also add style sheets through their .info file.

stylesheets[all][] = theStyle.css


Traditionally, themes could add javascripts by calling drupal_add_js() in their template.php file. Starting in 6.x, themes can also add javascripts by adding lines to their .info file:

scripts[] = script.js

in the drupal documentaiton now:
Theming hooks implemented as functions provide speed. It is about five times faster than templates but they are difficult for designers who may be more familiar with working directly in xHTML.

For most theme developers, the registry does not have to be dealt with directly. Just remember to clear it when adding or removing theme functions and templates. Editing existing functions and templates does not require a registry rebuild.

(empty cache)

am rather confused by the themable functions becuase they don't actaully show up in the themes. it appears that they're usedi n modules not themes.

in the themes, what i'm seeing are phptemplate_ functions

the book says the main themable functions are:
theme_page
theme_node
theme_comment
theme_block
theme_box

in impelemtantion i think what actually happens is that the theme designer gturns these into .tpl.php files

so the overriding is sort of implicit. you're not actually calling the functions instead you overrie it by creating files called

page.tpl.php
node.tpl.php
comment.tpl.php
block.tpl.php
box.tpl.php

okay th ebook explains it better now:

the reason we see phptemplate_

when you want to call a themable function, you do
theme($function_name,[$params,...])

if you call:
theme('foo',$bar)

Then drupal looks in 3 namespaces:
1 - theme's namespace
fourseasons_foo($bar)
2 - theme engine's namespace
phptemplate_foo($bar)
3 - default namespace
theme_foo($bar)

#2 is recommended because it is portable. you can move the function to a difft theme or rename it. that's why everywher eyou see phptemplate_

good table on p158 showing examples of the above

it's good you can see here:
http://api.drupal.org/api/group/themeable/6

all the themable functions, with the default code. so you can actually just copy that code out and modify it rahte rthan starting from scratch. that would be hte best way.

i wish someone would turn the wordpress theme api documentation into an AIR app or perhaps a chm.

this is the default breadcrumbs:
function theme_breadcrumb($breadcrumb) {
if (!empty($breadcrumb)) {
return '';
}
}
?>


to override just copy and paste and modify it

function phptemplate_breadcrumb($breadcrumb) {
if (!empty($breadcrumb)) {
return '';
}
}
?>

or from fourseasons:
function phptemplate_breadcrumb($breadcrumb) {
if (!empty($breadcrumb)) {
return '';
}
}

very easy.

put in what you want. you can put an image in if you want.

and okay like i suspected, the template files are just a convenient way of doing it so that you don't have to put html into these functions.

page.tpl.php is required

PHPtemplate engine provides also:
block.tpl.php
box.tpl.php
comment.tpl.php
node.tpl.php

if these appear in your theme, they override the version in themes/engines/phptemplate -- not applicable to drupal 6

tags must be closed:






Theme engine provides to all:
------------------------------------
- $id -- e.g. allows each block to have unique id
- $zebra -- odd or even
- $is_front -- true if front page

in addition:

Variables available to specific templates
---------------------------------

block.tpl.php
--------------
- $block object
$block->content
$block->module -- name of module
$block->region -- left, right, etc.
$block->subject -- title
$block->delta -- number given to block by module
- $block_id -- uniquely identifies block w/in region
- $block_zebra -- like $zebra but rest for each block region

Apparently the default blocks used to be at engines/phptemplate/ but i don't se ethem so i think they must have taken them out of drupal 6

box.tpl.php
-------------
- $content
- $region
- $title

comment.tpl.php
--------
- $author
- $comment object
- $comment->subject
- $comment->comment (content)
- $comment->name (name of user)
- $comment->timestamp
- $comment->uid (user id)
- $comment->new (boolean) -- has user viewed before?
- $content
- $date -- formatted
- $links -- controls (reply,edit,delete) as single string
- $new -- says "new" or "" if not new
- $picture - authors picture
- $submitted -- "Submitted by user_link on date."
- $title -- permalink

These are all listed in the documentation so i won't copy out anymore. See:
http://drupal.org/node/11816

node.tpl.php
page.tpl.php

so the same templates as in the old version. see the drupal docs for the variables available.

the drupal page is actually for version 5, they haven't done drupal 6 tehme developers gide yet really. but here's what htey have:

http://drupal.org/node/226776

common to all:
id
The placement of the template. Each time the template is used, it is incremented by one.
$zebra
Either "odd" or "even". Alternate each time the template is used.
$directory
The theme path relative to the base install. example: "sites/all/themes/myTheme"
$is_admin
Boolean returns TRUE when the visitor is a site administrator.
$is_front
Boolean returns TRUE when viewing the front page of the site.
$logged_in
Boolean returns TRUE when the visitor is a member of the site, logged in and authenticated.
$db_is_active
Boolean returns TRUE when the database is active and running. This is only useful for theming in maintenance mode where the site may run into database problems.
$user
The user object containing data for the current visitor. Some of the data contained here may not be safe. Be sure to pass potentially dangerous strings through check_plain.


they say the variables specific to individual template files are:
Variables specific to the template are documented inside the file.

but dont' sepcify really which file. confusing. don't know wher eto look.

http://drupal.org/node/226776

okay here they are:
http://drupal.org/node/190815

they're now provided by core, not in phptemplate directory

for box:
http://api.drupal.org/api/file/modules/system/box.tpl.php/6/source

for comment:
http://api.drupal.org/api/file/modules/comment/comment.tpl.php/6/source

for page:
http://api.drupal.org/api/file/modules/system/page.tpl.php/6/source

for node:
http://api.drupal.org/api/file/modules/node/node.tpl.php/6/source

for block:
http://api.drupal.org/api/file/modules/system/block.tpl.php/6/source

awesome. so we'll take what we see in hte book with a grain of salt and rely ont he actual docmentation for that.

just use the book for an overview.


Suggestions only work when it is placed in the same directory as the base template. In other words, trying to get comment-blog.tpl.php to work, comment.tpl.php also needs to exist inside your theme and in the same directory.

Custom suggestions beyond the ones listed below can be created.

sugegstions are like since node.tpl.php is very general, you can do:
node-TYPE_.tpl.php

for example:
node-story.tpl.php

to pass extra variables to the template, use template.php:
function _phptemplate_variables($hook, $vars) {
..
return $vars;
}

the $vars are the exsting vars. you can do what you want with them or add new ones

for example:
function _phptemplate_variables($hook,$vars) {
switch($hook) {
case 'block':
// generate random color
$color = '#';
for ($i=0;$<3;$i++) {
$r=dechex(rand(0,255));
$color .= strlen($r) < 2? '0'.$r : $r;
}

// add $color variable to $vars array
$vars['color'] = $color;
break;
}
return $vars;
}

most page execution has been run by the time this gets called, so use this for superficial stuff--visual elements and layout.

An alternative to overriding a themable function using a function and if you can't use one of hte popular tpl.php files is to create your own. breadcrumb.tpl.php for exmaple.

to do this. create the template file, and then create a function inside yoru teme's template.php

function phptemplate_breadcrumb($breadcrumb) {
return _phptemplate_callback('breadcrumb', array('breadcrumb' => $breadcrumb));
}

callback function is phptemplate's way of finding tpl.php files.

the second parameter is the array of values you awnt to pass, usually the same as what the themable function requires

well i'm feeling good about drupal. i thik i understand the theming system now, whichi s very improtant.

Adding Custom Regions for BLocks
------------------------------
can't find any examples in our intalled themes

http://drupal.org/node/171224

In Drupal 5 and below, regions were declared with ThemeName_regions() or EngineName_regions(). It has been deprecated in Drupal 6.

the book has us do that. in template.php, for example do:
function bluemarine_regions() {
return array('content_top' => t('content top'));
}
and then you do inside the page.tpl.php where you want it

apparently that's deprecated now.

i think now they want you to do all that in the .info file

The block regions available to the theme are defined within .info files. It must be specified with the key of 'regions' followed by the internal "machine" readable name in square brackets and the human readable name as the value, e.g., regions[theRegion] = The region label. If none are defined, the following values are assumed.

regions[left] = Left sidebar
regions[right] = Right sidebar
regions[content] = Content
regions[header] = Header
regions[footer] = Footer

Adding a custom region prevents the defaults from being used. If you want to keep the defaults in addition to custom regions, manually add in the defaults.

let's try adding a custom region to four seasons.

well it ididn't seem to work.

# The contents of the .info file is cached in the database so altering it will not be noticed by Drupal. (Do not confuse this with the theme registry.) To clear it, do one of the following:

1. Clear button located at "Administer > Site configuration > Performance".
2. With devel block enabled (comes with devel module), click the "Empty cache" link.
3. Simply visit the theme select page at "Administer > Site building > Themes".


now it shows up. let's see if it works though.

uyeah it works. awesome. that means we can put blocks anywhere on the page and can make a real site then. awesome.

CSS
---
style.css is automatically included

if you want additional stylesheets, not sure. i think what he tells us is probably dated now. he said in template.php do
theme_add_style($stylesheet,$media='all');

that's the simple way. but the way he recommends is to to add it to _phptemplate_variables() function
switch($hook) {
// theme('block') gets called on every apge load so we use 'block'
theme_add_style(drupal_get_path('theme',$theme) . '/layout.css');
break;

don't know if that's recommended anymore.

in all the themes i looked at when they had ie fixes, they just hardcoded the .css file location into the page.tpl.php
putting it inside conditional comments

drupal.css
-----
apparently no such hting abmore but ther earea lot of default css stylesheets. don't delete any of them you'll get a 404 and problems. instead override them if necessary in template.php file

well ignore it for now. p180 if eer needed

favicon
---
apparently just putting a favicon.ico file in your theme folder will do the trick

Sections Module
------
- lets difft sections of site have difft themes

Taxonomy_Theme module let's you do smoething simliar based on the taxonomy but there's no versoin for drupal 6

http://drupal.org/project/taxonomy_theme

Labels: cms, drupal, drupal6, php

all your bases ar--