Theme Authoring

From GregariusWiki

Contents 1 Introduction 1.1 Installing a theme 1.2 Writing a theme 2 Structure of a Gregarius theme 2.1 Style sheets 2.2 Meta information 2.3 Media 2.4 PHP Files 2.5 Markup 2.5.1 Standardization of Meta-information 3 Inheriting from the default theme 4 Theme wrappers and helpers 5 Adding a plugin to a theme 6 Coding Guidelines 7 Changes in the 0.5.4 (and the recent svn versions)

[edit] Introduction

Themes are used to alter the look and feel of a Gregarius installation.

Some themes are simple and provide cosmetic changes to the layout and the images. Others are complicated and can change the behavior of Gregarius completely. They can also edit the functionality that Gregarius provides.

[edit] Installing a theme

To install a theme, users:

• Unzip the theme archive in the themes/ sub-directory of rss/
• Activate it in the Config section of their Gregarius administration interface.

Themes can also be loaded if ?theme=YourThemeName is appended to a Gregarius URL.

[edit] Writing a theme

Writing a Gregarius theme can be very simple. If you know a little bit of CSS you can give a theme a different style. With a little knowledge of PHP you can change the behavior and funcionality that Gregarius provides. Gregarius has a theme engine that is similar to that of Wordpress. If you have ever written a Wordpress Theme, you should have no trouble writing a theme for Gregarius. Help is always available on the Forums and the gregarius-dev mailing list. After you have written your theme, please consider releasing your theme on the Theme Repository.

[edit] Structure of a Gregarius theme

In their simplest form, themes are just templates to render objects and pages in Gregarius. When Gregarius wants to display a page or render things like feeds, items and lists it will call the appropriate template files in the current theme.

[edit] Style sheets

Themes should contain a subdirectory called css/ which should contain the theme's css in two css files look.css and layout.css.

[edit] Meta information

A .themeinfo file should also be placed in the theme directory. This allows the theme to be selected in the configuration part of the admin section of Gregarius. A sample .themeinfo file looks like this :

name: Disney theme
official: false
description: A theme for the young'uns.
author: Tweety Bird
url: http://example.com/theme_author_url
version: 1.1
screenshot: shot.png

Note: the screenshot, if any, should be located in your theme directory and shouldn't exceed 320 per 220 pixels.

[edit] Media

If your theme requires media like images, flash, java etc, you should store them in the media/ subdirectory of your theme. For example if you have file called tweety.gif in your media directory, you can write an http link to it anywhere in your theme via the line

"<?php echo rss_theme_path(); ?>/media/tweety.gif"

[edit] PHP Files

Additionally, the theme can contain the following php template files to render pages and objects. These files are optional because Gregarius will load any missing files that are needed from the default theme. If your theme is similar to the default them, then it makes sense to only provide those files where your theme differs from the default theme.

Filename	What it renders	Where is it shown in the default theme	Notes
catfolder.php	Renders the Categories	In the sidemenu	This is exactly the same as feedsfolder.php but for categories instead of feeds.
error.php	Renders the Error messages	Anywhere there is an error	Of course this never happens :)
feed.php	Renders a feed	In the main items div	This usually requests the feeds items to be displayed when it is neccessary to do so.
feedsfeed.php	Renders a feed's RSS/ATOM feed info	In the sidemenu	This usually renders meta information about a feed like the RSS/ATOM URL, title, favicon etc..
feedsfolder.php	Renders feed info	In the sidemenu	This usually renders the feed title, unread count and collapsed state in the sidemenu.
feeds.php	Renders a column of feeds	In the main items div	This usually renders the title of the feeds, the stats and the column of feed folders.
footer.php	Renders the footer	In the footer of every page	The footer usually contains the version number and a link back to the Gregarius website.
header.php	Renders the header	In the header of every page	The header contains links to stylesheets and javascript and other things usually found in a header.
index.php	Sets the layout of everything on the page	Part of every page	This is the most important file in your theme. If this file is empty, nothing is rendered on any page.
itemlist.php	Renders a list of items	In the main items div	 
item.php	Renders an individual item	In the main items div	 
navitem.php	Renders each navigational items like Home, Admin, etc...	Below the header and title	 
nav.php	Renders a list of navigational items.	Below the header and title	This usually requests all the navigational items to be loaded.
searchform.php	Readers the searchform	In the main div after clicking the Search button	 

[edit] Markup

The CSS files should contain CSS markup. The php files are a mix of php and html markup. For example on of the files above could have include a block of code that looks like this

<meta http-equiv="refresh"  content="<?php echo rss_header_autorefreshtime(); ?>;<?php echo rss_header_autorefreshurl(); ?>" />

The default output is html, except for the code that is enclosed in the <?php and ?> tags. You can put any arbitrary php code in between these tags or you may call php code that already exists in Gregarius. Several wrapper and helper functions are available to do the latter more efficiently. Remember to follow the Coding Guidelines otherwise you will quickly run into trouble.

[edit] Standardization of Meta-information

To facilitate client-side scripting, the following standardized meta-information should be applied by theme authors, in the web medias of their themes:

• item.php:
  • The main HTML container of RSS item elements should expose the item ID in an id="item_ID" attribute, e.g.
    <li class="<?php echo rss_item_css_class(); ?>" id="item_<?php echo rss_item_id(); ?>">
  • The main (external) link for each RSS item should have an item_url class attribute, e.g.
    <a href="<?php echo rss_item_url(); ?>" class="item_url">

Note: this standard was first introduced in #1709.

[edit] Inheriting from the default theme

All the php template files are optional. If Gregarius needs any of them then it will load any missing files that are needed from the default theme. If your theme is similar to the default them, then it makes sense to only provide those files where your theme differs from the default theme. You will still need to provide the media files in your own theme.

[edit] Theme wrappers and helpers

Theme wrappers and helper functions help you call parts of the Gregarius code into your theme. These functions are available in rss/cls/wrappers. A list of wrappers with some additional documentation will eventually be made available on this wiki. In the meantime the source code in rss/cls/wrappers is very readable. As an example, the function

<?php echo  rss_footer_last_modif(); ?>

defined in rss/cls/wrappers/header.php prints out when Gregarius was last updated. The default theme uses this function in the footer.php. In fact it can be used in any of the php template files.

[edit] Adding a plugin to a theme

Gregarius allows themes to come with their own plugins. All you need to do is define a plugins.php file in your theme directory. Then whenever your theme is selected, your plugin.php file is automatically executed. You do not need the user to activate them in the config section. The 3 panes theme is an example of a theme that uses this.

[edit] Coding Guidelines

• Please do not use short open tags like <?= as they are not enabled on all systems. Instead you should use open your tags with <?php
• All the php statements in the theme files need to be terminated by a semicolon, otherwise it will not be cached properly. The statements should look like

<?php echo "This is a string"; ?>

Note: The default theme does not follow this second point correctly. Don't worry. At some point we will pay for these mistakes.

[edit] Changes in the 0.5.4 (and the recent svn versions)

• All theme files (excluding .themeinfo and the screenshot) for desktop web browsers must go into the web/ sub directory of your theme. See the lilina theme (included in the source distribution) for an example of how to do this. You can also have a subdirectory for mobile devices, see the default theme for an example.