/ 
Statocles-0.098
River stage one • 4 direct dependents • 4 total dependents
/ Statocles::Help::Develop

NAME

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

VERSION

version 0.098

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

AUTHOR

Doug Bell <preaction@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 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.