Geeklog Documentation - Theme How-To

# Creating a Theme for Geeklog

Creating a theme for Geeklog is easy and quite fast. If you can manipulate HTML files then you can create a theme! There's no need to learn PHP.

## Creating a theme

First, copy an existing theme that is most similar to what you want to implement (if one exists). If what you will do is radically different (and we hope so!) then copying any one will do. Copy the existing theme to the name you want your theme to have (please, no spaces in the theme name):

`cp -R /path/to/geeklog/public_html/layout/Yahoo /path/to/geeklog/public_html/layout/My_Theme_Name_No_Spaces`

Change into your new theme directory:

`cd /path/to/geeklog/public_html/layout/My_Theme_Name_No_Spaces`

Now edit the templates to suit your needs. Keep in mind that templates, generally are partial HTML files. The directory you just created holds ALL templates Geeklog needs but you will only need to modify a small few to make a huge impact on the look.

In particular these are the templates you will undoubtedly want to change:

- header.thtml
- footer.thtml
- blockheader.thtml
- blockfooter.thtml
- storybody.thtml
- storybodytext.thtml
- featuredstorybody.thtml
- featuredstorybodytext.thtml
- style.css

### How themes work

When rendering a theme, Geeklog starts with `header.thtml` which builds the site's header and then goes on to include the left column of blocks (look for the variable {left_blocks} and the `leftblocks.thtml` file). The middle part of a site consists of the stories which are built using the `storytext.thtml` and `storybodytext.thtml` (for normal stories) and `featuredstorytext.thtml` and `featuredstorybodytext.thtml` (for featured stories) template files. The `footer.thtml` file then builds the right column of blocks (variable {right_blocks}, file `right_blocks.thtml`) and the site's footer. Blocks themselves consist of the `blockheader.thtml` and `blockfooter.thtml` files.

The above only described how Geeklog's main page and stories are rendered. More templates exist for the various editors and lists you will see in Geeklog, as well as for the calendar and almost every other part of Geeklog.

There is currently no complete list available that explains which template file is used for which part of Geeklog. However, in most cases the use should be obvious when you have a look at the file and directory names in your theme's layout directory. If you're unsure which template file is used to render a certain part of Geeklog, have a look at the URL. You will notice the name of a PHP file there, e.g. the `users.php` file when you view a user's profile. Open that file and search for '`.thtml`'. For the profile you will find these lines (in `function userprofile()`):

> `$user_templates = new Template ($_CONF['path_layout'] . 'users');
> $user_templates->set_file (array ('profile'=>'profile.thtml', 'row'=>'commentrow.thtml', 'strow'=>'storyrow.thtml'));`

You don't need to understand PHP code to see that this uses the template files `profile.thtml`, `commentrow.thtml`, and `storyrow.thtml`. The first line also indicates that these are taken from the `users` directory within the theme's layout directory.

### Testing a theme and further information

After you have edited your themes, you are now ready to test it out. Simply go to http://mygeeklogsite/users.php?mode=preferences - in the theme drop-down select your newly created theme (note the name of your theme is the same name as the directory for your theme).

Finally, you may want to update the logo and other images in your theme's images directory.

For the template system we are using PHPLib's template class (http://phplib.sourceforge.net/). Read their documentation and, optionally, look at /path/to/geeklog/system/classes/template.class.php to see how it is implemented. Even with this knowledge it may not be clear which templates are used in conjunction with one another (i.e. `storybody.thtml` and `storybodytext.thtml` together make up the complete format of a single story). If you have questions join our mailing list at http://lists.geeklog.net/listinfo/geeklog-users or check us out in IRC at irc.freenode.net in #geeklog.

### Tips and tricks

Themes and WYSIWG editors: The template files used by Geeklog are not complete HTML files - they contain only parts of the HTML that Geeklog puts together to build a proper HTML document. This, however, seems to confuse some WYSIWYG HTML editors and some of them tend to add the HTML which they think is missing from the file, thus making it unusable for Geeklog.
We suggest you use a simple text editor to edit your themes.

PHP in themes: You can use PHP in the header of a theme, i.e. in the `header.thtml` file. If you want to use custom PHP functions, you can put them in the file `functions.php` within your themes directory.

Different look for left and right blocks: You can give the blocks on the left and right a different look. See this story on the Geeklog homepage for details.

## Theme changes in Geeklog 1.3.7

Please note that all the following changes are optional. Themes made for Geeklog 1.3.6 will work just fine with Geeklog 1.3.7 - no changes are necessary.

### New features and improvements

