Geeklog

Geeklog Documentation - Theme How-To

(see below for a list of theme changes in recent Geeklog versions - Note: not all changes may be listed)

Creating a Theme for Geeklog

Two types of themes exist in Geeklog. A regular Theme that includes all the required files under its directory, and a Child Theme. A Child Theme is based on a regular Theme (not on another Child Theme) and only include any changed files of the regular Theme within it's own directory. If Geeklog's theme engine doesn't find a required file in the Child Themes directory, it then falls back and uses the assigned regular theme to find the file it needs. Child Themes are a great way for theme developers to make minor adjustments to a regular Theme while keeping updating the theme simple when it is time to upgrade Geeklog itself, since any upgrades to the regular Theme will automatically be included in the Child Theme.

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 regular 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/denim /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:

How themes work

When rendering a theme, Geeklog starts with index.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 articles which are built using the articletext.thtml and articlebodytext.thtml (for normal articles) and featuredarticletext.thtml and featuredarticlebodytext.thtml (for featured articles) template files. The index.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 describes how Geeklog's main page and articles are rendered. More templates exist for the various editors and lists you will see in Geeklog, as well as for plugins like 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. Enabling the Geeklog Configuration option 'template_comments' will also show any template comments (marked by {# foo #}) in the source of the html file. All Geeklog themes and Plugins included with the Geeklog Install also include template comments which shows which template file is being used. So enabling this config option and then viewing the source of the HTML page, you will find comments right in the code that shows you when a certain template file is being used.

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'=>'articlerow.thtml'));

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

An incomplete list of variables that can be used in templates files is also included.

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/usersettings.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.

Tips and tricks

Themes and WYSIWYG 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.

XHTML: Geeklog will create XHTML-compliant tags when asked to do so. You can also create themes that are both HTML and XHTML compliant. Please see the article Themes and XHTML entry on the Geeklog Wiki for more information.

Logic Processing, Autotags, and PHP in themes: Please see our wiki article Caching Template Library for more information and examples of how to add PHP, Mobile Detection, Autotags, and even logic processing into template files.

Error Message: Since Geeklog 1.4.1 it is possible to control what HTML is displayed to non-root users in the event of an error occurring (a crash bug). To do so, you need to enable the config option $_CONF['rootdebug'] found in the siteconfig.php file.

Creating a Child Theme

For an example of a Child Theme and how they work please see the "denim_curve" theme which is based on the "denim" regular theme (also called the Parent Theme). Please note the extra settings and changes required in the "denim_curve" functions.php file.

Changes

Theme changes in Geeklog 2.2.2

Theme changes in Geeklog 2.2.1

Theme changes in Geeklog 2.2.0

Theme changes in Geeklog 2.1.3

Theme changes in Geeklog 2.1.2

Theme changes in Geeklog 2.1.1

New template functionality for plugins has been added to Geeklog which when supported allow for specific theme templates for plugins. This means a plugin or theme can include plugin templates designed for individual themes. These templates can be included with either the plugin itself, or the theme, or in both places at once. All of Geeklogs core plugins support this new feature. To find out more please visit the Geeklog Wiki about Theme Specific Plugin Templates.

General Changes

Theme changes in Geeklog 2.1.0

Theme changes in Geeklog 2.0.0

As of Geeklog 2.0.0 there are now 2 theme engines in Geeklog. Currently the themes Demin and Modern Curve use the 2.0.0 theme engine. The Professional and Professional CSS themes use the 1.8.1 engine. The 1.8.1 theme engine will eventually be removed from Geeklog so if you are developing a new theme it is best to use the new engine. To find out more about this please visit the Geeklog Wiki Theme Developers Guide.

General Changes

Theme Engine 2.0.0 Specific Changes

Theme Engine 1.8.1 Specific Changes

Theme changes in Geeklog 1.8.0

Theme changes in Geeklog 1.7.1

Admin templates

Other changes

Theme changes in Geeklog 1.7.0

Admin templates

Other changes

Theme changes in Geeklog 1.6.1

Cosmetic changes

These changes are mostly cosmetic and won't affect the functionality of a theme if not applied:

Changes to plugin templates

Note that plugin template files are kept in a directory plugins/pluginnname/templates and not in the layout directory.

Theme changes in Geeklog 1.6.0

Search

The templates for the search form and search results have been changed and new template files have been added for the new display modes of the search results. We suggest to replace the entire search subdirectory in your theme with a copy of the directory from the Professional theme as it ships with Geeklog.

Comments

The commentform.thtml and commentform_advanced.thtml template files were changed to include a security token and a {notification} variable (for the new option to be notified of followup comments).

Plugins

Permissions Editor

The various instances of the Permissions Editor (where you can set the Read / Edit permissions for Owner, Group, Members, Anonymous) were using slightly different template variable names. From now on, the following names are defined everywhere:

Template files using the alternative names will continue to work, but new files should use the above names from now on.

Theme changes in Geeklog 1.5.2

