Version 20 (modified by 6 years ago) ( diff ) | ,
---|
Creating new Themes with Foundation and SCSS
Table of Contents
Creating the Theme
Directory Layout
themes/THEME Base folder of the theme | +---theme.css the theme's SCSS-built CSS style sheet +---style.css the theme's additional CSS (optional) +---eden.min.css css.cfg-built, minified CSS (includes the two above) +---*.css any additional injectable CSS (s3.stylesheets) | +---foundation The theme's Foundation base CSS style sheets (SCSS-built) | | | +---foundation.css the theme's Foundation base style sheet for Left-to-Right writing direction | +---foundation.rtl.css the theme's Foundation base style sheet for Right-to-Left writing direction | +---foundation.min.css minified versions of the above | +---foundation.rtl.min.css " | +---scss The SCSS environment of the theme | | | +---_settings.scss the theme's Foundation SCSS settings (=> falls back to default/scss/_settings.scss) | +---foundation.scss the theme's Foundation SCSS imports | +---foundation.rtl.scss the theme's Foundation SCSS RTL overrides | +---theme.scss the theme's SCSS imports | +---config.rb the build configuration for Compass | | | +---theme/ The theme's SCSS sources | | | +---_base.scss the theme's SCSS base (required) | +---_config.scss the theme's Sahana-specific SCSS settings | +---_*.scss the individual SCSS sources (=> fall back to the corresponding default/scss/theme/_*.scss) | +---img Image folder of the theme +---js Script folder of the theme (injected scripts) +---favicon.ico The bookmark icon of the theme
Copying from Skeleton
- tbd
Building the Theme
Debug Versions
The theme can be built using compass
:
cd static/themes/THEME/scss compass compile
This will rebuild the following CSS style sheets as/when required:
- foundation/foundation.css
- foundation/foundation.rtl.css
- theme.css
For longer development sessions, it can be convenient to let compass
automatically rebuild the theme whenever a source changes:
cd static/themes/THEME/scss compass watch
This runs continuously, watching the file system, and will automatically run compass compile
when a source changes.
Production
To rebuild the minified versions of the foundation stylesheets:
- foundation/foundation.min.css
- foundation/foundation.rtl.min.css
...we need to tell compass
to build for the production environment:
cd static/themes/THEME/scss compass compile -e production
Note that this only needs to be done after changing THEME/scss/_settings.scss
, not routinely.
The eden.min.css
can be rebuild as usual with the build.sahana.py script.
Using the Theme in a Template
Adding Foundation to layout.html
Base Styles
Foundation-based themes must include the Foundation base stylesheets, ahead of any Sahana style sheets:
- static/themes/foundation/normalize.css
- static/themes/THEME/foundation/foundation.css
- static/themes/THEME/foundation/foundation.rtl.css
Note that only one of foundation.css
or foundation.rtl.css
is loaded, depending on the writing direction for the current UI language (Left-To-Right or Right-To-Left).
The sequence to include Foundation base styles is encoded in a view template views/foundation.css.html
, so it can easily be added to layout.html
:
... {{for sheet in s3.external_stylesheets:}} <link href="{{=sheet}}" rel="stylesheet" type="text/css" media="screen" charset="utf-8" /> {{pass}} {{include "foundation.css.html"}} <--- Foundation base styles are loaded here {{for sheet in s3.stylesheets:}} <link href="/{{=appname}}/static/styles/{{=sheet}}" rel="stylesheet" type="text/css" media="screen" charset="utf-8" /> {{pass}} {{if s3.debug:}}{{=s3base.s3_include_debug_css()}}{{else:}} {{# Built by /static/scripts/tools/build.sahana.py }} <link href="/{{=appname}}/static/themes/{{=theme}}/eden.min.css" rel="stylesheet" type="text/css" /> {{pass}} ...
Scripts
Additionally, Foundation requires loading and initialization of some scripts at the end of the <body>
. The corresponding sequence is also encoded in a view template views/foundation.js.html
, so it can easily be added to layout.html
:
... {{include "foundation.js.html"}} <--- this loads and initializes Foundation scripts </body> </html>
Adding Theme Styles to css.cfg
The SCSS-built theme.css
style sheet is included at the end of css.cfg
:
... ../themes/THEME/theme.css #../themes/THEME/style.css # Final line required for parsing
It can be followed by an optional THEME/style.css
to add CSS for template-specific elements as well as final overrides. The style.css
style sheet is not built from SCSS, so it can be edited directly.