NAME

CatalystX::CMS::Tutorial - drop-in content management system

DESCRIPTION

CatalystX::CMS (CXCMS) is a set of Catalyst base classes that enable web-based editing and revision history of your application templates. The impetus behind the project is simple: sometimes you need to give non-programmers an easy way to manage your application templates, or to allow them to extend the application with new content.

This tutorial provides an overview of the project and offers examples of CatalystX::CMS in use.

OVERVIEW

The basic premise is simple: any URL in your Catalyst application can be made edit-able by making your controller class a subclass of CatalystX::CMS::Controller. This magic is achieved through CatalystX::CMS::Action, which evaluates every action for the presence of the cxcms request parameter. If that parameter is present and true, then the appropriate CMS method is called. Otherwise, your normal action chain is executed.

The CMS editor interface pulls up the raw Template Toolkit file and allows the user to edit it in a text box. The TT files are then stored in a Subversion repository, so you get all the Subversion features for your templates: revision history, diff, blame, etc.

TEMPLATE STRUCTURE

CXCMS assumes the following template structure:

 wrapper.tt
 header.tt
 body.tt
 footer.tt

The wrapper.tt file calls the other three.

In addition to the four-part template, CXCMS supports two levels of abstraction: type and flavour. The type is intended to be used like a MIME type. The default type is html. The flavour is intended to be used like a theme or skin designation. The template directory structure is assumed to be:

 type/flavour/wrapper.tt
 type/flavour/header.tt
 type/flavour/body.tt
 type/flavour/footer.tt

This structure supports the idea of multiple flavours for each type.

A NEW PROJECT

This example looks at creating a new application designed specifically for managing mostly raw HTML files. Look at the example app in the distribution t/ dir for an example.

Bootstrap your app:

 % catalyst.pl MyCMS
 % cd MyCMS
 % script/mycms_create.pl controller CMS CMS
 % script/mycms_create.pl model CMS CMS
 % script/mycms_create.pl view CMS CMS

Add the config to lib/MyCMS.pm

 __PACKAGE__->config(
    cms => {
        use_editor => 1,
        use_layout => 1,
        root => { 
            r   => [ __PACKAGE__->path_to('root') ], 
            rw  => ['/tmp/mycms/work'] 
        },
    },
 );
 

Get your css and js files served for free by the Static::Simple plugin. Edit lib/MyCMS.pm to include:

 use Class::Inspector;
 use Path::Class::Dir;
 use CatalystX::CMS;
 my $cms_base = Class::Inspector->loaded_filename( 'CatalystX::CMS' );
 $cms_base =~ s/\.pm$//;

 __PACKAGE__->config(
    static           => {
        include_path => [
            __PACKAGE__->path_to( 'root' ),
            Path::Class::dir( $cms_base, 'tt' )
        ],
    }
 );
 

Create your local svn repos and workdir:

 % mkdir /tmp/mycms
 % svnadmin create /tmp/mycms/repos
 % cd /tmp/mycms
 % svn co file:///tmp/mycms/repos work
 % cd -

Start up the test server:

 % script/mycms_server.pl

Point your browser at a URL that doesn't yet exist:

 http://localhost:3000/cms/foo

You should be prompted to create the file. If you click on the file name foo you should be redirected to the CMS editor. Change the default text:

 [ this is a new page ]

to something more meaningful and click Save. You should be redirected to the new URL.

See the section on "TEMPLATE STRUCTURE" for tips on customizing the default HTML templates.

AN EXISTING PROJECT

CXCMS was designed to drop in easily to existing projects. The easiest way is to change your base class from:

 use base 'Catalyst::Controller';

to:

 use base 'CatalystX::CMS::Controller';

which will make all the actions in your controller editable.

What may take some work will be laying out your template directory structure to work with the CXCMS assumptions. TODO: one more example here.

AUTHOR

Peter Karman, <karman at cpan.org>

BUGS

Please report any bugs or feature requests to bug-catalystx-cms@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS

The Minnesota Supercomputing Institute http://www.msi.umn.edu/ and National Adult Literacy Database http://www.nald.ca/ sponsored the development of this software.

COPYRIGHT & LICENSE

Copyright 2008 by the Regents of the University of Minnesota.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm CatalystX::CMS

perl -MCPAN -e shell
install CatalystX::CMS