History: Make an SCSS-Compiled Tiki Theme

• «
• »

            {REMARKSBOX(type="tip" title="Update coming soon")}Tiki is now using Bootstrap 5 (as of Tiki 25) and so is making increased use of CSS variables and, soon (after Bootstrap 5.3 is available), color modes ("prefers-color-scheme"). These are big changes and hopefully this page will be updated soon to cover them. See also
* ((CSS Variables in Tiki))
* ((Color Modes in Tiki)) {REMARKSBOX}

!! Introduction
To have the most complete Tiki theme possible - a theme that can touch every detail of the site's appearance - the best way is to not just create a bootstrap.css-equivalent theme style sheet, but to also include Tiki-specific CSS rules that are outside the scope of Bootstrap. And the best way to do this is to use [https://sass-lang.com| Sass (SCSS) CSS pre-processing]. This is how the themes included in the Tiki package are made. The standard Bootstrap variables get new values, and CSS rules can be added for page elements that aren't covered by standard Bootstrap, with the new theme variables being used in both the Bootstrap and the Tiki CSS that's additional to Bootstrap.

Theme files can should be compiled within Tiki itself via the command line. See [https://dev.tiki.org/Using+Less+CSS+with+Tiki] (soon to be updated) and [https://dev.tiki.org/Improving-the-Tiki-Bootstrap-SCSS-File-Arrangement] for details on how to compile manually or automatically using PhpStorm. 
  
!! Prepare a set of files
Make a set of files for the theme, arranged like this:
* -+newtheme/+- - The directory for the new theme, in the ''themes'' directory.
** -+css/+-
*** -+newtheme.css+- -This location is required, to be recognized by the Look & Feel theme selector.
** -+fonts/+- - Local storage of fonts, if preferred to web fetching.
** -+icons/+- Icon set(s) used for the theme. See [https://dev.tiki.org/Icons#Theme_specific_icon_set].
** -+images/+- - Any background or border images, etc. should be put here. 
** -+scss/+-
*** -+variables.scss+- - A copy of the current Bootstrap ''scss/variables.scss'' file
*** -+tiki-selectors.scss+- - For CSS outside the scope of Bootstrap, etc.
*** -+newtheme.scss+- - The "root" scss file for the theme, imports the other files to produce the style sheet.

If you plan to make a number of themes, it's good to keep a base set of files that can be copied and renamed for each new theme. For more information on these files, see ((Tiki theme files)).

The "root" scss file, the one with the same name as the theme, imports the component files that are compiled to produce the theme's CSS style sheet. This file can also be the place for web font import statements, if web fonts are used. Alternatively to fetching fonts from the web, font files can be put in the theme's ''fonts'' directory and imported from there.

{CODE(caption="Typical 'newtheme.scss' file")}
(update coming soon)
{CODE}

The theme files should be part of or copied or uploaded to a Tiki site for development at the beginning of the theme-making process. It's good to see the effects of edits immediately, as the theme gets built in steps. 

!! Get style details
Here is one approach to developing the theme. As with other design-to-website integration projects, check the design mock-ups, wire frames, specifications and so on to understand the basic elements. For example, find or decide on the information for page and content-area background colors; text color, size and font family; link colors; white space; and so on.

If background images are used, they go in the theme's ''images'' directory. 

!! Edit variables.scss
Input the style information in the -+variables.scss+- file, replacing the default Bootstrap values with those for the theme. This is done the same way any Bootstrap style sheet is made. Save the edited file (which should trigger a scss compile), refresh the site with the updated CSS file, and check the site appearance. Some of the basic aspects of the theme should be evident already.

{CODE(caption="variables.scss")}
(updated info coming soon)

{CODE}

(More updated information coming soon)~tc~

!! Take advantage of Look & Feel and Modules configuration 
A lot of flexibility in Tiki's layout and content display is provided by the Look and Feel admin (''tiki-admin.php?page=look'') and Modules admin (''tiki-admin_modules.php'') features. For example, whether to have a page-top fixed navbar or a conventional navbar style and location, whether to have a main column only or that plus one or two side columns, etc. can be configured to suit the site purpose, content and design. The desired design for the theme's might flexibly accommodate any Look and Feel or Module configuration, or might require a specific configuration.

!! Extend the design reach by editing tiki-selectors.scss
After the site is reloaded following the revision of the -+variables.scss+- file, usually more styling still needs to be done. Standard Bootstrap assumes the page background and content area are the same, text color is the same everywhere, and so on. For not-so-simple layouts, more CSS rules are needed. Also, because Tiki's default layout is more complicated than a standard Bootstrap layout, it has more CSS rules. See ((Tiki Less selectors)) [[This is a page that describes what goes into tiki-base.css]. To add these style details, rules need to be added in the -+tiki-selector.scss+- file.  (Keep in mind that even though this is a SCSS file, as with all SCSS files, ordinary CSS syntax can be used.) 

Typically, the -+tiki-selectors.scss file+- has rules to implement things like
* background gradients or images
* more than one border color on buttons or cards
* background shadows or glows
* content-area background and foreground (text) colors different from those of the whole page (viewport)
* additional element properties not specified by Bootstrap variables
* additional elements specific to the site, etc.
Take a look at some Tiki themes' -+tiki-selectors.scss+- files to see what they contain. 

{CODE(caption="Typical tiki-selectors.scss file")}
// This file is for additional SCSS rules beyond what are in variables.scss.
// Image path example:
$imagePath: ~"../images/";
// body {
//	background-image: background: url('#{$imagePath}header_background_ltr.jpg');
// }
//



body {
	background: url('#{imagePath}flakesptn2.jpg');
	background-attachment: fixed;
}

header.container {
	margin-top: 20px;
}

.topbar {
	margin-bottom: 20px;
}

...
{CODE}

To get a better idea of the Tiki page elements available for styling, please see ((Layout Templates in Tiki 13 to 18)), which describes Tiki's total-page display options.  ((Organization and details of Less files)) shows information about all the Less files used to make Tiki's stylesheets (not just theme-related). ~/tc~