Difference between revisions of "Theme Developers Guide"

From GeeklogWiki
Jump to: navigation, search
(=Other changes=)
(Theme API)
 
(17 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
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 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.
  
 +
 +
== Geeklog’s theme engine ==
 +
 +
As of Geeklog 2.0.0, the Geeklog theme engine was updated. There are 2 versions of the theme engine now, 2.0.0 and 1.8.1. Version 1.8.1 of the theme engine works the same as before and will be around for the next couple of versions of Geeklog until most of the popular themes and plugins are updated. The Geeklog community will be given plenty of notice before this version of the theme engine is removed.
 +
 +
So what is difference between the 2 theme engines? The main difference is when the templates are compiled. In Geeklog 1.8.X and lower the average Geeklog page was generated in chunks. Usually the header was generated first, followed by some processing which generated the middle and then finally the footer. The problem with this approach now days is that it doesn't allow for the header to be updated whenever we need to. We were finding more and more that the middle processing part (i.e. displaying the actual articles, plugins, etc.) needed to add something (javascript, css, text, etc.) to the header. For Responsive Web Design we also found that themes needed to know how many columns were going to be displayed right when the html page is created. To get around this an updated theme engine was devised to allow Geeklog to generate the whole page at once.
 +
 +
So, with Geeklog 2.0.0 we have added a new function called COM_createHTMLDocument that will eventually completely replace COM_siteHeader and COM_siteFooter. Geeklog 2.0.0 and all of the core plugins have been converted to use COM_createHTMLDocument but COM_siteHeader and COM_siteFooter have been left in to be backwards compatible for all older plugins. The Geeklog Development Team strongly suggest when plugin developers are upgrading their plugins that they take the time to convert all calls for COM_siteHeader and COM_siteFooter, to COM_createHTMLDocument.
 +
 +
To use the new theme engine you must set in your theme's function.php a config variable:
 +
 +
;CONF['supported_version_theme'] = '2.0.0';
 +
 +
You will also need to include a new template variable called {layout_columns} which sets the class of the body tag which is found in header.thtml. This is needed to set the number of Geeklog columns on a given page.
 +
 +
Geeklog’s updated theme engine also supports plugins that do not yet use the COM_createHTMLDocument function when creating a page. To include this support in your 2.0.0 theme a new Javscript file fix_html.js is required. Javascript code also needs to be added in the footer of the theme that runs the following code:
 +
 +
;FixHTML('leftblocks', 'centerblocks', 'rightblocks');
 +
 +
When creating your Geeklog 2.0.0 theme (or upgrading older themes) please use the bundled Denim and Modern Curve themes as examples. They include all of the latest changes.
  
 
== Creating a theme ==
 
== Creating a theme ==
Line 35: Line 55:
 
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()):
 
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 = COM_newTemplate ($_CONF['path_layout'] . 'users');
 
;$user_templates->set_file (array ('profile'=>'profile.thtml', 'row'=>'commentrow.thtml', 'strow'=>'storyrow.thtml'));  
 
;$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.
 
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.
  