Note: Themes made for Geeklog 1.5.0 or 1.5.1 should work just fine with Geeklog 1.5.2. In this release, we only fixed a few problems in the themes (detailed below) that also affected 1.5.0 and 1.5.1. The other changes listed here are optional.

Bugfixes

These changes are actual bugs in the template files that also exist in Geeklog 1.5.0 and 1.5.1. We recommend making these changes to all custom themes.

Other changes

These changes are optional. They fix cosmetic issues or issues that only affect some setups.

Theme changes in Geeklog 1.5.1

Note: Themes made for Geeklog 1.5.0 are mostly compatible with Geeklog 1.5.1. We only made one mandatory change (for the Configuration admin panel) - all the other changes listed below are optional or adjustments for special setups (e.g. multi-language sites, right-to-left languages). See details below.

Important change: Configuration

The JavaScript code used for the Configuration admin panel used a generic name which caused conflicts with other JavaScript code. You should update the file admin/config/config_element.thtml to make sure your theme works with Geeklog 1.5.1.

Multilingual blocks

The multi-language support for blocks introduced in Geeklog 1.5.1 relies on disabled blocks being swapped in dynamically. If you are using Geeklog's multi-language support, you may need to modify the piece of PHP code in your theme's functions.php so that it picks the correct templates for these multilingual blocks:

$lang = COM_getLanguageId();
if (empty($lang)) {
    $result = DB_query("SELECT onleft,name FROM {$_TABLES['blocks']} WHERE is_enabled = 1");
} else {
    $result = DB_query("SELECT onleft,name FROM {$_TABLES['blocks']}");
}

Prior to Geeklog 1.5.1, you will probably only find the first SQL request in your functions.php file.

Other changes

Theme changes in Geeklog 1.5.0

XHTML support

Geeklog now supports XHTML compliant themes. These themes should define the following constant in their functions.php file:

define('XHTML', ' /');

This will ensure that Geeklog switches to XHTML internally. If you want your theme be working both as an HTML and an XHTML theme, you should use the {xhtml} variable wherever XHTML requires a self-closing tag, e.g. <br /> would be written as <br{xhtml}>. If you don't plan to use the theme for HTML, feel free to hard-code your theme for XHTML only.

Note: If you're using XHTML, it is your responsibility to ensure that your site's content (stories, comments, etc.) is XHTML compliant. Geeklog does not convert your content to XHTML.

"Contribute" - User submitted stories

Geeklog 1.5.0 supports the ability for users to specify story intro text and body text seperately rather than just the intro text. This can be turned on and off by changing the templates. The files:

Contain table rows containing the bodytext inputs. Simply removing these inputs returns behaviour to the original.

Admin Menu, User Menu & Topic List

All the above mentioned items are now lists, using ul and li tags (and a new CSS class, blocklist, to hide the list bullets). Two new template files have been added to create these blocks:

Please note that the {blockid} variable that was present in pre-release versions of Geeklog 1.5.0 has since been removed.

Security Changes

Many forms, particularly in the admin section of the site need a new hidden form field in order for saving the form/processing the action to work. Add:

<input type="hidden" name="{gltoken_name}" value="{gltoken}"{xhtml}>

To the following templates:

Some plugin specific templates have also been changed, you may also need to check:

Removed Files

The following template files have been removed and are no longer needed:

System Message

The previously hard-coded CSS for the System Messages has been moved to the stylesheet (new CSS class sysmessage).

Theme changes in Geeklog 1.4.1

The css in 1.4.1 has been changed to a wider extent. More and more layout components are beeing moved to the stylesheet so more change in looks can be achieved with less change in the files. There is a reduction of tables and DIV, and a stronger focus on semantics and consistency. Please also notice that the styles.css includes additional documentation on the use of classes now.

As usual, any missing new theme files can simply be copied over from the default theme (Professional) that ships with Geeklog.

Header-Tags

From now on, all headlines in blocks & stories are made with header-tags. The biggest title in a story is always h1, in a block always h2.

Story layout

The blocks for stories have no more tables, and the classes have been renamed for consistency. There is a box now around the story called class "story" or "story-featured". The components inside that box are story-icons, story-information, story-body and story-footer. The title is a h1-tag. For featured stories, only the outer box has a different class, the rest has to be cascaded for changes.

Blocks