- Theme-based topic icons are now supported by setting `$_THEME_URL` in the theme's `functions.php` file. The variable should point to a directory that has the same hierarchy as Geeklog's images directory (note that the path to topic images is stored relative to Geeklog's public_html directory).
  Example: `$_THEME_URL = $_CONF['layout_url'];`
- The `$_BLOCK_TEMPLATE` "hack" can now be applied to the What's Related and Story Options blocks, as well. Use `whats_related_block` and `story_options_block` as the block names.
- The What's Related and Story Options blocks are now available as separate variables using `{whats_related}` and `{story_options}`, respectively (the `{whats_related_story_options}` variable for both blocks is still available).
- Several new variables can now be used in the story templates, e.g. `{contributedby_fullname}` for the full name of a story author and `{contributedby_photo}` for his/her user photo.
- When the new config variable `$_CONF['showfirstasfeatured']` is set to 1, then the first story on every page is rendered using the template files for featured stories, even when the story is not marked as featured.

### Other changes

- The template file `admin/plugins/installform.thtml` has been removed since it isn't used any more.
- Two new optional template files, `admin/plugins/newpluginlist.thtml` and `admin/plugins/newlistitem.thml`, have been added to support formatting of the list of plugins which haven't been installed yet. If these files do not exist, hard-coded HTML is used to present the list.
- The template file `admin/link/listitem.thtml` has been changed so that all the links are clickable.
- `COM_pollResults()` doesn't use the side block templates any more when called from `pollbooth.php`. Therefore, you can now use different layouts whether the poll results are displayed in a side block or on the separate poll results and comments page.
- Removed the Normal / Archive / Refreshing drop down menus from the admin story and poll editors of the themes that ship with Geeklog. The setting of this dropdown isn't used in Geeklog anyway and has just confused users in the past ... (files `admin/story/storyeditor.thtml` and `admin/poll/polleditor.thtml`)

## Theme changes in Geeklog 1.3.6

There have been a lot of changes in the themes for 1.3.6 to get rid of the last pieces of hard-coded english texts so as to make localisation easier. Most of these changes have been made in the Admin editors (`admin` directory) and the calendar (`calendar` directory). If you created your own theme for an earlier version of Geeklog, we recommend that you copy over these two directories from one of the themes that come with Geeklog (choose one that is similar to your own theme or which it was originally based on). It seems like most Geeklog themes didn't change these files anyway, so this shouldn't be too much of a hassle ...

### Other changes

- The template file `admin/mail/mailform.thtml` has been added. This form for sending emails to other users of the site was previously hard-coded into Geeklog.
  If you followed the above advice and copied over the `admin` directory to your theme, you got this file already.
- Two new files `menuitem_last.thtml` and `menuitem_none.thtml` have been added to give theme authors better control over the items in menu bars ({menu_elements} and {plg_menu_elements} variables in `header.thtml`). The template file `menuitem.thtml` is now used to render the first and any following menu items - with the exception of the last menu item, which is rendered using `menuitem_last.thtml`. If there are no menu elements for a menu bar, `menuitem_none.thtml` is used.
- New files have been added and the existing files have been changed for the links section (`links` directory). Again, we recommend to just copy over those files from one of the themes that ship with Geeklog.
  The new files are: `categoryactivecol.thtml`, `categorycol.thtml`, `categorynavigation.thtml`, `categoryrow.thtml`, `pagenavigation.thtml`
- The user profile has been extended to include a list of the last 10 stories as well as the total numbers of stories and comments posted by that user. Have a look at the file `users/profile.thtml` to see the changes or just copy that file over from one of the themes that ship with Geeklog. You should also copy over the file `users/storyrow.thtml` which describes the block for the last 1o stories.
- The Classic theme has been updated to have an "Edit" link (for StoryAdmins) in every story now.
  Files changed: `storybodytext.thtml`, `featuredstorybodytext.thtml`
- In the Classic and Digital Monochrome themes the "contact" link now points to the form to send an email to the admin user instead of using a `mailto:` link with the site's email address from `config.php`.

### CSS changes

- The underscore '_' is not a valid character in CSS. Therefore, some class names used by the Geeklog calendar have been changed to use the dash '-' instead. You may need to change your stylesheet accordingly.
  Names that changed: cal-oldday, cal-today, cal-futureday, cal-nullday, weekview-curday, weekview-offday
- A new class named pagenav can be used to format the paged navigation.
  Please note that this change was made after the release of Geeklog 1.3.6rc1 and affects the use of the paged navigation in `admin/user/userslist.thtml` and `links/links.thtml`: In 1.3.6rc1, the navigation was wrapped in <p> tags in those files. As of Geeklog 1.3.6 however, the function producing the navigation will wrap it in a <div> automatically.

Note: Theme authors are encouraged to specify a character set in the `header.thtml` of their themes like this:

> `<meta http-equiv="Content-Type" content="text/html; charset={charset}">`

Geeklog will replace the `{charset}` variable with the proper character set based on the currently used language file. Also make sure that you put the above line before the `<title>` tag in the `<head>` section of your `header.thtml` file.