Creating and Understanding Themes

Introduction

There comes a time, when a user has become experienced with SMF, that they may wish to start developing their own themes. In this introduction, there is some useful information, for creating custom themes.

Recommendations for users, to create themes:

• Some knowledge of PHP basics
• Good knowledge of HTML (Hyper Text Mark-up Language)
• Good knowledge of graphics creation and optimizing
• Some inspiration

Quickstart

To be able to create a theme, the user first needs administration privileges on the SMF install that they are using. They would need to follow this path through their admin panel:

Administration Center > Configuration > Themes and Layout > Manage and Install

The Install a New Theme dialog contains three fields to take look at. The user can install a new Theme from a file, from a directory on the server, or create a copy of the default theme. If they want to create a new theme, they can ignore installing a Theme from a file, or from a directory on the server; these are mainly used for packed distributed themes. The user needs the "Create a copy of Default named" field. Here, they can change the name to whatever they want, or they can leave it as it is. They should select "Install!" and select "OK" for any dialog boxes that may appear - their new Theme should be up and running. A copy of a Default theme will not copy the whole Theme - instead it just copies the following files:

• index.php
• index.template.php
• css/index.css
• css/rtl.css
• scripts/theme.js

the directory images and creates the file Theme-info.xml.

If they wanted to change anything else, apart from the overall look of the Forum header and footer or the stylesheet, they would have to add the corresponding file (or template) into their new theme's directory. Say the user wanted to change something on the Board index, or completely redesign it. They would need to copy BoardIndex.template.php from the Default theme into their new theme's directory.

Themes "fall back" to the default version of a template if that template file cannot be found in the current theme's directory. This is why only few files are included in the user's new Theme to begin with - if they are only changing how the Forum will look overall, the theme will pull the other template files and images from the default theme. This makes it a lot easier to upgrade a SMF forum without having to rewrite the parts of the user's theme they did not change anyway.

What is a theme

A Theme is the look and feel of the forum. Themes can be switched by members, and usually have HTML, CSS, JavaScript, and images. Themes control virtually every visual aspect of SMF, allowing easier customization.

What is the default theme, and what is it there for

The "Default" theme is actually not the "default theme." While SMF starts out with it as the base theme, the "Default" theme is only a collection of the default templates. These templates are "fallbacks" in case the current theme does not have the correct template.

It is similar to URLs - if the base domain name isn't specified, (in example, just /style.css) it uses the default (making the URL, www.simplemachines.org/style.css). In this case, it works a bit different, but the concept is similar.

I don't like or want the default theme - can't I just change it

Although changing the default theme is not recommended, the site owner may do whatever they wish with their forum. Some reasons that changing the default theme is not recommended, is some other theme might expect the default template, and leaving the default templates alone makes upgrading easier.

Do not worry - administrators can make the Default theme not able to be selected.

What's with all this template business

A template is a collection of related sub templates. Templates can be left out of a theme, as they will come from the SMF default theme - but sub templates cannot. The real question is: What's a sub template.

What's a sub-template

A sub-template is what the HTML is in. For example, admins can change the admin_login sub-template to make the administrative password prompt look different. They could change the error sub-template to change what is displayed upon an error.

It's important to note that sub-templates are grouped within templates. The error sub-template "template_fatal_error()" can be found in the Errors.template.php, just as shown below.

// Show an error message...
function template_fatal_error()
{
   global $context, $settings, $options, $txt;

   echo '
<table border="0" width="80%" cellspacing="0" align="center"
cellpadding="4" class="tborder">
   <tr class="titlebg">
      <td>', $context['error_title'], '</td>
   </tr>
   <tr class="windowbg">
      <td style="padding-top: 3ex; padding-bottom: 3ex;">
         ', $context['error_message'], '
      </td>
   </tr>
</table>';

   // Show a back button (using javascript.)
   echo '
<div align="center" style="margin-top: 2ex;">
<a href="javascript:history.go(-1)">', $txt[250], '</a>
</div>';
}

Breaking it down:

Code:

// Show an error message...

This is used for comments to guide and tell the admin what the following block of code is.

Code:

function template_fatal_error()
{

}

In JavaScript, this is the sub-template that will be executed upon encountering an error.

Code:

global $context, $settings, $options, $txt;

This is a PHP declaration of some variables.

Code:

echo '
<table border="0" width="80%" cellspacing="0" align="center"
cellpadding="4" class="tborder">
   <tr class="titlebg">
      <td>', $context['error_title'], '</td>
   </tr>
   <tr class="windowbg">
      <td style="padding-top: 3ex; padding-bottom: 3ex;">
         ', $context['error_message'], '
      </td>
   </tr>
</table>';

This is the actual HTML that will be sent to the browser. Note the use of the previously declared variable, $context.

Code:

// Show a back button (using JavaScript.)

This is another comment.

Code:

echo '
<div align="center" style="margin-top: 2ex;">
<a href="javascript:history.go(-1)">', $txt[250], '</a>
</div>';

This is some more HTML code that will be sent to the browser.

