add theme help file

This document describes how to build a theme Fixes #108
preaction · Jan 25, 2015 · 63b2772 · 63b2772
1 parent f652aca
commit 63b2772
Showing 1 changed file with 105 additions and 0 deletions.
diff --git a/lib/Statocles/Help/Theme.pod b/lib/Statocles/Help/Theme.pod
@@ -0,0 +1,105 @@
+# PODNAME: Statocles::Help::Theme
+# ABSTRACT: A guide to making Statocles themes
+
+=head1 DESCRIPTION
+
+A Theme is the "View" class of Statocles. Themes build
+L<Statocles::Template|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 L<Statocles::Store|Statocles::Store>.
+
+=head1 Writing a Template
+
+The default L<Statocles::Theme|Statocles::Theme> uses
+L<Mojo::Template|Mojo::Template>, the template class from
+L<Mojolicious|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 %>
+
+=head2 Template Variables
+
+When an application assembles a L<page object|Statocles::Page>, 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.
+
+=head2 Helpers
+
+Helpers are extra functions available to the template.
+
+=over 4
+
+=item include
+
+The C<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.
+
+=back
+
+=head1 Layouts
+
+When a page object is built, it is given a template and a layout. The layout is
+a special template called C<layout.html.ep> in the C<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 (C<$self>), current site
+(C<$site>), and current app (C<$app>), in case you need it for the layout.
+
+=head1 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" />
+
+=head1 Default Themes
+
+There is a default theme included with Statocles, with more on the way. The
+default theme uses L<the Skeleton CSS boilerplate|http://getskeleton.com> to
+build a simple, clean starting point for your own theme.
+
+=head1 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
+