An [[incomplete list of variables]] that can be used in templates files is also included.
+
An [http://www.geeklog.net/docs/english/themevars.html incomplete list of variables] that can be used in templates files is also included.
 
 
  
 
== Testing a theme and further information ==
 
== Testing a theme and further information ==
Line 49: Line 68:
 
Finally, you may want to update the logo and other images in your theme's images directory.  
 
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.
+
For the template system we are using [http://phplib.sourceforge.net/ PHPLib]'s template class. 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
  
 +
== Theme Specific Plugin Templates ==
  
== Tips and tricks ==
+
As of Geeklog 2.1.1, 2 new functions have been added to the template library that plugins can use to determine which templates to use when displaying information. This means if the plugin supports it, under it's template directory it can contain directories named after themes. Within these directories the plugin template files for that theme will reside. A new directory called default will also be found and is REQUIRED. It contains all of the template files for the plugin that the plugin will use if no theme specific template directory and files are found. Also, the plugin theme template directories do not need to contain all of the template files. if one is not found the template class will fall back and look in the plugin default template directory for the required file.
  
'''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.
+
Themes themselves also can contain the plugin template files. These must be located in the root of the theme directory under the layout directory. This is the first spot that the template class will look for the plugin template file.  If it is not found here it will then check for the theme directory in the plugins template directory.
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.
+
To keep things consistent with the core plugins and to make theme development easier, other plugins should go ahead and use these functions where possible.  
  
'''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.
+
The 2 functions are:
  
'''Polls''': To use multi-colored bars in the graphical display of poll results, you can use the {answer_counter} and {answer_odd} variables in the pollbooth/pollvotes_bar.thtml template file. {answer_counter} will be replaced with a running number for each answer, hence bar{answer_counter}.gif would result in bar1.gif, bar2.gif, etc. Giving each of those GIFs a different color would give you a different color for each answer.
+
* CTL_plugin_templatePath($plugin, $path)
{answer_odd} will alternate between 0 and 1 for every answer, hence bar{answer_odd}.gif will result in bar0.gif for the first, third, fifth, etc. answer and bar1.gif for the second, fourth, etc. answer.
+
* CTL_plugin_themeFindFile($plugin, $directory, $filename, $return_url)
  
 +
The template function returns the physical path directory location of the plugin templates. This should be run at the beginning of your plugins functions.inc and stored in your plugins config variables like so:
  
== Theme changes in Geeklog 1.3.9 ==
+
$CONF_MYPLUGIN['path_layout'] = CTL_plugin_templatePath('myplugin');
  
*In header.thtml, you can now use the new variable {allowed_menu_elements} as an alternative to using {menu_elements}. The new variable takes the $_CONF['XXXloginrequired'] settings into account, i.e. it will only list those entries that the current user has access to.
+
The Find File functions returns the HTML path for a plugin file (url or physical file location).
*The admin/syndication directory, containing feededitor.thtml, listfeeds.thtml, listitem.thtml, and selecttype.thtml has been added.
 
*Template files comment/comment.thtml and comment/thread.thtml have been added and comment/startcomment.thtml has been changed to implement template-driven comments.
 
Please note that comment/comment.thtml was changed again in Geeklog 1.3.9rc2.
 
*A {link_edit} variable has been added to links/linkdetails.thtml so that admins can edit links directly from the links section.
 
*An "edit" icon has been added: images/edit.gif. The new variable {edit_icon} can be used as an alternative to {edit_link} in the story template files and in links/linkdetails.thtml.
 
*In the calendar/calendar.thtml file, the "mode" parameter has been added to the << and >> buttons, so that users stay in their personal calendar when browsing through months.
 
*A new file, admin/group/groupmembers.thtml, has been added and admin/group/listitem.thtml has been changed for the new alternative option to add users to groups.
 
*A new file, admin/block/listside.thtml, has been added and admin/block/listitem.thtml and admin/block/listblocks.thtml have been changed for the enhanced block list.
 
*A {google_paging} variable has been added to admin/link/linklist.thtml. Also added a column number to linklist.thtml and admin/link/listitem.thtml.
 
*All template files where the user can enter a URL are now using a new variable, {max_url_length}, instead of a hard-coded number of characters for the max. length of the URL. Files affected: admin/block/blockeditor.thtml, admin/event/eventeditor.thtml, admin/link/linkeditor.thtml, admin/topic/topiceditor.thtml, submit/submitevent.thtml, submit/submitlink.thtml.
 
*The hard-coded &nbsp; has been removed from the {welcome_msg} variable. The blank was then added to the header.thtml of the Classic, XSilver, and Yahoo themes (the other themes either look fine without it or didn't use {welcome_msg} in the first place).
 
*An extra table has been removed from the users/profile.thtml file of the XSilver theme so that the username now lines up properly with the other entries.  
 
  
== Theme changes in Geeklog 1.3.8 ==
+
The order of operation for the template function is
  
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.
+
1) It checks for a sub directory of the plugin’s name in the current theme being displayed root directory. If found it is used.
 +
2) It checks for a sub directory of the theme’s name in the current “plugins/myplugin/templates/” directory. If found it is used.
 +
3) If 1 or 2 is not found then the default template for the plugin is used. It is always located in “plugins/myplugin/templates/default/”
  
 +
This will hopefully make things easier for people when updating plugins to maintain their template changes. It also makes it easier for plugin developers to include plugin templates that support specific themes.
  
=== New template files ===
+
Plugin Templates that are theme specific can also now have a functions.php file which is similar to theme functions.php. This allows plugin templates to set additional JavaScript files, JavaScript library's and CSS 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).
+
CSS files also can be found in a similar way by Geeklog using the default directory name (required), and theme directory names. Their location is stored in the css directory which is in the root of the plugin directory, which is found under the Geeklog public_html directory.
  
adminoption_off.thtml<br/>
+
All core plugins support this functionality. Please review their code for examples.
loginform.thtml<br/>
 
topicoption.thtml<br/>
 
topicoption_off.thtml<br/>
 
useroption_off.thtml<br/>
 
admin/database/listbackups.thtml<br/>
 
admin/database/listitem.thtml<br/>
 
admin/user/edituser.thtml<br/>
 
admin/user/plainlist.thtml<br/>
 
comment/commentbar.thtml<br/>
 
comment/startcomment.thtml<br/>
 
pollbooth/pollanswer.thtml<br/>
 
pollbooth/pollblock.thtml<br/>
 
pollbooth/pollcomments.thtml<br/>
 
pollbooth/pollresult.thtml<br/>
 