Where do I get templates and sub-templates

All the themes, by default, are stored in the Themes directory inside your Forum installation directory. Inside this should be a few directories, each corresponding to a different theme. Inside one of these directories is a list of templates - for example, Errors.template.php. If you open this file up, you should see that it has the sub templates inside it.

How do I know which sub-template I need to change

For most things, you want to change the main layer. Layers are pairs of sub-templates that go above and below the next template layer, or the content. By default, there is only one layer -- the main layer. Its two sub-templates are main_above and main_below.

For other layers, please see the list below.

I'm done with templates... What else

To give your Theme a unique look, you may need to modify/add your own graphics to it. The easiest way to add/modify your own graphics is by copying the images directory from the SMF default theme to your new theme. Once done you can modify or add graphics to (in order of directories):

• bbc - bulletin boards buttons which are used mainly in Post screens.
• english - buttons used in forum's menu, Board index , message ..etc.
• icons - icons used in various part of the forum.
• post - icons used for posts.
• topic - topics indication images.

Also the main directory (images) contains various images used in many places in your forum, such as your Theme thumbnail, messenger indicators, stars, etc.

You can call an image from your Theme by using:

<img src="', $settings['images_url'], '/smflogo.gif" alt="" />

where

', $settings['images_url'], '

points to your theme's images directory.

or by using:

<img src="', $settings['images_url'], '/', $context['user']['language'], 
'/userinfo.gif" alt="" />

Where

', $settings['images_url'], '/', $context['user']['language'], '

points to your theme's images/english directory, if English is selected as user default language. This will give you the possibility of making another directory for a different language. So, you can have buttons for English and Dutch for example.

This is confusing... I just want to change something simple!

Most of the sub templates are just HTML. The only notable thing is that if you want to use an apostrophe, you must put a \ before it. So, instead of putting "it's" in there, you would need to put "it\'s".

It is not difficult; great pain has been taken to make the sub templates simple and they use PHP code. You only need a basic understanding of PHP to understand them.

Well, I might be able to do some... but there are just so many files!!

You only need to Modify the index template. (the main template) to affect most of the layout of your forum.

You can do this by going into the Administration Center > Configuration > Themes and Layout > Themes Settings". In there, select one of the themes present and it should be possible to edit the files, rename it, and change settings.

Please note that the SMF default theme cannot be modified from the Administration Center, but it's possible to create a copy of it and change the files of the new theme.

What is context

Context is basically, well, the context of this page view. In other words, it's what makes one view different from the next or last. Maybe there are more or less boards... maybe someone posted a new topic... these are all things the template context can tell you. The same context information isn't available everywhere. For example, the list of boards you can move a Topic to isn't there when you are editing your Profile because that's illogical.

What is the difference between settings and options

Settings are global for all users, while options are only for the current member.

These settings and options are also affected by the "default affect" - if there is a setting in the " SMF default theme", it is used as the "fallback" for all other themes.

Is there a list of templates

All templates are found in the theme directories. Most of these will be inside the default theme directory, unless a custom theme uses a customized version of it.

• Admin - this is for the Administration Control Panel area.
  Sub templates: admin_above, admin_below, admin, credits, edit_news, edit_agreement, view_versions, edit_censored, maintain
• BoardIndex - this is the Board index. That's the main page of the forum.
  Sub templates: main
• Calendar - the calendar, and related sub templates.
  Sub templates: main
• Display - the posts themselves.
  Sub templates: main
• Errors - error messages.
  Sub templates: fatal_error, error_log
• Help - for the Admin help and find Member box.
  Sub templates: popup, find_members
• index - this is the stuff around the main content that goes on every page.
  Sub templates: init, main_above, main_below, menu
• Login - basic login, as well as maintenance login and admin verification.
  Sub templates: login, kick_guest, maintenance, admin_login, retry_activate, resend
• ManageAttachments - Attachment management, delete, view, etc.
  Sub templates: main
• ManageBoards - manage boards, add, modify, delete, etc.
  Sub templates: main, modify_category, confirm_category_delete, modify_board
• ManageMembers - manage members and groups, add, modify etc.
  Sub templates: main, new_group, edit_group, group_members, email_members, email_members_compose, view_members, ban_list, ban_edit, ban_log, edit_reserved_words, trackUser, trackIP, showPermissions, announce, announcement_send
• ManagePermissions - mange permission.
  Sub templates: main, modify_group
• ManageSmileys - mange smiley, add remove arrange, etc.
  Sub templates: settings, editsets, modifyset, editsmileys, modifysmiley, addsmiley, setorder
• Memberlist - the memberlist, which can be viewed and searched.
  Sub templates: main, search
• MessageIndex - the message index, or in other words boards.
  Sub templates: main
• Modlog - moderation log.
  Sub templates: main
• MoveTopic - moving a topic.
  Sub templates: main
• Notify - confirmations for turning on/off notifications. Seldom seen except via email.
  Sub templates: main, notify_board
