Overview

Tiki uses the Smarty template engine, so pages generally have a PHP file (.php) and a Smarty template (.tpl) associated with them. These produce the XHTML for the page, which is then given visual styles with CSS. The CSS is provided by a combination of some feature-specific stylesheets, default layout and design stylesheets, and theme stylesheets.

Concept (Tiki14)

There are several features that determine which theme is displayed for a given screen. See also http://doc.tiki.org/Themes

Site theme

Site theme setting can be made at the Look and Feel settings panel. Themes can have options.

Overrides:
- none

Overridden by:
- user theme
- group theme
- theme control
- perspective

User theme

If preference change_theme is enabled than users are allowed to change theme.

Overrides:
- site theme
- perspective

Overridden by:
- group theme
- admin theme
- theme control

Limited by:
- available themes

Group theme

Define a theme for a group (tiki-admingroups.php)

Overrides:
- site theme
- user theme
- perspective

Overridden by:
- admin theme
- theme control

Admin theme

Themes and theme options for the settings control panels (tiki-admin.php?page=XXX).

Overrides:
- site theme
- user theme
- group theme

Overridden by:
- perspective setting

Not affected by:
- theme control

Theme Control

Allows to have a specific theme for objects, categories and sections, see Documentation.

Overrides:
- site theme
- user theme
- group theme
- perspective

Overridden by:
- none

No effect for:
- admin theme

Perspective

Perspectives are to override a preference, see Documentation

Overrides:
- site theme
- admin theme

Overridden by:
- user theme

How Tiki decides which theme to display

1) Check for user's theme preference

2) If there is a group theme defined, override user's theme

3) If Theme Control feature is enabled, then override the above like this:
- If a theme is assigned to the individual object that theme is used
- If not then if a theme is assigned to the object's category that theme is used: but if the object is assigned to multiple categories and this causes a conflict in the theme choice then they are all skipped and the next logical choice in this hierarchy is chosen
- If not then a theme for the section is used

4) If an admin page (Settings control panel) is displayed, check if there is any admin theme set to override. When in a perspective, check if there is a perspective specific setting and override if available.

5) If none of the above applies, use the site theme. When in a perspective, see if there is a perspective specific setting and override if available.

Theme related CSS files

Basics

1) Tiki always loads themes/base_files/css/tiki_base.css, no matter which theme is selected. This file contains rules specific to Tiki that Bootstrap doesn't have awareness of.

2) The css file of a theme (or theme option) must always have to be named like this: tiki.css. So they will no more match the name of the theme, This isn't necessary if the theme is selected by specifying the Custom theme URL, but if it's selected as a theme in the "themes" directory, then it needs to follow that naming scheme.

Create a new theme or theme option

New theme

If you want to create a new theme for Tiki, you have place a tiki.css file under the css folder in the theme (eg: themes/mytheme/css/tiki.css).

New theme option

If you want to create a simple new option called myoption (eg: for the jqui theme), than proceed like this:

• step1) create a new subfolder under the "themes/jqui/options" folder called "myoption/css" (so path is: "themes/jqui/options/myoption/css/")
• step2) place in the new folder a file called tiki.css that contains the changed or additional css for your new option (eg: "themes/jqui/options/myoption/css/tiki.css") - this is loaded in addition to the tiki.css file in the main css folder eg themes/jqui/css/
• step3) optionally place in the new folder a custom.css file that contains your specific local customizations for that one Tiki instance (eg: "themes/jqui/options/myoption/css/custom.css") - this too is loaded in addition to any custom.css file that is placed in the main css folder eg themes/jqui/css/

For more complex options you can also have the same folder structure as for a normal theme (fonts, icons, images, templates, etc).

Customizaton of themes and options

If you want to slightly modify (change some colors, backgrounds, etc) a theme or a theme option shipped with Tiki then it may be easier for you, if you don't edit the theme files directly, but create a custom.css file in the same directory of the theme or theme option and store your customizations there.

If you have a main theme with theme options, you can have a custom.css for the main theme and another custom.css for the theme option, both will be loaded (first the main theme's custom.css, then the theme option's custom.css)

To create a highly customised theme however it may be better, from an onward change management point of view, to add your own option to an existing theme. This then lets you use all the css from the main theme as a 'base' for your customised theme and this will be automatically maintained/updated for subsequent Tiki version changes. All you have to do then is to develop your option css and change this from time to time as may be necessary due to Tiki version upgrades and you can use your own naming convention for the option and its subsequent versions for your change management process.

