NAME
Lavoco::Web::App - Experimental framework.
Framework to run small web apps, URL dispatching based on a flexible config file, rendering Template::Toolkit templates.
VERSION
Version 0.01
SYNOPSIS
A FastCGI web-app for serving Template::Toolkit templates.
This is an experimental framework to control various small websites, use at your own risk.
use Lavoco::Web::App;
my $app = Lavoco::Web::App->new( name => 'Example' );
my $action = lc( $ARGV[0] ); # (start|stop|restart)
$app->$action;METHODS
Class Methods
new
Creates a new instance of the web-app object.
Instance Methods
name
The identifier for the web-app, used as the FastCGI-process title.
base
The base directory of the application, detected using FindBin.
dev
A simple boolean flag to indicate whether you're running a development instance of the web-app.
It's on by default, and currently turned off if the base directory contains /live. Feel free to set it based on your own logic before calling start().
I typically use working directories such as /home/user/www.example.com/dev and /home/user/www.example.com/live.
This flag is useful to disable things like Google Analytics on the dev site.
The application object is available to all templates under the name app.
e.g. [% IF app.dev %] ... [% END %]
processes
Number of FastCGI process to spawn, 5 by default.
$app->processes( 10 );templates
The directory containing the TT templates, by default it's $app->base . '/templates'.
start
Starts the FastCGI daemon. Performs basic checks of your environment and dies if there's a problem.
stop
Stops the FastCGI daemon.
restart
Restarts the FastCGI daemon, with a 1 second delay between stopping and starting.
CONFIGURATION
The app should be a simple Perl script in a folder with the following structure:
app.pl # see the synopsis
app.json # see below
app.pid # generated, to control the process
app.sock # generated, to accept incoming FastCGI connections
logs/
templates/
404.ttThe config file is read for each and every request, this makes adding new pages easy, without the need to restart the application.
Currently only JSON is supported for the config file, named app.json. This should be placed in the base directory of your application.
See the examples directory for a sample JSON config file, something like the following...
{
"pages" : [
{
"path" : "/",
"template":"index.tt",
...
},
...
]
...
"send_alerts_from":"The Example App <no-reply@example.com>",
"send_404_alerts_to":"you@example.com",
...
}The entire config hash is available in all templates via [% app.config %], there are only a couple of mandatory/reserved attributes.
The mandatory field in the config is pages, which is an array of JSON objects.
Each page object should contain a path (for URL matching) and template to render.
All other fields are completely up to you, to fit your requirements.
When a request is made, a lookup is performed for a page by matching the path, which then results in rendering the associated template.
If no page is found, the template 404.tt will be rendered, make sure you have this file ready in the templates directory.
The page object is available in the rendered template, eg, [% page.path %]
It is often useful to have sub-pages and categories, etc. Simply create a pages attribute in a page object as another array of page objects.
If a sub-page is matched and selected for a request, an extra key for parents is included in the page object as a list of the parent pages, this is useful for building breadcrumb links.
TODO
More documentation.
Deep recursion for page/path lookups.
Deep recursion for sitemap.
Cleanup deeper recursion in pages with parents.
Searching, somehow, of some set of templates.
AUTHOR
Rob Brown, <rob at intelcompute.com>
LICENSE AND COPYRIGHT
Copyright 2014 Rob Brown.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.