History: Theme-related Software Concept and Design

• «
• »

            {maketoc}
!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)
{REMARKSBOX(type="info" title="please mind" close="n")}
Status 8th Dec 14: As a number of design and layout concepts changed with effects to the directory structure, s ome of these features are not (yet) working after an upgrade to pre-14 trunk, but the developers are working on getting the functionality back into Tiki14. Hopefully we get there before branching. Until then this page is meant to determine the missing parts and the concepts how to integrate the old or improved functionalities. {REMARKSBOX}
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

{REMARKSBOX(type="info" title="Available themes" close="n")}
In the Look&Feel settings page it is possible to limit the list of the themes users can pick from when changing theme is allowed (preference name: available_themes). It is not possible to limit theme options, so all options of the allowed themes shall be available for selection.
{REMARKSBOX}

!!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 for the  settings control panels. (tiki-admin.php?page=XXX) . Can have options too.

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 [http://doc.tiki.org/Theme+Control|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  [http://doc.tiki.org/Perspectives|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, than 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
- 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) 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. 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
{REMARKSBOX(type="info" title="Tip" close="n")}
More information about how to structure a new theme: ((How To Add a New Theme))
{REMARKSBOX}
!!!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). 
{REMARKSBOX(type="info" title="Please note" close="n")}
The themes/base_files/tiki_base.css has rules for Tiki-specific things (similar to the old layout.css and design.css). It doesn't have anything related to Bootstrap, though, such as the grid, form classes, and so on. These have  to be provided by the theme stylesheet.
It isn't necessary to use Less to make the theme stylesheet, as long as the end product is essentially a bootstrap.css equivalent. That is, the theme stylesheet needs to contain the grid layout classes, rules for responsive behavior, and so on in addition to the color and typography rules, etc. for the theme. 
Anyway, this is what we might think of as the "standard" way, with the fewest separate CSS files.
More information about how to structure a new theme:  ((How To Add a New Theme))
{REMARKSBOX}

!!!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 css for your new option (eg: "themes/jqui/options/myoption/css/tiki.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")

For more complex options you can also have the same folder structure as for a normal theme (fonts, icons, images, templates, etc).
{REMARKSBOX(type="info" title="Tip" close="n")}
If you just want a few simple changes to the default Bootstrap theme, than create  a new option under "themes/default/options/" 
This way the new theme doesn't have to have the bootstrap rules. The new theme can just override or add to the bootstrap rules, essentially being a Bootstrap theme option. 
{REMARKSBOX}

!!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 than it is better 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. 
Your customizations will override the rules of the theme like this:
* For a main theme Tiki gets first the theme's main css file (eg: from themes/mytheme/css/tiki.css), than 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, than Tiki gets first the theme's main css file (eg: from "themes/jqui/css/tiki.css") than get the option's css file ("themes/jqui/options/myoption/css/tiki.css"), than 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. 
{REMARKSBOX(type="info" title="Tip for Tiki14 upgraders" close="n")}
The goal of moving customization stuff to the "themes/" folder was to have self-contained themes, which means that you can store all your site customizations (css, templates, images, etc) in this folder. This move should make your life easier. However, you should be aware, that if you are upgrading from preTiki14 version than you have to move your custom templates from the legacy "templates/styles/mycustomizedtheme/" folder to "themes/mycustomizedtheme/templates" folder. ("mycustomizedtheme" is not an actual folder name, it is just an example)
{REMARKSBOX}

!!Customization of templates
If you don't like how for example how a blog post (templates/tiki-view_blog_post.tpl) looks like, you can have your own, redesigned template. 
You have the below options:
1) If you want to have a custom template available for __ALL__ your themes, you should put the template file to "themes/templates/" folder. 
2) If you want to have a custom template for a given theme, put the template file to "themes/mytheme/templates" folder
3) If you want to have a custom template for a given theme option, put the template file to "themes/mytheme/options/myoption/templates" folder

!!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 in preferences and can be accessed smarty variable
!!Preferences
{CODE()}Theme related preferences:
$prefs['theme_active'] - this is the theme that will be displayed
$prefs['theme_option_active'] - the option to be displayed
$prefs['theme_admin'] - the theme to be displayed for admin pages
$prefs['theme_option_admin'] - the option to be displayed for admin pages
$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 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 preference stored in tiki_user_preferences table
$prefs['tc_theme'] - the current theme control setting
$prefs['tc_theme_option'] - the current theme control setting
$prefs['theme_path'] - the path of the currently displayed theme (know about multidomain if set)
{CODE}

!!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. Known limitation: when using Theme Control the custom templates are not used since  lib/init/smarty.php finishes before tiki-tc.php starts.

!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
- 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??)