Note: do not modify an existing theme. It may be overwritten when you upgrade. Instead copy an existing theme and rename it as described below.
Creating a theme? Don't forget to submit your URL to us. We may buy it from you!
The best way to create your own theme is to copy an existing one. Thyme's theme files are not encoded. This allows for you to copy and freely modify any existing theme.
To start, we'll copy the default theme. All themes in Thyme are in the themes sub-folder. Copy the default folder to custom. This will be our custom theme.
Let's take a look at the files in the custom directory and see how all this works.
- register_theme.php - Registers the theme with Thyme so that it knows what functions to use to display content.
- functions.php - Theme functions that display content
- images/* - images directory
- style/style.css - CSS file for this theme
The first file we need to edit is register_theme.php. Open it up in your favorite text editor.
<?php
##################
#
# DEFUALT THEME
#
#################
# register functions below
_ex_theme_register("_ex_content_title","_ex_default_content_title");
_ex_theme_register("_ex_section_header","_ex_default_section_header");
_ex_theme_register("_ex_tabs","_ex_default_tabs");
_ex_theme_register("_ex_content_header","_ex_default_content_header");
_ex_theme_register("_ex_content_footer","_ex_default_content_footer");
_ex_theme_register("_ex_cal_title","_ex_default_cal_title");
require_once(@constant("_CAL_BASE_PATH_") ."themes/default/functions.php");
?>
You'll see that this file first calls _ex_theme_register() 5 times. These tell Thyme's theme engine what functions to call for each of a theme's components. This is in the fomrat of:
_ex_theme_register([component],[function to call]);
function to call must be a unique function name. The standard used in all of Thyme's existing themes is _ex_theme_name_component.
The last item includes (requires to be exact) the theme file that contains all of our custom functions. The constant _CAL_BASE_PATH_ used in this statement is an existing constant that tells Thyme where to find itself. This should be require_once(), not include() or require().
All detailed explanations aside, this file is very easy to customize for our theme. We can globally search and replace all instances of the word default with custom. Now our register_theme.php file should look something like this:
<?php
##################
#
# DEFUALT THEME
#
#################
# register functions below
_ex_theme_register("_ex_content_title","_ex_custom_content_title");
_ex_theme_register("_ex_section_header","_ex_custom_section_header");
_ex_theme_register("_ex_tabs","_ex_custom_tabs");
_ex_theme_register("_ex_content_header","_ex_custom_content_header");
_ex_theme_register("_ex_content_footer","_ex_custom_content_footer");
_ex_theme_register("_ex_cal_title","_ex_custom_cal_title");
require_once(@constant("_CAL_BASE_PATH_") ."themes/custom/functions.php");
?>
Our register_theme.php file is now ready for use. That's it. A search and replace of default with the name of our theme.
Now that we've told the theme engine what functions to call, we'll have to create those functions. These are defined in functions.php.
To start our customization of this file, we must first change all the function names. In our current file, they are all called _ex_default_component() because we copied the file from the default theme. To change this to match our custom theme, we can do another global search and replace in our text editor. Replace all occurences of default with custom. Now all the functions that we pointed the theme engine to in register_theme.php actually exist. This is a good thing :).
You may now customize the contents of these functions however you wish. DO NOT change the function arguments.
You may see references to some global variables in Thyme. The contents and format of these are beyond the scope of this document, however, most of them should be self explanitory.
So now that Thyme's theme engine knows what function to call for each component, it would be helpful to know which coponents go where and what the function arguments are. We'll take a look at each component in order of appearance in a standard Thyme theme.
_ex_cal_title($calendar,$links)
This should print the calendar title, it's description, and any links that are used for this calendar. $calendar is an assiciative array containing (among other things) title, and description. $links is an array of links. This typically contains the calendar's details and post links, but may contain more in the future.
A very simple _ex_cal_title function may look like this:
<?
function _ex_custom_cal_title($calendar, $links)
{
echo("<h3 align='left'>{$calendar['title']}</h3>\n");
echo($calendar['description']);
if(count($links)) {
echo(" - ( ");
echo(join(" - ", $links));
echo(" ) ");
}
}
?>
_ex_tabs($tabs)
This function prints Thyme's tabs. $tabs is an associative array containing the following information:
- name - The display name of the tab
- selected - true/1 if the tab is selected
- url - The url that the tab should link to
A very simplistic _ex_custom_tabs() function may look something like this:
<?
function _ex_custom_tabs($tabs)
{
foreach($tabs as $tab) {
echo("<a href='{$tab['url']}'>");
if($tab['selected']) echo("<b>");
echo($tab['name']);
if($tab['selected']) echo("</b>");
echo("</a> ");
}
}
?>
_ex_content_header();
examplified in red
This function displays a header at the start of Thyme's main content. This is typically just below the tabs and is a reflected at Thyme's footer as well. Some themes do not print anything here. The default theme prints a black bar that matches the selected tab.
A very simple _ex_custom_content_header() may look like this:
<?
function _ex_custom_content_header()
{
echo("<hr width='100%'>\n");
}
?>
_ex_content_title($l="",$m="",$r="");
This function prints the title of the content Thyme displays as examplified in the screenshot above. The arguments $l,$m and $r are content items that should be aligned left, center, and right respectively.
A simple _ex_custom_content_title() may look like this:
<?
function _ex_custom_content_title($l="",$m="",$r="")
{
echo("<table><tr>");
echo("<td align='left'>{$l}</td>");
echo("<td align='center'>{$m}</td>");
echo("<td align='right'>{$r}</td>");
echo("</tr></table>");
}
?>
_ex_content_footer($footer_items);
This function prints the footer of Thyme and any items that should be contained in the footer. $footer_items is an array of items to be printed.
A simple _ex_custom_content_footer() may look like this:
<?
function _ex_custom_content_footer($footer_items)
{
echo("<hr width='100%'><br>");
if(count($footer_items)) {
echo("[ ");
echo(join(" : ", $footer_items));
echo(" ]");
}
}
?>
_ex_section_header($text);
This function prints section headers where ever Thyme has sections to display. The most common example of this is when viewing an event. The screenshot above displays a General and Repeating sections. Each black bar that displays this text is derived from the theme's _ex_section_header function.
A simple _ex_custom_section_header() may look like this:
<?
function _ex_custom_section_header($text)
{
echo("<table width='100%' border=1><tr valign='middle'>");
echo("<td align='left'><b>{$text}</b></td>");
echo("</tr></table>");
}
?>
Our custom theme now has all 5 of the theme functions covered. It is also very simple and ugly :). Feel free to spruce it up a bit!
Now we'll move on to images. Each theme must have an images directory. At a minimum, this must contian:
- next.gif - Used for the 'Next' button when navigating through a calendar
- prev.gif - Used for the 'Previous' button when navigating through a calendar.
- next_sm.gif - Small 'Next' button for mini calendars
- prev_sm.gif - Small 'Previous' button for mini calendars
Other images in this directory may override the default images that Thyme uses for icons based on their name. These include:
- printer.gif - Used as print view link
- up.gif - Used in column headings in event list view
- down.gif - Used in column headings in event list view
- error.gif - Used when an error or warning message is displayed. In the Events tab, select multiple events, then click 'Delete' to see this image.
- repeat.gif - Used to signify an event repeats in the event list on the 'Events' tab
- view_remove.gif - Used at Thyme's footer next to 'view: ' to hide Thyme's navigation panes
- view_left_right.jpg - Used at Thymes footer next to 'view: ' to show Thyme's navigation panes
Though you may override the default images for these by placing your own in your theme's images directory, you do not have to. In fact, none of Thyme's pre-built themes override the default images.
Now that we have functions and images covered, we'll move on to CSS. Each theme must have a style directory containing a file called style.css. The best thing to do is just open it up and start editing.
Note that all style information in this file is prefixed by '#cal'. This tells browsers to only apply this style information to items within the 'cal' div tag. This is done so that when integrating Thyme into another web site, a theme's style information does modify the site's existing style information.
That's it! Theme functions, icons, and css. Happy theming!
If you want to force all users to use your new theme, you can set the Site Theme option in Admin -> Site Settings.
|
