Anatomy of a Theme - xenocrat/chyrp-lite GitHub Wiki

Chyrp Lite allows you to extend your blog with powerful themes that can radically alter its presentation and behaviour, using the Twig template engine. Themes are added to Chyrp Lite by copying them into the themes directory in the Chyrp Lite installation, where each theme should be located in its own subdirectory. A fresh install of Chyrp Lite comes with six themes.

Theme Structure

A Chyrp Lite theme is structured as follows:

  • theme
    • content
      • post.twig
      • preview.twig
    • feathers
      • audio.twig
      • link.twig
      • photo.twig
      • quote.twig
      • text.twig
      • uploader.twig
      • video.twig
      • missing.twig
    • filters
      • bazbarfoo.php
    • forms
      • user
        • register.twig
        • login.twig
        • controls.twig
        • lost_password.twig
        • reset_password.twig
    • functions
      • foobarbaz.php
    • info.php
    • javascripts
      • JavaScript files.
    • layouts
      • default.twig
    • pages
      • 403.twig
      • 404.twig
      • archive.twig
      • drafts.twig
      • index.twig
      • page.twig
      • search.twig
      • updated.twig
      • view.twig
    • stylesheets
      • all.css
      • custom.inc.css

Metadata

info.php

This file contains attribution and version information that Chyrp Lite will display in the administration console.

Layouts

The layouts directory contains default.twig that provides the container for every blog page rendered by Chyrp Lite.

Pages

The pages directory contains template twigs that extend default.twig in different contexts. If you add new pages to your blog, they can be given a unique appearance by adding a twig for them in this directory, using the naming convention page_<<page URL>>.twig. You can also add "matter" pages – static templated content not backed by the database – using the naming convention matter_<<name>>.twig.

403.twig

extends: layouts/default.twig

This twig is the template for a 403 (forbidden) error page.

404.twig

extends: layouts/default.twig

This twig is the template for a 404 (resource not found) error page.

archive.twig

extends: layouts/default.twig

This twig is the template for a page that displays a chronological archive of blog posts.

drafts.twig

extends: layouts/default.twig

This twig is the template for a page that displays the draft blog posts of a logged-in user.

index.twig

extends: layouts/default.twig

This twig is the template for a page that displays the blog index.

page.twig

extends: layouts/default.twig

This twig is the template for displaying pages (articles published separate from your blog content).

search.twig

extends: layouts/default.twig

This twig is the template for a page that displays the blog posts returned a search.

updated.twig

extends: layouts/default.twig

This twig is the template for a page that displays updated posts in order of update.

view.twig

extends: layouts/default.twig

This twig is the template for a page that displays a single blog post in isolation.

Content

post.twig

This twig renders blog posts. It is extended by whichever feather was used to create the post.

preview.twig

This twig renders previews in an iframe on the Write pages. The twig should display an approximation of how the text will appear in a published post or page.

Feathers

The feathers directory contains twigs dedicated to rendering various feathers.

text.twig

extends: content/post.twig

This twig allows Chyrp Lite to render plain text blog posts handled by the text feather.

audio.twig

extends: content/post.twig

This twig allows Chyrp Lite to render audio posts handled by the audio feather.

video.twig

extends: content/post.twig

This twig allows Chyrp Lite to render video posts handled by the video feather.

link.twig

extends: content/post.twig

This twig allows Chyrp Lite to render link posts handled by the link feather.

photo.twig

extends: content/post.twig

This twig allows Chyrp Lite to render photo posts handled by the photo feather.

quote.twig

extends: content/post.twig

This twig allows Chyrp Lite to render quoted text blog posts handled by the quote feather.

uploader.twig

extends: content/post.twig

This twig allows Chyrp Lite to render blog posts with attached files handled by the uploader feather.

missing.twig

extends: content/post.twig

This twig is displayed as a fallback if the theme does not have a template to support a feather type.

Forms

The forms directory contains twigs that contain HTML forms for various purposes.

user/register.twig

extends: layouts/default.twig

This twig allows a visitor to your blog to become a registered user.

user/login.twig

extends: layouts/default.twig

This twig allows a registered user to log in.

user/controls.twig

extends: layouts/default.twig

This twig allows a registered user to change various details, including their password.

user/lost_password.twig

extends: layouts/default.twig

This twig allows a registered user to reset their password.

user/reset_password.twig

extends: layouts/default.twig

This twig displays a password reset form that can only be accessed within 1 hour of request.

Filters

The filters directory can contain custom Twig filters to be used in theme templates. Custom filters must have a filename matching the filter name, with the extension .php. The PHP script in the file should return an anonymous function that implements the desired behaviour. An example bazbarfoo custom filter, bazbarfoo.php, is included with all bundled themes.

Functions

The functions directory can contain custom Twig functions to be used in theme templates. Custom functions must have a filename matching the function name, with the extension .php. The PHP script in the file should return an anonymous function that implements the desired behaviour. An example foobarbaz custom function, foobarbaz.php, is included with all bundled themes.

JavaScripts

The javascripts and js directories contain JavaScript files that will be loaded by the theme's pages. Files with names containing .inc.js will not be served to the visitor.

Stylesheets

The stylesheets and css directories contain CSS files that will be loaded by the theme's pages. Files with names containing .inc.css will not be served to the visitor, allowing you to @import them in one of your other stylesheets. For all bundled themes, the sytlesheet custom.inc.css is empty and pre-configured as CSS cascade layer, providing a simple way to do basic theme customisation.