(see below for a list of theme changes in recent Geeklog versions)
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.
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/professional /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:
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 describes 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.
An incomplete list of variables that can be used in templates files is also included.
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.
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. storytext.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.
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.
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.
Left blocks in the right column:
$_CONF['left_blocks_in_footer'] is a
rather curious option. It makes the {left_blocks} variable
available in the site's footer (i.e. footer.thtml) while at the same
time disabling it in the header (header.thtml).
The idea is that this can be used for two-column layouts (one column for the
blocks and one column for the content) but when you want to have the blocks
on the right side. Simply moving all blocks to the right will not work as
expected, as you'd end up with no blocks at all on those pages that
normally only display the left blocks (e.g. article.php or the
admin pages). Setting $_CONF['left_blocks_in_footer'] = 1 will
fix this, so that the blocks, while internally still treated as left
blocks, will actually be displayed on the right.
The theme's header.thtml, footer.thtml, and
leftblocks.thtml will probably need some adjustments. The
'left_blocks_in_footer' option is therefore not available in the main
configuration but should instead be set in the theme's functions.php
file. That way, you can even leave your users a choice between, for example,
a "normal" theme and one with the blocks on the right.
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 change the function CUSTOM_handleError in
lib-custom.php to output any HTML you like.
Adding a "permalink" to stories: Many websites offer a so-called permalink, i.e. a link to a permanent URL for the story. In Geeklog's default Professional theme, the article's headline already provides the same functionality - it links to a permanent URL for the story (pointing to article.php). However, since this is not very obvious and since visitors often expect to find a "permalink" somewhere on the page, here's how to add one yourself:
<a href="{article_url}">{lang_permalink}<a>article_url) using the word
"Permalink" from the current language file (lang_permalink).(to be grouped and sorted)
{plg_footercode} to footer.thtml.
Allows for adding code, e.g. JavaScript code, to the end of a page.tooltip classes and introduced
new classes (classic, help, etc.) in the stylesheet,
style.css.chk_grpdefault and chk_applydefault
checkboxes in admin/group/groupeditor.thtml so that the "apply
Default Group change" option only shows up when the state of the Default
Group checkbox changes (requires an additional piece of JavaScript in
javascript/common.js).{hide_meta} in the Topic editor template,
admin/topic/topiceditor.thtml, to hide the text entry fields for
the meta description and meta keywords when meta tag support is
disabled.{icon_max_dimensions}).{hide_meta} in the Story editor templates,
admin/topic/storyeditor.thtml and
admin/topic/storyeditor_advanced.thtml, to hide the text entry
fields for the meta description and meta keywords when meta tag support is
disabled.display:{show_htmleditor}; CSS snippet from the
<div id="editor-mode"> in
admin/topic/storyeditor_advanced.thtml to ensure that the list of
allowed HTML tags and autotags is always visible.false. In admin/config/menu_element.thtml, the return
statement was missing for the open_group and
open_subgroup calls.
In admin/config/config_element.thtml, it was missing for the
unset-param case (i.e. the call to restore).select-element, {hide_row} was added for the
table row and a {delete} option was added after the
select. These changes are required to allow dynamic addition /
removal of dropdowns, e.g. for $_CONF['menu_elements'].lang_ prefix ({lang_owner}, etc).span around the link and a
new template variable, {hidewhenediting}, that will contain CSS to
hide the span when a comment is edited (but not when it's
submitted). Changed files: comment/commentform.thtml and
comment/commentform_advanced.thtml.id="identity_url" (since the <label> tag refers to an id,
not a name).rel="home" attribute to the Home link in the Topics
block.<li> element in
comment/thread.thtml so that follow-up comments in threaded mode
are a bit more apart and easier to read.{lang_num_stories}, {num_stories}{remoteservice} variable in
admin/user/edituser.thtml to optionally display the name of the
service a Remote User was using to log in.{title_checked} variable to search/searchform.thtml, so that the "Refine search" option can keep the status of the "Titles
Only" checkbox.searchresult-byline.These changes are mostly cosmetic and won't affect the functionality of a theme if not applied:
<div id="preview"> in
admin/story/storyeditor_advanced.thtml.font-size:larger; for the header fields of
the admin lists from the stylesheet, but added some top/bottom padding
(bug #0000956).width="180" from the Block editor template
(admin/block/blockeditor.thtml) that pushed the first column too
far to the right.width:100%;Note that plugin template files are kept in a directory plugins/pluginnname/templates and not in the layout directory.
width="150" from the Category editor template
(admin/categoryeditor.thtml) that pushed the first column too far
to the right.XHTML constant in its
functions.php file!{pi_display_name} in admin/plugins/editor.thtml.
This is a purely cosmetic change.<form> (e.g. the new Groups
editor).{startblock_email} and {endblock_email}
and the top table. These elements are now added automatically to make the
the mail form look more consistent with the other admin panels.</option> tag; the <col> tags in
configuration.thtml were not XHTML compliant.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.
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).
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.
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.
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.
{start_storylink_anchortag} variable in the story templates
was missing the closing '>'. This caused the story title to disappear
on some themes. (This was a bug in Geeklog's code, so no theme changes
required){site_admin_url} was missing from the Configuration form
action in admin/config/configuration.thtml. This may have caused
problems making configuration changes on some setups.old_pid input field to the polls editor template
file, plugins/polls/templates/admin/polleditor.thtml, to fix
problems when changing a poll's ID.These changes are optional. They fix cosmetic issues or issues that only affect some setups.
.header-navigation-container li.last rule in style.css
is not needed for this theme.{direction}, was not available in the printer-friendly
templates for articles and static pages.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.
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.
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.
{page_title}
(in header.thtml) changed so that it now only contains the actual
page title or the site's slogan (in earlier versions, it contained both the
site's name and either the page title or the site's slogan). This was done
so that the combination {page_title}{page_site_splitter}{site_name}
could be used to place the page title before the site's name for better SEO. If you prefer
to have the site's name first on the index page and the page title first on
all other pages, you can now use the new variable
{page_title_and_site_name}feed-link class to be used for links to
feeds (e.g. the new Story Option entry for topic feeds). In the Professional
theme, a small feed icon (images/feed.png) is used as a background
image for these links.commentbar-line2 class in style.css to make
the "Post a comment" button float to the left and easier to see. There were
no changes in functionality and other commentbar layouts will continue to
work as before.{story_text_no_br} variable to refer to the story
text. Template files that use {story_introtext} here will
continue to work as before.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.
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.
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.
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:
{hidden_fields} variable)The following template files have been removed and are no longer needed:
The previously hard-coded CSS for the System Messages has been moved to the stylesheet (new CSS class sysmessage).
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.
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.
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.
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:
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.
{delete_option} variable with
{delete_option_no_confirmation} in the admin templates.{group_dropdown} variable.
{startampm_selection}, {endampm_selection},
{ampm_selection}, depending on the template file), and the
dropdowns for the minutes are available as variables
({startminute_options}, {endminute_options},
{minute_options}, depending on the template file).{author} and {owner} are now
available in every template where an object's author (e.g. story or
comment author) or owner (e.g. owner of a block) name can be displayed.
They will also respect the $_CONF['show_fullname'] setting,
i.e. display either the user's full name or username.{contributedby_author}.{answer_text}. The
polleditor.thtml has an aditional field to enter the remarks,
same as the pollansweroption.thtml.
{captcha} variable has been added to
the following files:
The following changes are specific to the Professional theme. There is probably no need to port them over to other themes.
As usual, any missing new theme files can simply be copied over from the default theme (Professional) that ships with Geeklog.
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).
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.
{send_trackback_link},
{send_trackback_url}, and
{lang_send_trackback_text} are available in the story and
article template files. They provide a complete link as well as the URL and
link text allowing you to send a trackback comment for the current
story.{plugin_types} option).{services}, has to be added to the
loginform.thtml template file if you plan to allow users to log in
to your site using remote authentication.{start_trackbacks_anchortag}{trackbacks_with_count}{end_trackbacks_anchortag}. See the Professional theme's story template files for
examples.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:
{camera_icon}, can now be used in the story
and comment template files to display the small camera icon (the same as in
the Who's Online block) to link to the author's user profile (only if they
uploaded a userphoto).{layout_url} variable is now available in the templates
for the story, link, and event submission forms.{separator} is now
available in addition to the misspelled {seperator}
variable.{calendar_mode}, can be used in the
calendar/events.thtml template file to ensure that the "add event"
link will take the user to the proper event submission form for either the
site calendar or the personal calendar.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.
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.
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.
{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.{link_edit} variable has been added to
links/linkdetails.thtml so that admins can edit links directly
from the links section.{edit_icon} can be used as an alternative to
{edit_link} in the story template files and in
links/linkdetails.thtml.{google_paging} variable has been added to
admin/link/linklist.thtml. Also added a column number to
linklist.thtml and admin/link/listitem.thtml.{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. 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).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 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.
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/boxesblock.thtml preferences/commentblock.thtml preferences/deleteaccount.thtml preferences/digestblock.thtml preferences/displayblock.thtml preferences/displayprefs.thtml preferences/excludeblock.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.
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}">If you have a file named commentheader.thtml in your theme directory, you can safely remove it. It isn't used at all.
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.
$_THEME_URL = $_CONF['layout_url'];$_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.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.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 ...
mailto: link with the site's email address from the
configuration.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.