NAME
Statocles::Help::Theme - A guide to making Statocles themes
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.
Default Themes
There are some default themes included with Statocles, with more on the way. To use a default theme, set your site's theme to ::name
, where name
is the name of the theme. The currently-available default themes are:
::default
-
The default theme uses the Skeleton CSS boilerplate to build a simple, clean starting point for your own theme.
::bootstrap
-
The bootstrap theme uses the Bootstrap library to provide an elegant and flexible theme. Sites like Bootswatch can provide a custom look to your Bootstrap site.
Making Minor Adjustments
Include Stores
Before going to editing the entire theme, you can change the theme includes by adding include_stores.
Some examples of files you can edit are:
- site/head_after.html.ep
-
This include is after all the default
<head>
content. You can add links to new scripts and stylesheets here. - site/header_after.html.ep
-
This include is after the nav bar and page header. You can add banners and such here.
- site/footer.html.ep
-
The entire site footer is up to you to edit.
- site/sidebar_before.html.ep
-
If the page has a sidebar, this include will be placed before it.
Editing a Theme
Start From the Default Theme
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 site/theme
Theme "default" written to "site/theme"
Make sure to update "site.yml"
This command will copy the "default" Statocles theme into the "site/theme" directory. Now we need to update our site.yml
to point to our new theme:
# site.yml
site:
class: Statocles::Site
args:
theme: site/theme
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 Statocles::Page object$site
- The current Statocles::Site object$app
- The current Statocles::App object
These objects hold all the data we need to render the page. Since you are writing Perl, you can use any of the methods from those objects. Some useful methods to note are:
data()
-
All of the objects above, Page, Site, and App, have a
data()
method that allows for an arbitrary hash of key/values. Site and App data are configured in the Site's config file, so these can be used as hooks for template authors to add additional features, such as social media links or metrics tools. Page objects data come from the App, and add information that may not fit anywhere else. $self->sections
-
The
sections
method works on document pages and gives you all of the content split into sections on the section marker (---
).# Get only the first section my ( $first_section ) = $self->sections; # Loop over the sections % for my $section ( $self->sections ) { <%= $section %> % }
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.
- markdown
-
The
markdown
helper allows you to render Markdown to HTML. This is useful when you're using extradata()
(see above) or for things like the blog app tag_text attribute.# Render Markdown as HTML %= markdown $self->data->{markdown}
Layouts
When a page object is built, it is given a template and a layout. The default layout is a special template called default.html.ep
in the layout
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" />