sculpin/sculpin — pull request #90 by simensen (2013-12-15 07:39:45+00:00)
Title: Theme

I had an extremely long commit message written up that went into all of the details but I lost it because who knows why. Some combination of git / vim / mac, I guess.

Anyway, I'll try to get it all in:

In `app/config/sculpin_kernel.yml`, you can set the following:

~~~yml
sculpin_theme:
theme: blue
~~~

That will try to load a theme from `source/themes/blue`. As long as that directory exists you are golden.

If `source/themes/blue/_views` exists, it will be added to the Twig loader.

If `source/themes/blue/theme.yml` exists, it will be read. The only thing of interest in there now is the `parent` key. If `parent` is set to a value, it must be the name of another theme in `source/themes`.

Template resolution for `{% include "foo" %}` is as follows:

* Check a parent theme _views/foo (if a theme is active and it has a parent)
* Check a theme _views/foo (if a theme is active)
* Check source _views/foo

This should give a lot of flexibility in what you can do as far as defining things and overriding them at various spots.

There is also a twig function `{{ theme_path("style.css") }}` that would do something similar:

* Check a parent theme and if it exists, return themes/{parent-name}/style.css
* Check a theme and if it exists, return themes/{theme}/style.css
* Just return /style.css

So given the following:

app/
config/
sculpin_kernel.yml # sculpin_theme: theme: league-plates
source/
_views/
footer.twig # site level override
style.css # @import url("themes/league-plates/style.css")
random-image-asset.png
themes/
league/
style.css
league-logo.png
_views/
header.twig
banner.twig
footer.twig
league-plates/
style.css # @import url("../league/style.css")
plates-logo.png
random-image-asset.png # gonna get overriden...
theme.yml # parent: league
_views/
banner.twig

We can expect imports and template stuff to work like this...

* `{% import "header" %}` => `source/themes/league/header.twig`
* `{% import "banner" %}` => `source/themes/league-plates/banner.twig`
* `{% import "footer" %}` => `source/_views/footer.twig`

And we can expect to be able to access non-template assets like this:

* `{{ theme_path("league-logo.png") }}` => `/themes/league/league-logo.png`
* `{{ theme_path("plates-logo.png") }}` => `/themes/league/plates-logo.png`
* `{{ theme_path("random-image-asset.png") }}` => `/random-image-asset.png`
* `{{ theme_path("style.css") }}` => `/style.css`

So all around, it looks for the most specific thing first.

This is a somewhat contrived example as it might not make sense to build a plates theme separate from the plates site. However, it made for an easy to write demo of what works currently.