view release on metacpan or  search on metacpan

lib/App/ZofCMS.pm  view on Meta::CPAN

package App::ZofCMS;

use warnings;
use strict;

our $VERSION = '1.001010'; # VERSION

1;
__END__

=encoding utf8

=head1 NAME

App::ZofCMS - web framework and templating system for small-medium sites.

=head1 SYNOPSIS

This module is just the main documentation for ZofCMS framework. See
L<USING THE FRAMEWORK> section below for explanation of how to use this
framework.

=head1 WARNING

=for html  <div style="display: table; height: 91px; background: url(http://zoffix.com/CPAN/Dist-Zilla-Plugin-Pod-Spiffy/icons/section-warning.png) no-repeat left; padding-left: 120px;" ><div style="display: table-cell; vertical-align: middle;">

I have no desire to continue development or maintenance of this framework.
As far as I know, I am the only developer. My only ties to this
framework is its use at $work and I am actively trying to switch
to L<Mojolicious>. For that reason,
I strongly recommend you do NOT use this framework. Please see
L<Mojolicious>, L<Catalyst>, L<Dancer>, or L<Dancer2> as alternatives.

=for html  </div></div>

=head1 DESCRIPTION

ZofCMS stands for "Zoffix's Content Management System", however I prefer
it to be just a name. It is a small web framework/templating system designed
to be easily installed and workable on limited severs, i.e. the ones that do
not allow you to install perl modules from CPAN, don't have ssh and
occasionally don't even offer any SQL databases. If you have more freedom
than that you may want to give L<Catalyst> a try which, my opinion, is
a great framework, not just for web, and it offers far more functionality
than ZofCMS ever will.

ZofCMS is plugin based. If you create your own plugins, please upload them
to L<App::ZofCMS::Plugin> namespace or email it to me (C<zoffix@cpan.org>)
and I will package it, upload it, and give you corresponding credits.

ZofCMS currently uses L<HTML::Template> as a module to interpret HTML
templates. And so far, I have no plans to change this to anything alike
L<Template::Toolkit>.

Despite the "core" of the framework along with all of its plugins being
on CPAN there is a helper script (C<zofcms_helper>) which can produce
a ready-for-upload set of files which you can simply upload to your server
without having to install anything from CPAN on the server itself. See
C<perldoc zofcms_helper>.

=head1 HYSTORY

This section does not say anything useful, you can skip it if you are
not interested in what made me create ZofCMS.

For about two-three years name "ZofCMS" lived more as a joke. A lot of
people in IRC channels such as C<#css> would ask me what web framework
I use (I didn't use any at the time) and I would gladly say "I use ZofCMS"
instead of the expected "Drupal" or "Wordpress".

After coding a templating system from scratch for
one of the sites, which runs on the server without any SQL, ssh
or ability to install any perl modules directly from CPAN, I already felt
that something needed to be done. The "perl hashref" templates which I used
to make all those products displayed with only one L<HTML::Template>
template proved to be flexible, extendable and maintainable and that's
exactly from where ZofCMS template format came.

The last site I coded before starting to implement ZofCMS was a private
web application which had a message board along with a few other features.
Mostly everything was coded from scratch once more... The final breaking
point when a few weeks later I was asked to add two sections for file
uploads to that site. No, it wasn't hard to add them, it's just that
I found myself adding a couple lines of code to the "core" modules that
called modules which provided new functionality and those modules were
loaded on any page of the site; even the ones that would never require
functionality from those modules. That's where the idea of plugins came
to life including the idea of "page templates" asking for plugins which
are needed only on that specific page.

After being told at work that I will be putting up about nine sites in
near future I started putting actual ZofCMS code "on paper". The first
"site" was a single page because the content for it was not yet ready, we
just needed "something" to be up. I've used the baby ZofCMS (yet without
any helper scripts) and was quite happy with the ease of installation.
Despite my framework driving just single page being an overkill I already
was prepared for anything which is to be thrown on that site and was
confident that I will no longer have to hack around existing Perl code
on the site.

"What about L<Catalyst>?", you may ask. Well, here is my answer.
L<Catalyst> is GREAT! I love it. It's magic. But even on
L<http://zoffix.com/>, which allows me to easily install modules directly
from CPAN AND gives me ssh access, I spent quite some time deploying
my Catalyst application. As I am not creating very large sites at work
(or at home for that matter) I feel that Catalyst is an overkill for what
I do. I definitely recommend Catalyst to everyone. We make our own choices
- I am happy with the ones I've made.

=head1 HOW DOES IT WORK

There is a single C<index.pl> script. The page to display is specified
via C<page> query parameter (it can come from either POST or GET requests).
There is also a C<dir> parameter, but it's use it optional. For example,
if you are to access C<index.pl?page=foo/bar/baz/page> framework will
convert the query into C<page=page&dir=foo/bar/baz/>.

The "config file" (see L<App::ZofCMS::Config>) is loaded and checked whether
or not the specified page is an "allowed page"; if it isn't, user will
be presented with a 404.

Later on, the "ZofCMS template" file is located and loaded. This template
is just a file with a Perl hashref in it. All keys have special meanings,
see L<App::ZofCMS::Template> for details. Some (or even all) of those keys
can be specified in the "config file" under several keys which provide
"defaults", see L<App::ZofCMS::Config> for details.

ZofCMS template will reference a "base" template (which is a
L<HTML::Template> template) as well as several other L<HTML::Template>
files. The framework then will run any plugins, fill out all the values
in the templates and display the page to the user.

=head1 USING THE FRAMEWORK

=head2 FIRST TIME USE

Ok, if you are reading this I can assume you want to give ZofCMS a whirl.
This documentation describes how to install/use it from CPAN. I am also
planing to put up a ZofCMS tarball on L<http://web-tools.cc/tools/ZofCMS/>
from which you can get started without touching CPAN (for the most part).
At the time of this writing that webpage is not yet up.

First of all, install C<App::ZofCMS> "module" via your cpan script. If you