History: Making or Updating a Theme for Tiki 27
Preview of version: 9
New location for custom themes
One aspect of this is to put all of the custom, site-specific files in one directory to facilitate backing up the site, moving the site, and so on. In Tiki 27, the included themes are still in the /themes directory, but it's recommended to put custom theme files in this location if the theme is being developed within the Tiki instance (the files are going to be SCSS-compiled): <Tiki root>/_custom/shared/themes/ . If the custom theme is already compiled and ready to use and won't be further SCSS-compiled in this Tiki installation, then see "New location for custom theme CSS files" below.
New location for custom theme top file ("mytheme.scss")
The "top" files of the theme, mytheme.scss, for example, and newsletter.scss, are now in the mytheme/css directory, moved from the mytheme/scss directory. Otherwise, each custom theme still has the same sub-directories as the package themes, the same as before.
New custom theme files hierarchy
In Tiki 26 and earlier
tiki root
|_ themes
|_ mynewtheme
|_ css
|_ mynewtheme.css
|_ newsletter.css (normally generated during SCSS compiling)
|_ fonts
|_ icons
|_ images
|_ mynewtheme_background_image.png (if any)
|_ mynewtheme.png (screenshot thumbnail that displays on Look & Feel admin page)
|_ options
|_ mynewthemeoption
|_ css
|_ mynewthemeoption.css
|_ scss (plus other standard directories if needed)
|_ scss
|_ _css-variables.scss (SCSS files beginning with "_" won't be compiled into their own CSS files)
|_ mynewtheme.scss
|_ _tiki-variables.scss
|_ _variables.scss
|_ _variables-dark.scss
|_ newsletter.scss
|_ templates
|_ sometemplatefile.tpl (if needed)
In Tiki 27 and later
tiki root
|_ _custom
|_ shared
|_themes
|_ mynewtheme
|_ css
|_ mynewtheme.scss
|_ newsletter.scss
|_ fonts
|_ icons
|_ images
|_ mynewtheme_background_image.png (if any)
|_ mynewtheme.png (screenshot thumbnail that displays on Look & Feel admin page)
|_ options
|_ mynewthemeoption
|_ css
|_ mynewthemeoption.scss
|_ ( . . . plus other standard theme sub-directories if needed)
|_ scss
|_ _css-variables.scss (SCSS files beginning with "_" won't be compiled into their own CSS files)
|_ _tiki-pagetop_colors.scss
|_ _tiki-selectors.scss
|_ _variables.scss
|_ _variables-dark.scss
|_ templates
|_ sometemplatefile.tpl (if needed)
New location for custom theme CSS files
While the component files of the theme are in _custom/shared/themes/ , when these are compiled, the output CSS files of the theme are generated in
<tiki root>/public/generated/_custom/shared/themes/mytheme/ .
This location works the same as <tiki root>/themes so the custom theme will show up in the Look & Feel admin theme selector just like the included themes.
New file paths in top file
All the file paths in the theme's top file ("mytheme.scss") need to be updated as shown in the Tiki 27 example, below right:
In Tiki 26 and earlier
for a theme in the /themes directory
@import "../../base_files/scss/_tiki-bootstrap_functions"; @import "variables"; // Needs to come first, to override Bootstrap defaults. @import "variables-dark"; @import "../../base_files/scss/_tiki-variables.scss"; // Values/definitions for Tiki variables (outside of Bootstrap variables) such as _tiki-selectors.scss. @import "../../default/scss/variables"; // Bootstrap default variables, with a few Tiki overrides @import "../../default/scss/variables-dark"; // Bootstrap dark mode default variables @import "../../base_files/scss/_tiki-bootstrap_layout_and_components"; @import "css-variables"; // Needs to be loaded after default variables to override them @import "../../base_files/scss/_tiki-selectors.scss"; @import "../../base_files/scss/_tiki-pagetop_colors.scss"; // Import if needed to specify top and topbar zone colors in more detail @import "_tiki-selectors.scss"; @import "../../base_files/scss/_external-scripts.scss"; @import "../../base_files/scss/_select2-tiki_colors.scss";
In Tiki 27 and later (updated)
for a theme in the /_custom/shared/themes directory
@import "themes/base_files/scss/_tiki-bootstrap_functions"; // 1. Functions are included first (so colors, etc. can be manipulated). @import "themes/base_files/scss/_tiki-variables.scss"; // 2. Default value declarations for Tiki variables and the default vendor Bootstrap variables. @import "../scss/variables"; // 3. The theme's variable declarations are used when they are imported after the Bootstrap defaults (order changed for Tiki 27). @import "themes/default/scss/variables-dark"; //4. Values of dark variables if color modes are enabled (Order of importing this and the default variables-dark doesn't seem to make a difference). @import "../scss/variables-dark"; // 5. Adds default dark variables for any not declared by the theme dark variables file. @import "themes/base_files/scss/_tiki-bootstrap_layout_and_components"; // 6. Remainder of required Bootstrap parts. @import "themes/base_files/scss/_tiki-selectors.scss"; // 7. Tiki CSS selectors used globally. @import "themes/base_files/scss/_tiki-pagetop_colors.scss"; // 8. Optionally imported to group (separately) the top and topbar zone components for styling. @import "../scss/_tiki-selectors.scss"; // 9. Tiki CSS selectors, including those of external scripts, to be styled by the theme's variables. @import "../scss/css-variables"; // 10. Imported after default CSS variables to override them.
As the lists above show, there are fewer files directly imported by the theme in Tiki 27 because one file import was redundant and a few other imports are now combined "upstream" in themes/base_files/scss to reduce duplication across themes and simplify each theme's top file.
New theme compiling method
The theme-building workflow changed between Tiki 26 and 27. Formerly the PHP script to compile themes was part of the Tiki package, but as of Tiki 27 node.js and npm are used so these need to be installed separately from Tiki. The required npm version is between 9.0.0 and 11, and the required node.js version is between 18.0.0 and 22.
Then running npm run watch in the terminal will watch for changes in SCSS files and compile them to CSS, and will report any errors.