Difference between revisions of "Theme Developers Guide"

From GeeklogWiki
Jump to: navigation, search
(Geeklog’s theme engine)
Line 12: Line 12:
 
To use the new theme engine you must set in your theme's function.php a config variable:
 
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';
+
;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.  
 
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 /javascript/fix_html.js is required. Javascript code also needs to be added in the footer of the theme that runs  
+
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');  
+
;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.
 
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.

Revision as of 00:01, 23 February 2013

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 or check us out in IRC at irc.freenode.net in #geeklog.

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