• Packages - package management, add, browse, install, etc.
  Sub templates: main, package_above, package_below, view_package, extract_package, list, examine, view_installed, browse, servers, package_list, downloaded, install_options
• PersonalMessage - instant message display, sending, etc.
  Sub templates: directory, send, ask_delete, prune
• Poll - poll editing.
  Sub templates: main
• Post - posting a new topic, a reply.
  Sub templates: main, postbox, spellcheck
• Printpage printing a topic.
  Sub templates: print_above, main, print_below
• Profile - the profile, editing and viewing alike.
  Sub templates: profile_above, profile_below, summary, showPosts, statPanel, account, forumProfile, theme, notification, pmprefs, deleteAccount, profile_save
• Recent - recent posts, unread topics and unread replies.
  Sub templates: main, unread, replies
• Register - registration... before and after.
  Sub templates: before, after, admin_browse, admin_register
• Reminder - forgot your password?
  Sub templates: main, sent, set_password, ask
• Search - this is the main search screen and results.
  Sub templates: main, results
• SendTopic - who're you going to send it to?
  Sub templates: main, report
• Settings - Theme settings and options.
  Sub templates: settings, options
• SplitTopics - splitting and merging topics.
  Sub templates: ask, main, select, merge_done, merge, merge_extra_options
• Stats - statistics about your forum.
  Sub templates: main
• Themes - themes management.
  Sub templates: main, pick, installed, edit_style, edit_template, set_settings, set_options
• Who - who is online, and what are they doing?
  Sub templates: main
• Wireless - wireless access via WAP, WAP 2, or i-mode.
  Sub templates: wap_above, wap_boardindex, wap_messageindex, wap_display, wap_error, wap_below, imode_above, imode_boardindex, imode_messageindex, imode_display, imode_post, imode_login, imode_error, imode_below, wap2_above, wap2_boardindex, wap2_messageindex, wap2_display, wap2_login, wap2_post, wap2_error, wap2_below
• Xml - xml related
  Sub templates: quotefast, post, stats, split

Editing the main menu

The Main menu can easily be changed in SMF to add additional links to it and modify existing links.

How do I add buttons to the babylon and classic style themes?

There are generally two types of menus used in SMF prior to 2.0. The one type that typically consists of actual images is either the Babylon theme, the Classic theme or likely a theme that is based on one of them. Themes for SMF 1.0 will only use this style as the other menu style wasn't introduced until the new default theme in SMF 1.1 RC2 was released. For information on how to edit this type of menu, see How do I add buttons to the babylon and classic style themes

How do you add custom tabs to the Core (default) theme menu?

That however, is no longer the most common menu style used in SMF themes. Most themes made now, are based off of the SMF 1.1 "Core" theme, which uses a image-less, tab menu. If you want to edit this menu, the instructions are different from what is above. See How_do_I_add_custom_tabs_to_the_Core_(default)_theme_menu for how to edit the Main menu for the "Core" style menu.

How do I add buttons to SMF 2.0?

With 2.0, SMF has removed the main menu from the template files and used an array defined in Sources/Subs.php in order to have the menu defined in a single place, used across themes. This means that editing the main menu is not done in the template file(s) for each individual theme, but, instead, is done once for all themes (whether they use text or images). See How do I add buttons to SMF 2.0 for how to edit the Main menu for the "Curve" style menu along with most other themes on 2.0.

Theme Strings in Themes

As per the Theme Approval Guidelines, all text should be in a theme language string, however the Guidelines are lenient with copyrights and allow these to be hard-coded.

Theme authors will commonly place their strings into the wrong file, for example: Modifications.language.php (Eg: Modifications.english.php, Modifications.turkish.php). Although this is not technically the wrong place to put the strings, it will cause issues with modifications being installed on the theme.

When making a 1.x compatible theme you can simply add 2 or 3 extra lines of code into your index.template.php, which will call a ThemeStrings.language.php file where your strings can go. This will prevent conflicts with modifications and your theme.

Search for this in index.template.php:

/* Show sticky and lock status seperate from topic icons? */
	$settings['seperate_sticky_lock'] = true;

Replace it with:

/* Show sticky and lock status seperate from topic icons? */
	$settings['seperate_sticky_lock'] = true;
	/* Call to Theme String for languages */
	if(loadlanguage('ThemeStrings') == false)
		loadLanguage('ThemeStrings', 'english');

In 2.0 RC1 and onwards, a new way of including ThemeStrings.language.php would be to set $settings['require_theme_strings'] to true in index.template.php. It would look something like this:

Search for this in index.template.php:

/* Set the following variable to true if this theme requires the optional theme strings file to be loaded. */
	$settings['require_theme_strings'] = false;

Replace it with:

/* Set the following variable to true if this theme requires the optional theme strings file to be loaded. */
	$settings['require_theme_strings'] = true;

After doing this you will need to create language file specific for your language, i.e. ThemeStrings.english.php.

Note: ThemeStrings.language.php file has to be inside languages directory of your theme. You will need to create the directory yourself, if you're creating your own theme from scratch, or updating a theme that didn't have this directory in first place.