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

NAME

Statocles::Site - An entire, configured website

VERSION

version 0.098

SYNOPSIS

my $site = Statocles::Site->new(
    title => 'My Site',
    nav => [
        { title => 'Home', href => '/' },
        { title => 'Blog', href => '/blog' },
    ],
    apps => {
        blog => Statocles::App::Blog->new( ... ),
    },
);

$site->deploy;

DESCRIPTION

A Statocles::Site is a collection of applications.

ATTRIBUTES

title

The site title, used in templates.

author

author: Doug Bell <doug@example.com>
author:
    name: Doug Bell
    email: doug@example.com

The primary author of the site, which will be used as the default author for all content. This can be a string with the author's name, and an optional e-mail address wrapped in <>, or a hashref of Statocles::Person attributes.

Individual documents can have their own authors. See "author" in Statocles::Document.

base_url

The base URL of the site, including protocol and domain. Used mostly for feeds.

This can be overridden by base_url in Deploy.

theme

The theme for this site. All apps share the same theme.

apps

The applications in this site. Each application has a name that can be used later.

plugins

The plugins in this site. Each plugin has a name that can be used later.

index

The page path to use for the site index. Make sure to include the leading slash (but /index.html is optional). Defaults to /, so any app with url_root of / will be the index.

Named navigation lists. A hash of arrays of hashes with the following keys:

title - The title of the link
href - The href of the link

The most likely name for your navigation will be main. Navigation names are defined by your theme. For example:

{
    main => [
        {
            title => 'Blog',
            href => '/blog',
        },
        {
            title => 'Contact',
            href => '/contact.html',
        },
    ],
}
# site.yml
links:
    stylesheet:
        - href: /theme/css/site.css
    script:
        - href: /theme/js/site.js

Related links for this site. Links are used to build relationships to other web addresses. Link categories are named based on their relationship. Some possible categories are:

stylesheet

Additional stylesheets for this site.

script

Additional scripts for this site.

Each category contains an arrayref of hashrefs of link objects. See the Statocles::Link documentation for a full list of supported attributes. The most common attributes are:

href

The URL for the link.

text

The text of the link. Not needed for stylesheet or script links.

images

# site.yml
images:
    icon: /images/icon.png

Related images for this document. These are used by themes to display images in appropriate templates. Each image has a category, like title, banner, or icon, mapped to an image object. See the Statocles::Image documentation for a full list of supported attributes. The most common attributes are:

src

The source path of the image. Relative paths will be resolved relative to this document.

alt

The alternative text to display if the image cannot be downloaded or rendered. Also the text to use for non-visual media.

Useful image names are:

icon

The shortcut icon for the site.

templates

# site.yml
templates:
    sitemap.xml: custom/sitemap.xml
    layout.html: custom/layout.html

The custom templates to use for the site meta-template like sitemap.xml and robots.txt, or the site-wide default layout template. A mapping of template names to template paths (relative to the theme root directory).

Developers should get site templates using the template method.

template_dir

The directory (inside the theme directory) to use for the site meta-templates.

deploy

The deploy object to use for deploy(). This is intended to be the production deployment of the site. A build gets promoted to production by using the deploy command.

data

A hash of arbitrary data available to theme templates. This is a good place to put extra structured data like social network links or make easy customizations to themes like header image URLs.

log

A Mojo::Log object to write logs to. Defaults to STDERR.

markdown

The Text::Markdown object to use to turn Markdown into HTML. Defaults to a plain Text::Markdown object.

Any object with a "markdown" method will work here.

disable_content_template

This disables processing the content as a template. This can speed up processing when the content is not using template directives.

This can be also set in the application ("disable_content_template" in Statocles::App), or for each document ("disable_content_template" in Statocles::Document).

_pages

A cache of all the pages that the site contains. This is generated during the build phase and is available to all the templates while they are being rendered.

METHODS

BUILD

Register this site as the global site.

app

my $app = $site->app( $name );

Get the app with the given name.

my @links = $site->nav( $key );

Get the list of links for the given nav key. Each link is a Statocles::Link object.

title - The title of the link
href - The href of the link

If the named nav does not exist, returns an empty list.

build

$site->build( %options );

Build the site in its build location. The %options hash is passed in to every app's pages method, allowing for customization of app behavior based on command-line.

links

my @links = $site->links( $key );
my $link = $site->links( $key );
$site->links( $key => $add_link );

Get or append to the links set for the given key. See the links attribute for some commonly-used keys.

If only one argument is given, returns a list of link objects. In scalar context, returns the first link in the list.

If two arguments are given, append the new link to the given key. $add_link may be a URL string, a hash reference of link attributes, or a Statocles::Link object. When adding links, nothing is returned.

url

my $url = $site->url( $page_url );

Get the full URL to the given path by prepending the base_url.

template

my $template = $app->template( $tmpl_name );

Get a template object for the given template name. The default template is determined by the app's class name and the template name passed in.

Applications should list the templates they have and describe what page class they use.

EVENTS

The site object exposes the following events.

collect_pages

This event is fired after all the pages have been collected, but before they have been rendered. This allows you to edit the page's data or add/remove pages from the list.

The event will be a Statocles::Event::Pages object containing all the pages built by the apps.

before_build_write

This event is fired after the pages have been built by the apps, but before any page is written to the build_store.

The event will be a Statocles::Event::Pages object containing all the pages built by the apps.

build

This event is fired after the site has been built and the pages written to the build_store.

The event will be a Statocles::Event::Pages object containing all the pages built by the site.

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.