glFusion Wiki

Site Tools


glfusion:development:themes

Creating a Theme for glFusion

Creating a theme for glFusion is easy and quite fast. The code, contents, theme (used interchangeably with the word 'layout' here) and system language are properly separated.

If you know beginners level HTML and simple CSS then you can create a theme! There's no need to learn PHP / MySQL nor complicated CSS.

Theme Basics

First, create a new directory alongside the Nouveau directory. No spaces are allowed in the new theme name!

Your existing theme is here: public_html/layout/nouveau

The new theme may be here: public_html/layout/new_theme

Keep the original Nouveau theme on your webspace! This is not only good for trouble shooting, but will allow you to only include files in your theme that differ from the default versions in the Nouveau directory.

Now copy the functions.php file and files that you would like to change from the /nouveau directory into new_theme/ directory, and edit the .thtml files to suit your needs. The .thtml files are more or less HTML files with CSS and some JavaScript at times. The directory you just created (new_theme) holds ALL templates glFusion needs apart from those being used by plugins. You will only need to modify a small few to make a huge impact on the look.

You can also create a /new_theme/plugins/plugin_name directory and customize any of the default templates for plugins that aren't found in the normal theme folder. glFusion will always look there for template files before using the default versions from the /private/plugins/ directories. This allows you to easily customize all aspects of the system, for any given theme.

In particular some templates you will undoubtedly want to change:

  • header.thtml (the top horizontal portion of your site)
  • footer.thtml (the bottom horizontal portion of your site)
  • leftblocks.thtml (the left sidebar of your site)
  • rightblocks.thtml (the right sidebar of your site)
  • style.css (all the structure, and style definitions, etc.)
  • style-colors.css (all the color definitions)

Maybe also:

  • featuredstorytext.thtml
  • storytext.thtml
  • archivestorytext.thtml

How themes work

When rendering a theme, glFusion starts with htmlheader.thtml which builds the site's header (along with header.thtml), and then goes on to include the middle part of a page which 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 left and right columns of blocks (using the variable {left_blocks) and {right_blocks}. Blocks themselves consist of the blockheader.thtml and blockfooter.thtml files.

The above only describes how glFusion's main page and stories are rendered. More templates exist for the various editors and lists you will see in glFusion, as well as for the calendar and almost every other part of glFusion.

There is currently no complete list available that explains which template file is used for which part of glFusion. 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 glFusion, 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.

Testing a Theme

After you have created your new theme, you are now ready to test it out. Simply go to http://yourglfusionsite/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 logos 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 /private/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 feel free to post in our forums.

Tips and tricks

Themes and WYSIWYG editors: The template files used by glFusion are not complete HTML files - they contain only parts of the HTML that glFusion 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 in glFusion. We suggest you use a simple text editor to edit your themes.

Different look for left and right blocks: You can give the blocks on the left and right a different look.

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.

Error Message: 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.

glfusion/development/themes.txt · Last modified: 2015/07/11 17:43 (external edit)