History: Making or Updating a Theme for Tiki 27

• «
• »

            {REMARKSBOX(type="note" title="Current information" close="n")} The Tiki 27 file organization has stabilized after considerable development, but for any clarification and the latest information, please visit Tiki's [https://app.gitter.im/#/room/#tiki-org_community:gitter.im|Matrix chatroom]. {REMARKSBOX}

{DIV(class="lead")}Tiki continues to evolve along with modern web technology methods. For Tiki 27 the file system has been reorganized to be more logical and efficient. More information is here: [https://dev.tiki.org/The-Tiki-27-plus-Build-System], with more background information here: [https://gitlab.com/tikiwiki/tiki/-/blob/master/_PATH_DOCUMENTATION.md]. Also, to compile a theme now (from SCSS to CSS), the script has changed from PHPSCSS to Dart, so the process is faster and it is also the same script that Bootstrap uses.{DIV}

!! 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 themes in this location:

-+ <Tiki root>/_custom/shared/themes/ +-

!! 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
{DIV(class="row")}{DIV(class="col-sm-5")}{DIV(class="card")}{DIV(class="card-body")}
!!! In Tiki 26 and earlier
~pp~
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)

~/pp~

{DIV}{DIV}{DIV} 
{DIV(class="col-sm-1 d-flex align-items-center justify-content-center")} {icon name="arrow-right" size="3"} {DIV}
{DIV(class="col-sm-5")}{DIV(class="card")}{DIV(class="card-body")}
!!! In Tiki 27 and later
~pp~
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)

~/pp~

{DIV}{DIV}{DIV}{DIV} 

!! 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 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 package 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:
{DIV(class="row")}{DIV(class="col-sm-5")}{DIV(class="card")}{DIV(class="card-body")}
!!! In Tiki 26 and earlier
''for a theme in the /themes directory'' 
~pp~
@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";
~/pp~
{DIV}{DIV}{DIV} 
{DIV(class="col-sm-1 d-flex align-items-center justify-content-center px-0")} {icon name="arrow-right" size="3"} {DIV}
{DIV(class="col-sm-5")}{DIV(class="card")}{DIV(class="card-body")}
!!! In Tiki 27 and later (updated)
''for a theme in the /_custom/shared/themes directory''
~pp~
@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.
~/pp~
{DIV}{DIV}{DIV}{DIV} 

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. 

{REMARKSBOX(type="note" title="Compiling on Windows" close="n")}As of this writing (May 20, 2024), there's a glitch when compiling custom themes in Windows. Non-SCSS files and directories are output on a different path than SCSS files, so the theme's images, fonts, templates, etc. directories need to be copied manually to the correct location in public/_custom/shared/themes to be available for the theme. {REMARKSBOX}