= Creating new Themes with Foundation and SCSS =
[[TOC]]
== 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 ===
== 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:}}
{{pass}}
{{include "foundation.css.html"}} <--- Foundation base styles are loaded here
{{for sheet in s3.stylesheets:}}
{{pass}}
{{if s3.debug:}}{{=s3base.s3_include_debug_css()}}{{else:}}
{{# Built by /static/scripts/tools/build.sahana.py }}
{{pass}}
...
}}}
==== Scripts ====
Additionally, Foundation requires loading and initialization of some scripts at the end of the {{{}}}. 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