Loading css files

• For a main theme Tiki gets first the theme's main css file (eg: from themes/mytheme/css/tiki.css), then a custom.css file containing local customizations if found in the theme's css folder (eg: /themes/mytheme/css/custom.css)
• If a theme option is enabled, then Tiki gets first the main theme's css file (eg: from "themes/jqui/css/tiki.css") then it gets the theme option's css file ("themes/jqui/options/myoption/css/tiki.css"), and then it loads the main theme's custom.css (eg: from "themes/jqui/css/custom.css") and finally the theme option's custom.css file containing local customizations if found in the option's folder (eg: "themes/jqui/options/myoption/css/custom.css")

Theme related smarty template files

Basics

• Tiki uses smarty templates
• Tiki ships all basic template files in the "templates/" folder.

Customization of templates

If you don't like how, for example, a blog post (templates/tiki-view_blog_post.tpl) looks like, you can have your own, redesigned template.
You have a number of ways of implementing this however as follows:
1) If you want to have a custom template available for all your themes, you should put the altered or new template file in the "themes/templates/" folder.
2) If you want to have a custom template for a given theme and all its potential options, put the template file in the "themes/mytheme/templates" folder
3) If you want to have a custom template for just one specific theme option, put the template file in the "themes/mytheme/options/myoption/templates" folder

In this way you can manage a hierarchy of choices so that the same .tpl file can have different content depending upon whether it is available at a specific level in this choice hierarchy.

How Tiki decides which template to display

1) first try to use the theme option's template folder (eg: "themes/fivealive-lite/options/watermelon/templates/tiki-view_blog_post.tpl)
2) than try to use the theme's template folder (eg: "themes/fivealive-lite/templates/tiki-view_blog_post.tpl)
3) than try to use "themes/templates" folder (eg: "themes/templates/tiki-view_blog_post.tpl)
4) finally use "templates/" folder ( (eg: "templates/tiki-view_blog_post.tpl))

Developer info

The different theme settings are stored as preferences and can be accessed as smarty variables.

Preferences

Theme related preferences:
$prefs['theme_active'] - The theme that is actually displayed. This is a dynamic preference, so it is not stored in the database.
$prefs['theme_option_active'] - The theme option that is actually displayed. This is a dynamic preference, so it is not stored in the database. Empty if no option is set.
$prefs['theme_admin'] - The theme to be displayed for admin pages. Stored in tiki_preferences table.
$prefs['theme_option_admin'] - The theme option to be displayed for admin pages. Stored in tiki_preferences table.
$prefs['theme_site'] - The theme setting for the site. Stored in tiki_preferences table.
$prefs['theme_option_site'] -  The theme option setting for the site. Stored in tiki_preferences table.
$prefs['available_themes'] -  List of themes and theme options available for users to pick their preferred theme for the site, Stored in tiki_preferences table.
$prefs['user_theme'] - The user's theme preference. Stored in tiki_user_preferences table.
$prefs['user_theme_option'] - The user's theme option preference. Stored in tiki_user_preferences table.
$prefs['tc_theme'] - The current theme control setting for theme. This is a dynamic preference, so it is not stored in the database.
$prefs['tc_theme_option'] - The current theme control setting for theme option. This is a dynamic preference, so it is not stored in the database.
$prefs['theme_path'] - The path of the currently displayed theme (knows about multidomain if set). This is a dynamic preference, so it is not stored in the database.

Theme selection logics

Theme selection is primarly done at lib/setup/theme.php. If you enable Theme Control, than after lib/setup/theme.php has finished tiki-tc.php kicks in and makes sure that Theme Control settings are applied.

Template selection logic

Template selection is done using lib/init/smarty.php.

Upgrade to Tiki14

The structure of themes changed singificantly for Tiki14, so please note the below points:
- your old themes wont work, you will see the Default Bootstrap theme after an upgrade. See How To Add a New Theme
- you have to set themes manually after an upgrade for group theme, site theme, theme control and user theme
- the only change in the database is the renaming of user theme preference (table name: tiki_user_preferences). Only the prefName column is overwritten. Still the value has to be changed for each user. (Could this be managed using a wizard??)