NAME

Statocles::Help::Develop - How Statocles works and how to write Statocles modules

VERSION

version 0.051

DESCRIPTION

This is a high-level overview of how Statocles works: Which modules are responsible for which tasks.

OVERVIEW

Statocles has a small workflow:

DOCUMENTS

A document is the main content of the site. The user does all the work with documents: adding, editing, and removing documents.

The default store reads documents in a Markdown format with a YAML header, easily editable with any text editor. A sample document looks like:

    ---
    title: This is a title
    author: preaction
    ---
    # This is the markdown content

    This is a paragraph

The document format is described in the Statocles::Store::File documentation under Frontmatter Document Format.

STORES

A Statocles::Store reads and writes documents and pages. The default store reads documents in YAML and writes pages to a file, but stores could read documents as JSON, or from a Mongo database, and write pages to a database, or whereever you want!

Statocles::Store::File

Read documents from the filesystem.

APPLICATIONS

An application is the module that will take the documents the user provides and turn them into the pages that can be written out to the filesystem.

Statocles::App::Plain

Plain markdown documents are turned into pages with no special arrangement.

Statocles::App::Blog

A simple blogging application.

Statocles::App::Static

Static files, like images and other site collateral, are copied into the site with no processing whatsoever.

PAGES

A Statocles::Page is collected information ready to be rendered into HTML (or whatever). Statocles Applications generate pages from the documents that the user provides. One document may generate multiple pages, and pages may have multiple formats like HTML or RSS.

Statocles::Page::Document

This page renders a single document. This is used for the main page of a blog post, for example.

Statocles::Page::List

This page renders a list of other pages (not documents). This is used for index pages and feed pages.

Statocles::Page::Plain

This page adds a layout, but does not require a document. Good if you've already got HTML.

Statocles::Page::File

This page is used for non-rendered static files like images. No processing is done.

SITES

A Statocles::Site manages a bunch of applications, writing and deploying the resulting pages.

The site controls the entire workflow, reading pages from the applications and writing them to the appropriate deploy.

THEMES

A Statocles::Theme creates Statocles::Template objects using Mojo::Template.

If you want to use Template Toolkit or Text::Xslate, you would create a new Theme class that provides a different Template object.

DEPLOYS

Deploying the site may involve a simple file copy, but it could also involve a Git repository, an FTP site, or a database.

Statocles::Deploy::File

Copy the site's files to a given local path.

Statocles::Deploy::Git

Copy the files to a git repository and push them out. This is how a Github Pages site is deployed.

PLUGINS

Plugins are used to respond to events in the Statocles workflow. For example, when a site is built, an event is fired containing all the built pages. Then, the Statocles::Plugin::LinkCheck plugin can search all the pages for broken links.

Any class can be a plugin, it just needs a method. The event listener is wired up using the configuration file:

    # site.yml
    site:
        class: Statocles::Site
        on:
            - build:
                $class: Statocles::Plugin::LinkCheck
                $sub: check_pages

When the build event fires, the LinkCheck method check_pages will be called, with the event object given as the argument.

ROLES

If you want to add some custom behavior to any of the site's objects, the configuration file (made with Beam::Wire) allows you to compose one or more roles into the objects in your site.

    # lib/My/Readme.pm
    package My::Readme;

    use Moo::Role;
    around build => sub {
        my ( $orig, $self, @args ) = @_;

        # Call the original build method
        my @pages = $orig->$self( @args );

        # Add a readme file
        push @pages, Statocles::Page::Plain->new(
            path => '/README',
            content => 'Please read me!',
        );

        return @pages;
    };

    # site.yml
    site:
        class: Statocles::Site
        with: 'My::Readme'

Using roles can help change behaviors that are otherwise not available to plugins.

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.