Updated documentation on customization

Author: fbacall

app/helpers/application_helper.rb

@@ -694,6 +694,6 @@ def unverified_notice(resource)
   end
 
   def theme_path
-    "themes/#{params[:theme_preview] || current_space&.theme || 'default'}"
+    "themes/#{params[:theme_preview] || current_space&.theme || TeSS::Config.site['default_theme'] || 'default'}"
   end
 end

config/tess.example.yml

@@ -94,6 +94,7 @@ default: &default
     logo_alt: 'Training eSupport System'
     logo_open_graph: ''
     logo_email: ''
+    default_theme: default
     # Colours of the SVG icons used throughout TeSS, requires `rake assets:precompile` if changed
     icon_primary_color: '#047EAA' # Blue by default
     icon_secondary_color: '#F47D21' # Orange by default

docs/customization.md

@@ -18,23 +18,30 @@ Secure settings such as database credentials, API keys, email settings etc. can
 TeSS' UI is built on [Bootstrap 3](https://getbootstrap.com/docs/3.4/). To customize the appearance of TeSS, go into
 the themes folder (`app/assets/stylesheets/themes`) and make a copy of the default theme file (`default.scss`).
 In your copy, you can tweak any of the existing variables, add overrides for any Bootstrap variables
-([reference](https://github.com/twbs/bootstrap-sass/blob/master/assets/stylesheets/bootstrap/_variables.scss)) and add
-new CSS/Sass styles.
+([reference](https://github.com/twbs/bootstrap-sass/blob/master/assets/stylesheets/bootstrap/_variables.scss)) and add new CSS/Sass styles (look at the other themes in that directory, and the `mixins/_modern_base.scss` mixin for reference).
 
-To enable your theme, edit `app/assets/stylesheets/mixins/variables.scss` and change the line:
-```scss
-@import "../themes/default";
-```
-to point to your new theme file...
-```scss
-@import "../themes/new_theme";
+To use your theme as the site default, edit your `config/tess.yml` config file and change 
+(or add if not present) the `default_theme` variable under the `site` section to reference your new theme file (sans the `.scss` extension):
+
+```yml
+default: &default
+  # ...
+  site:
+    # ...
+    default_theme: my_theme
 ```
 
+Additionally, you will need to create a symlink for the theme's images:
+
+    ln -s app/assets/images/modern app/assets/images/themes/my_theme
+
 Be sure to recompile assets (`bundle exec rake assets:recompile`), or rebuild your docker image, 
 and restart the application to apply the new styles.
 
 You can visit <http://localhost:3000/theme_showcase> on your local instance to see various Bootstrap elements with the
-current theme applied.
+current theme applied. 
+
+You can also add a query parameter `theme_preview` to the URL of any page to preview different themes, e.g. <http://localhost:3000/theme_showcase?theme_preview=blue>
 
 ## Text changes