Merge pull request #1127 from ElixirTeSS/theme-config

Configure themes in tess.yml

Author: fbacall

app/models/space.rb

@@ -14,8 +14,7 @@ class Space < ApplicationRecord
   has_many :administrator_roles, -> { where(key: :admin) }, class_name: 'SpaceRole'
   has_many :administrators, through: :administrator_roles, source: :user, class_name: 'User'
 
-  THEMES = ['default', 'green', 'blue', 'space'].freeze
-  validates :theme, inclusion: { in: THEMES, allow_blank: true }
+  validates :theme, inclusion: { in: TeSS::Config.themes.keys, allow_blank: true }
 
   has_image(placeholder: TeSS::Config.placeholder['content_provider'])
 

app/views/spaces/_form.html.erb

@@ -7,7 +7,7 @@
 
   <%= f.input :description, as: :markdown_area, input_html: { rows: '10' } %>
 
-  <%= f.input :theme, collection: Space::THEMES, selected: @space.theme || 'default' %>
+  <%= f.input :theme, collection: TeSS::Config.themes.keys, selected: @space.theme || 'default' %>
 
   <div class="form-group">
     <%= render partial: 'common/image_form', locals: { form: f } %>

config/application.rb

@@ -84,6 +84,21 @@ class Application < Rails::Application
     tess_config['placeholder']['content_provider'] = tess_config['placeholder']['provider']
   end
 
+  # Apply legacy `icon_primary_color` and `icon_secondary_color` to default theme
+  if tess_config.dig('site', 'icon_primary_color')
+    warn "DEPRECATION WARNING: 'icon_primary_color' should now be 'primary_color' under 'themes', 'default' in: config/tess.yml"
+    tess_config['themes'] ||= {}
+    tess_config['themes']['default'] ||= {}
+    tess_config['themes']['default']['primary'] ||= tess_config.dig('site', 'icon_primary_color')
+  end
+
+  if tess_config.dig('site', 'icon_secondary_color')
+    warn "DEPRECATION WARNING: 'icon_secondary_color' should now be 'secondary_color' under 'themes', 'default' in: config/tess.yml"
+    tess_config['themes'] ||= {}
+    tess_config['themes']['default'] ||= {}
+    tess_config['themes']['default']['secondary'] ||= tess_config.dig('site', 'icon_secondary_color')
+  end
+
   def self.merge_config(default_config, config, current_path = '')
     default_config.each do |key, value|
       unless config.key?(key)

config/tess.example.yml

@@ -95,9 +95,6 @@ default: &default
     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
     repository: 'https://github.com/ElixirTeSS/TeSS'
     supported_by: 'elixir_supported_by'
     widget_example:
@@ -245,6 +242,22 @@ default: &default
 #      featured_providers:
 #        node:
 #          name: United Kingdom
+  # Themes enabled in TeSS:
+  # "primary" and "secondary" refer to the colours of the SVG icons used throughout TeSS,
+  #   requires `rake assets:precompile` if changed
+  themes:
+    default:
+      primary: '#047eaa' # Blue by default
+      secondary: '#f47d21' # Orange by default
+    green:
+      primary: '529d00'
+      secondary: '#829d30'
+    blue:
+      primary: '#024552'
+      secondary: '#00839d'
+    space:
+      primary: '#260252'
+      secondary: '#5c29b1'
 development:
   <<: *default
 

docs/customization.md

@@ -15,30 +15,60 @@ Secure settings such as database credentials, API keys, email settings etc. can
 
 ## Styles
 
-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 (look at the other themes in that directory, and the `mixins/_modern_base.scss` mixin for reference).
+TeSS' UI is built on [Bootstrap 3](https://getbootstrap.com/docs/3.4/). 
+To customize the appearance of TeSS, you can either select one of the pre-made themes, or create your own. 
 
-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):
+### Switching theme
+
+To change the site default theme, edit your `config/tess.yml` config file and change (or add if not present) 
+the `default_theme` variable under the `site` section to reference one of the configured themes 
+(listed under the `themes` section in `config/tess.yml` or `config/tess.example.yml`):
 
 ```yml
 default: &default
   # ...
   site:
     # ...
-    default_theme: my_theme
+    default_theme: green
+```
+
+### Creating your own theme
+
+1. Go into the themes folder (`app/assets/stylesheets/themes`) and make a copy of the default theme file (`default.scss`).
+
+2. Add your theme to the list of themes in `config/tess.yml` (see `config/tess.example.yml` for reference). 
+   The `primary` and `secondary` properties are colours that will be used in the various SVG icons in TeSS.  
+```yml
+default: &default
+  # ...  
+  themes:
+    default:
+      primary: '#047eaa' # Blue by default
+      secondary: '#f47d21' # Orange by default
+    # ...
+    my_theme:
+      primary: '#ff0000'
+      secondary: '#ffff00' 
 ```
 
-Additionally, you will need to create a symlink for the theme's images:
+3. Enable your theme as the default them according to the section above.
+
+4. Create a symlink for the theme's SVG images:
 
+```shell
     ln -s app/assets/images/modern app/assets/images/themes/my_theme
+```
+
+*Alternatively, if you would like to make changes to the SVG images (beyond the colour changes that are automatically applied),
+you may want to copy the images instead of making a symlink.*
+
+In your theme's .scss file 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 (look at the other themes in that directory, and the `mixins/_modern_base.scss` mixin for reference).
 
 Be sure to recompile assets (`bundle exec rake assets:recompile`), or rebuild your docker image, 
-and restart the application to apply the new styles.
+and restart the application to apply the new styles (except in development mode, where CSS changes should be applied automatically).
 
-You can visit <http://localhost:3000/theme_showcase> on your local instance to see various Bootstrap elements with the
+You can visit <http://localhost:3000/theme_showcase> on your local instance to see various UI elements with the
 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>

lib/svg_recolourer.rb

@@ -6,30 +6,6 @@ class SvgRecolourer
     '#f47d21' => :secondary
   }
 
-  # Configured themes. TODO: Read this from some config
-  THEMES = {
-    'default' => {
-      primary: TeSS::Config.site['icon_primary_color'],
-      secondary: TeSS::Config.site['icon_secondary_color']
-    },
-    'green' => {
-      primary: '#529d00',
-      secondary: '#829d30'
-    },
-    'blue' => {
-      primary: '#024552',
-      secondary: '#00839d'
-    },
-    'space' => {
-      primary: '#260252',
-      secondary: '#5c29b1'
-    },
-    'dark' => {
-      primary: '#260252',
-      secondary: '#5c29b1'
-    }
-  }
-
   REGEXP = Regexp.new('(' + MAPPING.keys.map { |k| Regexp.quote(k) }.join('|') + ')',  Regexp::IGNORECASE)
 
   def initialize(filename, &block)
@@ -44,7 +20,7 @@ def render(context, empty_hash_wtf)
   def self.run(filename, source, context)
     match_data = filename.match(/images\/themes\/([^\/]+)\//)
     return source unless match_data
-    theme = THEMES[match_data[1]]
+    theme = TeSS::Config.themes[match_data[1]]
     raise "Missing theme #{match_data[1]}" unless theme
 
     source.gsub(REGEXP) do |match|