Creating new Themes with Foundation and SCSS

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.