Themes

Table of Contents

• Overview
• Creating a Theme
• Dealing with New Components

Overview

A toolkit theme provides additional styling information that is automatically applied to components during rendering. This way, presentation (CSS, etc.) is not handled by the components themselves, or even by the user of the components, but is instead done in a single separate place: a theme.

A theme essentially provides a set of default values for CSS styling properties which are applied right before rendering. Themes can build upon other themes, inheriting those themes' defaults as well as adding new ones.

Themes also support the concept of a "theme class" (not to be confused with a PHP class that is used to implement a theme). A theme class is a way to provide alternate stylings for a component or set of components within a theme. Your theme may, for example, provide different styles for buttons depending on how the buttons are used. Some buttons may need to look one way and other buttons a different way. Normally, themes set the style for all instances of a given component. However, in this case, we want some buttons to use a different style. We can assign those buttons to different theme classes and then the theme can specify different stylings for different theme classes.

Creating a Theme

Usually, you will want to extend the default theme. The default theme is used as-is by Snap2, so you can look there to see what it normally looks like. If you truly want a completely different style, then you can create your own theme from scratch. Either way, the process is almost exactly the same. You create a theme class that starts with 'TK' and put it somewhere that autoload can find it (such as an app/tk directory in your project, and then add app/tk to the list of autoload paths). Then you will create the following skeleton code:

<?php

// extend TKDefaultTheme if you want to use the default theme as your base
class TKProjectTheme extends TKTheme {
    protected function initialize() {
        // if you extend TKDefaultTheme, you need the following line
        //parent::initialize();

        // INITIALIZATION CODE GOES HERE
    }
}

?>

The remainder of the code goes inside the initialize() method, where the comment "INITIALIZATION CODE GOES HERE". You will essentially have a list of lines containing calls to $this->setThemeDefault(). There are a few variations on this method, which will be detailed below.

The simple case of setThemeDefault() is to set one of the *_class properties for a component. Suppose that we want a table to have a certain CSS class (and that class will be defined in a project CSS file somewhere). We then add this call:

$this->setThemeDefault('TKTable', 'class', array('projectTableClass'));

This sets the class property of TKTable to be 'projectTableClass' (the array is needed because class properties are array, not scalar, properties). If the class property of a TKTable object is not modified by the user, it will automatically be set to 'projectTableClass'. If the user does modify the class property, then the user's value and the theme's value will be merged (so you will see class="projectTableClass userClass" instead of just class="projectTableClass" on the <table> tag in the HTML).

The setThemeDefault() method completely overrides whatever was set for that component and property before, either by a theme that you inherit from, or a previous statement in the initialize() method. If you want to merge defaults, you need to do that manually. The following code gives one possible way to do that:

// get the old value (note that we must specify the theme class of 'default')
$old = $this->getDefault('TKTable', 'default', 'class');

// make our own setting for the 'class' property
$mine = array('projectTableClass');

// merge the old and the new
$merged = array_merge($old, $mine);

// and set the default to the merged value (including the old and ours)
$this->setThemeDefault('TKTable', 'class', $merged);

Because of the above example, this is a good place to talk about theme classes. A theme class, as mentioned above, allows us to not only assign defaults for components, but particularly classes of a given component. We might have tables for listing users, tables for listing classes, etc. And we might want to have a different appearance for each type, even though they are all TKTables. So we can create several theme classes, which is done by using an additional argument to setThemeDefault():

// add setting for TKTables that display user lists
$this->setThemeDefault('TKTable', 'user_listing', 'class', array('projectUserListTable'));

// add separate setting for TKTables that display class lists
$this->setThemeDefault('TKTable', 'class_listing', 'class', array('projectClassListTable'));

// and provide a suitable default appearance for TKTables
$this->setThemeDefault('TKTable', 'class', array('projectTable'));

Now, to tell a component to use a different theme class than the default, we just use this code:

$table = new TKTable();
$table->setThemeClass('user_listing');

Dealing with New Components