NAME

Statocles::Document - Base class for all Statocles documents

DESCRIPTION

A Statocles::Document is the base unit of content in Statocles. Applications take documents to build pages.

Documents are usually written as files, with the content in Markdown, and the other attributes as frontmatter, a block of YAML at the top of the file.

An example file with frontmatter looks like:

    ---
    title: My Blog Post
    author: preaction
    links:
        stylesheet:
            - href: /theme/css/extra.css
    ---
    In my younger and more vulnerable years, my father gave me some

ATTRIBUTES

path

The path to this document. This is not settable from the frontmatter.

store

The Store this document comes from. This is not settable from the frontmatter.

title

    ---
    title: My First Post
    ---

The title of this document. Used in the template and the main page title. Any unsafe characters in the title (<, >, ", and &) will be escaped by the template, so no HTML allowed.

author

    ---
    author: preaction <doug@example.com>
    ---

The author of this document. Optional. Either a simple string containing the author's name and optionally, in ><, the author's e-mail address, or a hashref of Statocles::Person attributes.

    ---
    # Using Statocles::Person attributes
    author:
        name: Doug Bell
        email: doug@example.com
    ---

status

The publishing status of this document. Optional. Statocles apps can examine this to determine whether to turn a document into a page. The default value is published; other reasonable values could include draft or private.

content

The raw content of this document, in markdown. This is everything below the ending --- of the frontmatter.

links

    ---
    links:
        stylesheet:
            - href: /theme/css/extra.css
        alternate:
            - href: http://example.com/blog/alternate
              title: A contributed blog
    ---

Related links for this document. 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 the content of this document.
script: Additional scripts for the content of this document.
alternate: A link to the same document in another format or posted to another web 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

    ---
    images:
        title:
            src: title.jpg
            alt: A title image for this post
        banner: banner.jpg
    ---

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

date

    ---
    date: 2015-03-27
    date: 2015-03-27 12:04:00
    ---

The date/time this document is for. For pages, this is the last modified date. For blog posts, this is the post's date.

Should be in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format.

template

    ---
    template: /blog/recipe.html
    ---

The path to a template override for this document. If set, the document page will use this instead of the template provided by the application.

The template path should not have the final extention (by default .ep). Different template parsers will have different extentions.

layout

    ---
    layout: /site/layout-dark.html
    ---

The path to a layout template override for this document. If set, the document page will use this instead of the layout provided by the application.

The template path should not have the final extention (by default .ep). Different template parsers will have different extentions.

data

    ---
    data:
      ingredients:
        - Eggs
        - Milk
        - Cheese
    ---
    % for my $item ( @{ $self->data->{ingredients} } ) {
        <%= $item %>
    % }

A hash of extra data to attach to this document. This is available immediately in the document content, and later in the page template.

Every document's content is parsed as a template. The data attribute can be used in the template to allow for some structured data that would be cumbersome to have to mark up time and again.

disable_content_template

    ---
    disable_content_template: true
    ---

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 the entire site ("disable_content_template" in Statocles::Site).

METHODS

parse_content

    my $doc = $class->parse_content(
        path => $path,
        store => $store,
        content => $content,
    );

Construct a document the given content, with the given additional attributes. Returns a new Statocles::Document object.

This parses the YAML or JSON frontmatter into the document's attributes, putting the rest of the file after the YAML or JSON frontmatter in the content attribute.

Custom document classes can override this method to change how file content is parsed.

deparse_content

    my $content = $doc->deparse_content;

Deparse the document into a string ready to be stored in a file. This will serialize the document attributes into YAML frontmatter, and place the content after.