pollbooth/pollvotes_bar.thtml<br/>
 
pollbooth/pollvotes_num.thtml<br/>
 
preferences/boxesblock.thtml<br/>
 
preferences/commentblock.thtml<br/>
 
preferences/deleteaccount.thtml<br/>
 
preferences/digestblock.thtml<br/>
 
preferences/displayblock.thtml<br/>
 
preferences/displayprefs.thtml<br/>
 
preferences/excludeblock.thtml<br/>
 
preferences/language.thtml<br/>
 
preferences/privacyblock.thtml<br/>
 
preferences/profile.thtml<br/>
 
preferences/theme.thtml<br/>
 
preferences/username.thtml<br/>
 
preferences/userphoto.thtml<br/>
 
search/resultauthdatehits.thtml<br/>
 
search/resultrowenhanced.thtml<br/>
 
search/resultsummary.thtml<br/>
 
search/resulttitle.thtml<br/>
 
users/newpassword.thtml<br/>
 
  
Note: preferences and admin/database are new directores.
+
== Theme API ==
  
 +
Since Geeklog 2.0.0, a minimal theme API is available. It can be used to override defaults, load CSS files and load JavaScript files.
 +
The API is structured similarly to that of the Geeklog plugins. In the file "functions.php" in the theme's folder, the following functions may be declared (replace yourThemeName with the actual theme name):
  
=== Changed / updated template files ===
+
* function theme_config_yourThemeName()
 +
* function theme_css_yourThemeName()
 +
* function theme_js_libs_yourThemeName()
 +
* function theme_js_files_yourThemeName()
 +
* function theme_init_yourThemeName()
  
These file 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).
+
For implementation details please see the functions.php file that was shipped with your version of Geeklog.
  
style.css (see below)<br/>
+
== Tips and tricks ==
header.thtml (see below)<br/>
 
admin/block/blockeditor.thtml<br/>
 
admin/block/listblocks.thtml<br/>
 
admin/block/listitem.thtml<br/>
 
admin/event/eventeditor.thtml<br/>
 
admin/event/eventlist.thtml<br/>
 
admin/event/listitem.thtml<br/>
 
admin/group/grouplist.thtml<br/>
 
admin/group/listitem.thtml<br/>
 
admin/story/liststories.thtml<br/>
 
admin/topic/listitem.thtml<br/>
 
admin/topic/topiceditor.thtml<br/>
 
admin/topic/topiclist.thtml<br/>
 
calendar/editpersonalevent.thtml<br/>
 
calendar/eventdetails.thtml<br/>
 
search/searchform.thtml<br/>
 
search/searchresults.thtml<br/>
 
submit/submitevent.thtml<br/>
 
users/getpasswordform.thtml<br/>
 
  
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.
+
'''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.
  
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
+
'''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.
  
    <a href="{site_url}/submit.php?type=story">
