NAME
Statocles::Help::Theme - A guide to making Statocles themes
VERSION
version 0.034
DESCRIPTION
A Theme is the "View" class of Statocles. Themes build Statocles::Template objects that apps can then attach to a page. Each template has a category and a name. The category usually maps to the application name, or "site" for global site templates. Themes get their templates from a Statocles::Store.
Writing a Template
The default Statocles::Theme uses Mojo::Template, the template class from Mojolicious. In the template, there are a few directives that allow you to evaluate Perl code, which is why the templates are also called ".ep" for Embedded Perl.
# A single leading % means the rest of the line is Perl
% if ( $self->path eq '/index.html' ) {
# A leading %= means replace with the return value
%= $self->path
# Inline code can be wrapped in <% ... %>
# <%= ... %> is replaced with the return value
My name is <%= $self->name %>
# Comments are %# and <%# %>
%# This is in the template, but not the result
<%# A comment %>
Template Variables
When an application assembles a page object, it sets values inside. The page then gives those values to the template. The common values in every template are:
$self - The current L<Statocles::Page|Statocles::Page> object
$site - The current L<Statocles::Site|Statocles::Site> object
$app - The current L<Statocles::App|Statocles::App> object
These objects hold all the data we need to render the page.
Helpers
Helpers are extra functions available to the template.
- include
-
The
include
helper allows you to include another template or file. The include will be searched for in the theme directory.# Include a template, passing the same variables as the current template %= include "site/before_header.html.ep" # Include a file without template processing %= include "site/before_header.html"
If the included path ends with ".ep", it is treated as a template. Otherwise, it's just written directly with no processing.
Layouts
When a page object is built, it is given a template and a layout. The layout is a special template called layout.html.ep
in the site
category that wraps the content from the template, allowing a consistent site style in a single place.
The layout generally adds the site's scaffolding: <html>, <head>, <body>, scripts and stylesheets, header and footer.
The layout gets the exact same template variables that the current page's template gets, so you have the current page ($self
), current site ($site
), and current app ($app
), in case you need it for the layout.
Stylesheets and Scripts
A site's theme is deployed to the "/theme" path. If a theme needs extra files, like stylesheets, scripts, and images, they can be added to the theme's directory and referenced in the HTML from "/theme".
# Reference a stylesheet in theme/css/normalize.css
<link rel="stylesheet" href="/theme/css/normalize.css" />
Default Themes
There is a default theme included with Statocles, with more on the way. The default theme uses the Skeleton CSS boilerplate to build a simple, clean starting point for your own theme.
Bundling Themes
It is unlikely that the default themes will do things exactly as you need. So, Statocles has a command to copy one of the default themes into your site directory so that you can edit it as you need.
# Bundle the default theme
statocles bundle theme default
SEE ALSO
AUTHOR
Doug Bell <preaction@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2015 by Doug Bell.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.