The blocks changed in the same way as the stories. There are no more tables, only one div-tag as a frame around called block-box, block-box-left or block-box-right. The title is a h2-tag and the help icon for the block is a span with a class called block-helpicon. Sub-titles in blocks have the h3-tag (such such as in the What's new or Older Stories block). The changes affect (next to styles.css) the follwing files:

Admin templates

Many of the admin template files have had minor changes to tweak appearance or functionality. If you didn't modify the admin templates in your theme, the easiest way to upgrade your theme's admin templates is to simply replace the entire 'admin' directory with the one from Geeklog's Professional theme.

Other theme changes

Professional theme

The following changes are specific to the Professional theme. There is probably no need to port them over to other themes.

Theme changes in Geeklog 1.4.0

As usual, any missing new theme files can simply be copied over from the default theme (Professional) that ships with Geeklog.

Admin templates

Geeklog 1.4.0 comes with revamped Admin sections which required a lot of theme changes. We therefore suggest that you simply replace the entire admin directory of your theme with the admin directory from Geeklog's default theme (Professional) as it ships with Geeklog 1.4.0 and apply any modfications you may have made to your Admin templates again afterwards.

Note: The new icons for "Command and Control" (moderation.php) in the Professional theme use a white background. For themes with a dark (or other non-white) background, you can download these icons as PNGs with alpha transparency (note that Internet Explorer can not display images with alpha transparency unless you include a JavaScript "hack" into your theme, so you may want to convert those icons to normal transparency or simply set the background to that of your theme).

Advanced editor

To use the included advanced editor (FCKeditor) you will need the following new template files:

You also have to add {advanced_editor} to the <head> section of your theme's header.thtml file.

Other changes

Theme changes in Geeklog 1.3.11

There are no mandatory theme changes in Geeklog 1.3.11, so themes made for Geeklog 1.3.10 will work just fine without any modifications.

A few minor additions / new options have been introduced:

Theme changes in Geeklog 1.3.10

General note: To upgrade your custom theme for use with Geeklog 1.3.10, you can simply copy over any new template files from the Geeklog default theme.

The biggest change in Geeklog 1.3.10 is that we now ship it with only one default theme (the Professional theme, kindly provided by Victor B. Gonzalez) and that the previously included themes are now available as a separate download.

Admin templates

Most themes don't change the template files in the theme's admin directory, so you can often save yourself a bit of work by simply replacing the entire admin directory with the one from the Geeklog 1.3.10 distribution.

Other templates

Optional changes

The following is a list of optional changes (mostly new variables that are now available). This information is mostly of interest for those who want to develop their own themes.

Theme changes in Geeklog 1.3.9

Theme changes in Geeklog 1.3.8

Theme changes in Geeklog 1.3.8 were mostly aimed at moving as much of the hard-coded HTML into template files as possible. Other changes were made to give theme authors better control over the layout and a small portion of changes were done to incorporate new Geeklog features.

New template files

This is a list of the new files. You can safely copy these over from one of the standard themes that ship with Geeklog (most of these files contain HTML that was previously hard-coded into Geeklog).

adminoption_off.thtml
loginform.thtml
topicoption.thtml
topicoption_off.thtml
useroption_off.thtml
admin/database/listbackups.thtml
admin/database/listitem.thtml
admin/user/edituser.thtml
admin/user/plainlist.thtml
comment/commentbar.thtml
comment/startcomment.thtml
pollbooth/pollanswer.thtml
pollbooth/pollblock.thtml
pollbooth/pollcomments.thtml
pollbooth/pollresult.thtml
pollbooth/pollvotes_bar.thtml
pollbooth/pollvotes_num.thtml
preferences/commentblock.thtml
preferences/deleteaccount.thtml
preferences/digestblock.thtml
preferences/displayblock.thtml
preferences/displayprefs.thtml
preferences/language.thtml
preferences/privacyblock.thtml
preferences/profile.thtml
preferences/theme.thtml
preferences/username.thtml
preferences/userphoto.thtml
search/resultauthdatehits.thtml
search/resultrowenhanced.thtml
search/resultsummary.thtml
search/resulttitle.thtml
users/newpassword.thtml

Note: preferences and admin/database are new directores.

Changed / updated template files

These files have changed since Geeklog 1.3.7, i.e. they may contain new variables, table columns, etc. If you haven't changed these files in your existing theme, it is probably best to simply copy them over from one of the themes that ship with Geeklog (with the exception of style.css and header.thtml, see below).

style.css (see below)
header.thtml (see below)
admin/block/blockeditor.thtml
admin/block/listblocks.thtml
admin/block/listitem.thtml
admin/event/eventeditor.thtml
admin/event/eventlist.thtml
admin/event/listitem.thtml
admin/group/grouplist.thtml
admin/group/listitem.thtml
admin/story/liststories.thtml
admin/topic/listitem.thtml
admin/topic/topiceditor.thtml
admin/topic/topiclist.thtml
calendar/editpersonalevent.thtml
calendar/eventdetails.thtml
search/searchform.thtml
search/searchresults.thtml
submit/submitevent.thtml
users/getpasswordform.thtml

In style.css, four classes have been added that are used in the new search code of Geeklog 1.3.8. Instead of copying over the entire file, you will probably only want to copy over the code for those four classes: searchAuth, searchDate, searchHits, highlight.

If the header.thtml of your theme is using the {menu_elements} variable, then you do not need to make any changes to it. If it is not using that variable, then you will need to make one change to it. In that case, search your header.thtml for the link to the story submission form, i.e. something like

<a href="{site_url}/submit.php?type=story">

and change it to read

<a href="{site_url}/submit.php?type=story{current_topic}">

Removed template files

If you have a file named commentheader.thtml in your theme directory, you can safely remove it. It isn't used at all.

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

Other changes

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

CSS changes

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.

The Geeklog Documentation Project
All trademarks and copyrights on this page are owned by their respective owners. Geeklog is copyleft.