# 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.040

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

If you only want to edit some minor things, such as the stylesheets, but want to get
any new fixes from the default theme you bundled, you can safely edit any of the
default includes, which start out as completely empty files.

If you have edited the default includes, the C<bundle theme> command will not update
them.

Some examples of files you can safely 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 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
