NAME

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

DESCRIPTION

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

OVERVIEW

Statocles has a small workflow:

User creates Documents.
Stores read and write documents.
Applications use Stores to read documents and create Pages.
Sites collect a set of Applications.
Sites have a Themes that builds Templates that are given to Pages.
Finally, the Site writes the Page to a Deploy.

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 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 wherever you want!

Statocles::Store: 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::Basic: Basic markdown documents are turned into pages with no special arrangement. Also allows for collateral images and other files.
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 add template functions and 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. For another example, the Statocles::Plugin::Highlight plugin adds the highlight function to all the templates in the site.

Plugins consume the Statocles::Plugin role and must implement the register method to add themselves where they need to be added.

    # Statocles::Plugin::LinkCheck
    sub register {
        my ( $self, $site ) = @_;
        $site->on( build => sub { $self->check_pages( @_ ) } );
    }

    sub check_pages { ... }

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

Plugins are added to the Site object's plugins attribute:

    # site.yml
    site:
        class: Statocles::Site
        args:
            plugins:
                link_check:
                    $class: 'Statocles::Plugin::LinkCheck'

Event Handlers

Instead of making an entire Statocles::Plugin, we can respond only to certain events using Beam::Wire's event handling API.

In this example, we're going to enable the same LinkCheck plugin as above, but manually using a build event handler:

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

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.