NAME

Contentment::Theme - Contentment plugin for adding themes to content

SYNOPSIS

  $context->theme('master', \%arguments);

DESCRIPTION

The theme plugin provides a simple theming system. Basically, the "SYNOPSIS" says it all. To take some data and theme that data, simply call:

  $context->theme('master', \%arguments);

The "master" is the name of the master template to apply to the arguments. The arguments will be passed to the theme in the way that arguments are normally passed to the filetype of the master template.

HOW THEMES WORK

If you want to create a theme, you need to understand how theming works. Of course, you probably want to have a general idea if you are using them too.

Essentially, the themes are loaded via the VFS path named something like this:

  /themes/<theme>/<kind>/<master>

Each of the variables <theme>, <kind>, and <master> translate into a piece of the path to the theme template. Other theming assets may be found under the /themes directory as well.

The <theme> variable is currently set using the default_theme variable of the Contentment::Plugin::Settings setting. However, if a template is requested that cannot be found in a theme, the theme named default is also searched as a fallback.

The <kind> variable is the kind of master to pull from. This allows for documents to be served in multiple formats. In general, you just need to fill the text/html subdirectories (e.g., /themes/default/text/html).

The <master> variable is the name of the actual template file to use. It may also include additional subdirectories. For example, the Form plugin employs the use of masters like form/Form and form/Submit for the various controls. The top-level or page-level document is generally called top.

The templates themselves are generally created for particular uses. The uses are generally defined by each of the plugins. Eventually the manual will show the primary templates and the arguments they are typically passed.

Basically, all theme data is stored under the /themes directory of the VFS. Inside that directory are subdirectories containing one or more themes. There must always be a theme named default inside of the /themes directory that is used as a fallback.

Inside of each theme directory are directories for each destination file type that a theme should be applied to and any extra files and directories used by the theme. So far, the convention has been to create a directory named images to hold the graphics and photos, styles to hold stylesheets, and the rest are actual themes. However, the theme designer may arrange her files in whichever way is convenient.

Since the typical final file type uses the MIME-type "text/html", the theme directory for HTML files is usually a nested directory, text/html. Once inside the file type directory, the theme master is used to render the theme. The theme master can be anything. By default the top-level or page theme is called top. Thus, altogether, the path to a theme master is:

CONTEXT

This class adds the following methods to the context:

$context->theme($master, \%args)

This applies the requested theme master, $master, using the current file type stored in Contentment::Response-top_kind> and the theme set in the "default_theme" key of the "Contentment::Plugin::Theme" setting.

The special parameter "theme_dir" is passed to every template during generation to let it know of the template's base directory. This is relative to the base URL, so you may need to include a reference to the site variable "base_url" if you need an absolute base address for the client:

  my $site = Contentment::Site->current_site;
  print $site->base_url;

or using a Template Toolkit template:

  [% USE Site %]
  [% Site.base_url %]

HOOK HANDLERS

Contentment::Theme::upgrade

This handler is for the "Contentment::upgrade" hook and is responsible for making sure any changes to "default_theme" or "default_template" are transferred during upgrades.

Contentment::Theme::apply_theme

Handles the "Contentment::Response::filter" hook by attempting to wrap the generated output with a theme, or leaving the output as is if there is no matching theme handler.

Contentment::Theme::begin

Handles the "Contentment::begin" hook. When run, it notifies the VFS to add the plugins "docs" folders layer.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.

Contentment is licensed and distributed under the same terms as Perl itself.