+
'''Different look for left and right blocks''': You can give the blocks on the left and right a different look. See [http://www.geeklog.net/forum/viewtopic.php?forum=10&showtopic=21070 this story on the Geeklog homepage] for details.
  
and change it to read
+
'''Polls''': To use multi-colored bars in the graphical display of poll results, you can use the {answer_counter} and {answer_odd} variables in the pollbooth/pollvotes_bar.thtml template file. {answer_counter} will be replaced with a running number for each answer, hence bar{answer_counter}.gif would result in bar1.gif, bar2.gif, etc. Giving each of those GIFs a different color would give you a different color for each answer.
 
+
{answer_odd} will alternate between 0 and 1 for every answer, hence bar{answer_odd}.gif will result in bar0.gif for the first, third, fifth, etc. answer and bar1.gif for the second, fourth, etc. answer.
    <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 ===
 
 
 
*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:
+
'''XHTML''': [[Themes and XHTML]]
  
<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.
+
[[Category:Themes]]

Latest revision as of 14:56, 27 December 2015

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.


Geeklog’s theme engine

As of Geeklog 2.0.0, the Geeklog theme engine was updated. There are 2 versions of the theme engine now, 2.0.0 and 1.8.1. Version 1.8.1 of the theme engine works the same as before and will be around for the next couple of versions of Geeklog until most of the popular themes and plugins are updated. The Geeklog community will be given plenty of notice before this version of the theme engine is removed.

So what is difference between the 2 theme engines? The main difference is when the templates are compiled. In Geeklog 1.8.X and lower the average Geeklog page was generated in chunks. Usually the header was generated first, followed by some processing which generated the middle and then finally the footer. The problem with this approach now days is that it doesn't allow for the header to be updated whenever we need to. We were finding more and more that the middle processing part (i.e. displaying the actual articles, plugins, etc.) needed to add something (javascript, css, text, etc.) to the header. For Responsive Web Design we also found that themes needed to know how many columns were going to be displayed right when the html page is created. To get around this an updated theme engine was devised to allow Geeklog to generate the whole page at once.

So, with Geeklog 2.0.0 we have added a new function called COM_createHTMLDocument that will eventually completely replace COM_siteHeader and COM_siteFooter. Geeklog 2.0.0 and all of the core plugins have been converted to use COM_createHTMLDocument but COM_siteHeader and COM_siteFooter have been left in to be backwards compatible for all older plugins. The Geeklog Development Team strongly suggest when plugin developers are upgrading their plugins that they take the time to convert all calls for COM_siteHeader and COM_siteFooter, to COM_createHTMLDocument.

To use the new theme engine you must set in your theme's function.php a config variable:

CONF['supported_version_theme'] = '2.0.0';

You will also need to include a new template variable called {layout_columns} which sets the class of the body tag which is found in header.thtml. This is needed to set the number of Geeklog columns on a given page.

Geeklog’s updated theme engine also supports plugins that do not yet use the COM_createHTMLDocument function when creating a page. To include this support in your 2.0.0 theme a new Javscript file fix_html.js is required. Javascript code also needs to be added in the footer of the theme that runs the following code:

FixHTML('leftblocks', 'centerblocks', 'rightblocks');

When creating your Geeklog 2.0.0 theme (or upgrading older themes) please use the bundled Denim and Modern Curve themes as examples. They include all of the latest changes.

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 = COM_newTemplate ($_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.

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

Theme Specific Plugin Templates

As of Geeklog 2.1.1, 2 new functions have been added to the template library that plugins can use to determine which templates to use when displaying information. This means if the plugin supports it, under it's template directory it can contain directories named after themes. Within these directories the plugin template files for that theme will reside. A new directory called default will also be found and is REQUIRED. It contains all of the template files for the plugin that the plugin will use if no theme specific template directory and files are found. Also, the plugin theme template directories do not need to contain all of the template files. if one is not found the template class will fall back and look in the plugin default template directory for the required file.

Themes themselves also can contain the plugin template files. These must be located in the root of the theme directory under the layout directory. This is the first spot that the template class will look for the plugin template file. If it is not found here it will then check for the theme directory in the plugins template directory.

To keep things consistent with the core plugins and to make theme development easier, other plugins should go ahead and use these functions where possible.

The 2 functions are:

  • CTL_plugin_templatePath($plugin, $path)
  • CTL_plugin_themeFindFile($plugin, $directory, $filename, $return_url)

The template function returns the physical path directory location of the plugin templates. This should be run at the beginning of your plugins functions.inc and stored in your plugins config variables like so:

$CONF_MYPLUGIN['path_layout'] = CTL_plugin_templatePath('myplugin');

The Find File functions returns the HTML path for a plugin file (url or physical file location).

The order of operation for the template function is

1) It checks for a sub directory of the plugin’s name in the current theme being displayed root directory. If found it is used. 2) It checks for a sub directory of the theme’s name in the current “plugins/myplugin/templates/” directory. If found it is used. 3) If 1 or 2 is not found then the default template for the plugin is used. It is always located in “plugins/myplugin/templates/default/”

This will hopefully make things easier for people when updating plugins to maintain their template changes. It also makes it easier for plugin developers to include plugin templates that support specific themes.

Plugin Templates that are theme specific can also now have a functions.php file which is similar to theme functions.php. This allows plugin templates to set additional JavaScript files, JavaScript library's and CSS files.

CSS files also can be found in a similar way by Geeklog using the default directory name (required), and theme directory names. Their location is stored in the css directory which is in the root of the plugin directory, which is found under the Geeklog public_html directory.

All core plugins support this functionality. Please review their code for examples.

Theme API

Since Geeklog 2.0.0, a minimal theme API is available. It can be used to override defaults, load CSS files and load JavaScript files. The API is structured similarly to that of the Geeklog plugins. In the file "functions.php" in the theme's folder, the following functions may be declared (replace yourThemeName with the actual theme name):

  • function theme_config_yourThemeName()
  • function theme_css_yourThemeName()
  • function theme_js_libs_yourThemeName()
  • function theme_js_files_yourThemeName()
  • function theme_init_yourThemeName()

For implementation details please see the functions.php file that was shipped with your version of 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.

Polls: To use multi-colored bars in the graphical display of poll results, you can use the {answer_counter} and {answer_odd} variables in the pollbooth/pollvotes_bar.thtml template file. {answer_counter} will be replaced with a running number for each answer, hence bar{answer_counter}.gif would result in bar1.gif, bar2.gif, etc. Giving each of those GIFs a different color would give you a different color for each answer. {answer_odd} will alternate between 0 and 1 for every answer, hence bar{answer_odd}.gif will result in bar0.gif for the first, third, fifth, etc. answer and bar1.gif for the second, fourth, etc. answer.

XHTML: Themes and XHTML