Statocles::Help::Develop - How Statocles works and how to write Statocles modules
version 0.056
This is a high-level overview of how Statocles works: Which modules are responsible for which tasks.
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.
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.
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!
Read documents from the filesystem.
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.
Basic markdown documents are turned into pages with no special arrangement. Also allows for collateral images and other files.
A simple blogging application.
Static files, like images and other site collateral, are copied into the site with no processing whatsoever.
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.
This page renders a single document. This is used for the main page of a blog post, for example.
This page renders a list of other pages (not documents). This is used for index pages and feed pages.
This page adds a layout, but does not require a document. Good if you've already got HTML.
This page is used for non-rendered static files like images. No processing is done.
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.
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.
Deploying the site may involve a simple file copy, but it could also involve a Git repository, an FTP site, or a database.
Copy the site's files to a given local path.
Copy the files to a git repository and push them out. This is how a Github Pages site is deployed.
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.
build
check_pages
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.
Doug Bell <preaction@cpan.org>
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.
To install Statocles, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Statocles
CPAN shell
perl -MCPAN -e shell install Statocles
For more information on module installation, please visit the detailed CPAN module installation guide.