# PODNAME: Statocles::Help::Theme
# ABSTRACT: A guide to making Statocles themes

__END__

=pod

=head1 NAME

Statocles::Help::Theme - A guide to making Statocles themes

=head1 VERSION

version 0.045

=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 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 Making Minor Adjustments

=head2 Include Stores

Before going to editing the entire theme, you can change the theme includes
by adding L<include_stores|Statocles::Theme/include_stores>.

Some examples of files you can edit are:

=over 4

=item site/head_after.html.ep

This include is after all the default C<E<lt>headE<gt>> content. You can add
links to new scripts and stylesheets here.

=item site/header_after.html.ep

This include is after the nav bar and page header. You can add banners and such
here.

=item site/footer.html.ep

The entire site footer is up to you to edit.

=item site/sidebar_before.html.ep

If the page has a sidebar, this include will be placed before it.

=back

=head1 Editing a Theme

=head2 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 C<site.yml> to point to our new theme:

    # site.yml
    site:
        class: Statocles::Site
        args:
            theme: site/theme

=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 SEE ALSO

=over 4

=item L<Statocles::Theme>

=item L<Statocles::Template>

=back

=head1 AUTHOR

Doug Bell <preaction@cpan.org>

=head1 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.

=cut
