App::Office::CMS - The Canny, Microlight and Simple CMS
The scripts discussed here, cms.cgi and cms.psgi, are shipped with this module.
A classic CGI script, cms.cgi:
#!/usr/bin/env perl use strict; use warnings; use CGI; use CGI::Application::Dispatch; # --------------------- my($cgi) = CGI -> new; CGI::Application::Dispatch -> dispatch ( args_to_new => {QUERY => $cgi}, prefix => 'App::Office::CMS::Controller', table => [ '' => {app => 'Initialize', rm => 'display'}, ':app' => {rm => 'display'}, ':app/:rm/:id?' => {}, ], );
A Plack script, cms.psgi:
#!/usr/bin/env perl use strict; use warnings; use CGI::Application::Dispatch::PSGI; use Plack::Builder; # --------------------- my($app) = CGI::Application::Dispatch -> as_psgi ( prefix => 'App::Office::CMS::Controller', table => [ '' => {app => 'Initialize', rm => 'display'}, ':app' => {rm => 'display'}, ':app/:rm/:id?' => {}, ], ); builder { enable "Static", path => qr!^/(assets|favicon|yui)/!, root => '/var/www'; $app; };
For more on Plack, see my intro to Plack: http://savage.net.au/Perl/html/plack.for.beginners.html.
App::Office::CMS is the Canny, Microlight and Simple Content Management System.
The canniness comes in observing that almost all web sites have a menu for navigation.
So, this module gives you (the content manager) a menu designer.
The idea is that the menu you design is 'live', so you use the web site's own menu to design both the menu itself and the whole web site.
This means use Moo rather than Moose.
For the same reason, DBIx::Simple rather than DBIx::Class.
And hence Brannigan rather than Data::Verifier, because the latter uses Moose::Util::TypeConstraints, and hence a whole slew of Moose::Meta::* modules.
Lastly, I'm not claiming this package is as small as it could possibly be. For example, I could replace Text::Xslate with HTML::Template to shrink it, but I don't want to do that.
The other motivation is to deliver an application which anyone, with minimal training, can master.
Up to V 1.00, 99.99% of the effort went into the structure of the code, i.e. the mangement of a web site, and not into supporting content generation.
That's why the features provided for generating content are minimalistic.
The end-user docs are discussed below, under FAQ, and are strongly recommended reading.
This is a simplified version:
You can create any number of web sites.
Each web site can have any number of designs.
Every design has a menu of web pages.
As expected, each design consists of any number of web pages.
When you create a new site and design, a default web page is created.
This also happens if you change the name of a web site or of a design, and click Save.
This web page has a default asset (output file template), and default (empty) content.
To make it easy to edit!
Also note that there are 2 template files shipped with this distro, one for the homepage and one for any other page. These templates are not fancy, they are just there as guidelines for how you should develop your own templates.
See htdocs/assets/templates/app/office/cms/page.templates/*.tx for the templates.
See also data/asset_types.txt for the other place template information is stored.
So far, each web page is given a small number of attributes, including the template to be used to create the corresponding output web page (at generation time).
Using the Javascript editor, you create the content for each page.
Web pages are generated by pouring the content into the template.
Two (2) sample templates are provided.
See lib/App/Office/CMS/.htoffice.cms.conf.
As far as possible, Try::Tiny is used to catch non-DBI errors.
DBI errors are caught using the HandleError attribute key in the call to DBI's connect() method.
Minimal effort has been made to sanitize error messages, so there's a risk that information you don't wish to leak out may be displayed on the end-user's screen.
Feel free to recommend changes in this area.
CGI form field data is passed thru CGI::Untaint and, optionally, HTML::Defang.
This module is available as a Unix-style distro (*.tgz).
See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing distros.
This module does not ship with YUI. You can get it from: http://developer.yahoo.com/yui.
All development was done using V 2.8.1.
Currently, I have no plans to port this code to V 3 of YUI.
See also lib/App/Office/CMS/.htoffice.cms.conf, where it specifies the URL used by the code to find YUI's JavaScript files.
The output templates use these 5 YUI files:
At various places I refer to a file, lib/App/Office/CMS/.htoffice.cms.conf, shipped in this distro.
Please realize that if you edit this file, you must ensure the copy you are editing is the one used by the code at run-time.
After a module such as this is installed, the code will look for that file in the directory where Build.PL or Makefile.PL has installed the code.
The module which reads the file is App::Office::CMS::Util::Config.
App::Office::CMS::Util::Config
Both Build.PL or Makefile.PL install .htoffice.cms.conf along with the Perl modules.
So, if you unpack the distro and edit the file within the unpacked code, you'll still need to copy the patched version into the installed code's directory structure.
There is no need to restart your web server after updating this file.
OK, here we go...
I use SQLite because it's shipped with recent versions of Perl.
Running scripts/create.tables.pl (below) will create the database.
If you use Postgres, do this to create the database:
shell>psql -U postgres psql>create role cms login password 'cms'; psql>create database cms owner cms encoding 'UTF8'; psql>\q
The distro contains a set of text files which are used to populate constant tables. All such data is in the data/ directory.
This data is loaded into the database using programs in the distro. All such programs are in the scripts/ directory.
After unpacking the distro, create and populate the database thus:
shell>cd App-Office-CMS-1.00 # Naturally, you only drop /pre-existing/ tables :-), # so use drop.tables.pl later, when re-building the db. #shell>perl -Ilib scripts/drop.tables.pl -v shell>perl -Ilib scripts/create.tables.pl -v shell>perl -Ilib scripts/populate.tables.pl -v shell>perl -Ilib scripts/report.tables.pl -v
See also scripts/new.db.sh.
Note: The '-Ilib' means 2 things:
That is, Perl does not use the installed version of the code, if any.
That is, it does not use the installed version of this file, if any.
So, if you leave out the '-Ilib', Perl will use the version of the code which has been previously installed, and then the code will look in the same place for .htoffice.cms.conf.
Install App::Office::CMS as you would for any Perl module:
Perl
Run:
cpanm App::Office::CMS
or run:
sudo cpan App::Office::CMS
or unpack the distro, and then either:
perl Build.PL ./Build ./Build test sudo ./Build install
or:
perl Makefile.PL make (or dmake) make test make install
Either way, you need to install all the other files which are shipped in the distro.
Copy the distro's htdocs/assets/ directory to your web server's doc root.
Specifically, my doc root is /dev/shm/html, so I end up with /dev/shm/html/assets/.
/dev/shm is Debian's RAM disk. Your doc root might be /var/www, or even /var/www/html.
This FAQ is for using App::Office::CMS via its CGI scripts, not for the generated web site.
App::Office::CMS
In lib/App/Office/CMS/.htoffice.cms.conf there is a line:
program_faq_url=/assets/templates/app/office/cms/cms.help.html
This page is displayed when the user clicks FAQ on the About tab.
A sample page is shipped in docs/html/cms.help.html. It has been built from docs/pod/cms.help.pod (by running a script I wrote, pod2html.pl, which in turn is a simple wrapper around Pod::Simple::HTML).
So, copy the sample HTML file into your web server's doc root, or generate another version of the page, using docs/pod/cms.faq.pod as input.
Copy the distro's httpd/cgi-bin/office/ directory to your web server's cgi-bin/ directory, and make cms.cgi executable.
If I used Apache, my cgi-bin/ dir would be /usr/lib/cgi-bin/, so I would end up with /usr/lib/cgi-bin/office/cms.cgi.
Actually, I run nginx (Engine X) http://wiki.nginx.org/Main, which does not serve CGI scripts, and tiny (thttpd) http://acme.com/software/thttpd/, which does.
See http://wiki.nginx.org/ThttpdCGI for patching tiny.
See also http://savage.net.au/Perl/html/env.report.html.
Try:
starman -l 127.0.0.1:5006 --workers 1 httpd/cgi-bin/office/cms.psgi &
Or, for good debug output:
plackup -l 127.0.0.1:5006 httpd/cgi-bin/office/cms.psgi &
Or, install cms.cgi and point your browser at:
http://127.0.0.1/cgi-bin/cms.cgi.
Mostly, you'll be working on the Edit Content tab, so that's where the [Generate] button is.
Clicking [Generate] generates all of the pages in the current design. You do not have to be editing content for the homepage to use the [Generate] button.
The disk directory structure created matches the tree structure you have created via the Edit Pages tab.
So, if you created a page called Offices, and under that 2 children called Locations and Staff, then these files will be output:
There are various things to note:
This conversion is done with String::Dirify.
This structure is generated by tracing the ancestors of each page up the tree of pages, to the root (but excluding the root), and using the parent, grand-parent, etc, names as directory names.
When a site is created, you specify an output directory, and the directories mentioned in the previous items are created under the site's directory.
So, if this site's output directory was in Debian's RAM disk at /dev/shm/html, then the output files' full paths would be:
Path::Class is used to construct these paths in an OS-independent manner, which means you must provide the site's output directory in a format suitable for your OS.
True, but since it's Open Source, you can extend it yourself.
I can give you 3 reasons for that: Canny, Microlight and Simple.
No. When user input is being checked, the page is searched for by name, and a match means the new input is an update for the existing page.
MVC (Model-View-Controller).
The sample scripts cms.cgi and cms.psgi use
prefix => 'App::Office::CMS::Controller'
so the files in lib/App/Office/CMS/Controller are the modules which are run to respond to http requests.
Files in lib/App/Office/CMS/View implement views, and those in lib/App/Office/CMS/Database implement the model.
Files in lib/App/Office/CMS/Util are a mixture:
This is used by all code.
This is just used to create tables, populate them, and drop them.
Hence it won't be used by CGI scripts, unless you write such a script yourself.
This simplifies logging by allowing me to say:
$self -> log(debug => 'A message'); $self -> log(info => 'Another message');
This is used to validate CGI form data.
See docs/cms.schema.png.
The file was created with scripts/schema.sh, which uses dbi.schema.pl.
That program is a version of dbigraph.pl, which ships with GraphViz::DBI.
The code is DBI-based, of course.
Also, the code assumes the database server supports $dbh -> last_insert_id(undef, undef, $table_name, undef).
See the config file .htoffice.cms.conf:
backup_command = pg_dump -U cms cms backup_file = /tmp/pg.cms.backup.dat
When backup_command has a value, the Edit Contents tab gets a [Backup] button, and when this button is clicked:
So, why are there 2 lines, and not something like 'pg_dump -U cms cms > /tmp/pg.cms.backup.dat'?
Because I use Capture::Tiny, which does not want you to use redirection.
Lastly, the output is written using File::Slurper.
It's the value ("$site_id/$design_id") which ties those 2 tables together, just like a foreign key.
I originally allowed the user to select a horizontal or vertical menu format, when generating pages.
The vertical menu is just the tree I ended up with.
I decided not to support horizontal menus, at least in the short term, because of the width of such a menu when the page names became long. It would have appeared just above the site map on the Edit Pages tab, and would have been clickable in the same way the site map tree is.
The os_type_id is for the unsupported code which generates pages in a directory structure for an OS different from the one the code is running on.
You can ignore these 2 fields, and the other 2 tables, menu_orientations and os_types.
Basdically, copy the code dealing with 'homepage'.
At the very least, ensure you've updated:
For site data, start with App::Office::CMS::Controller.build_site_hash().
Simply.
This is in site.tx. It's id is submit_edit_design. Leave it as is.
Clicking [Edit design] triggers a call to update_site_onsubmit(). This is in site.js.
This is called from within update_site_onsubmit(). The call is in site.js.
The path info is 'page/edit', which is added to the base '$form_action/'.
As per CGI::Application::Dispatch, this calls App::Office::Controller::Page's edit() method.
App::Office::Controller::Page
Change this path info to call a different module. So, 'custom_page/my_edit' will call App::Office::Controller::CustomPage's my_edit() method.
App::Office::Controller::CustomPage
You write *::Controller::CustomPage.pm, based (obviously) on *::Controller::Page.pm.
You can still let *::View::Page process your updated page.tx and page.js templates. See below for details.
This is App::Office::CMS::Util::Validator. You'll have to edit the validate_design() method.
App::Office::CMS::Util::Validator
This is in page.js. This is the Javascript function which receives the output of CustomPage.pm.
Replace the code in this function as needed.
You'll need to patch the build_head_js() and build_update_page_html() methods in this class.
This is populated by code in the *::View::Page::build_update_page_html() method.
This is populated by code in *::View::Page::build_head_js() method.
When a site/design is submitted for saving, some attributes are saved with the site, and some with the design.
If writing to the database fails, it's probably because the attributes for the design were not copied from the CGI form fields.
Check App::Office::CMS::Database::Design's site2design() method.
App::Office::CMS::Database::Design
Programs are shipped in scripts/, and data files in data/.
I prefer to use '.' to separate words in the names of programs.
However, for database table names, I use '_' in case '.' would case problems.
Programs such as create.tables.pl and populate.tables.pl, use table names for their data files' names. Hence the '_' in the names of their data files.
No, that would be an unproductive use of my time.
Other such libraries might do a good job, but I don't believe they'll do a better job.
I have published a review of various Javascript libraries [1], and IMHO YUI is the best.
[1] http://use.perl.org/~Ron+Savage/journal/37726.
The templates used for generating pages are found via the config option page_template_path.
All *.tx files in this directory are put into the page template menu on the 'Update Design' page.
The default homepage template is home.page.tx.
The default generic page template is generic.page.tx.
For various reasons:
... does not parse the parameters to new().
... to have BUILD() (or even init() ) called after new().
... will call init(), but it also drags in another set of dependencies.
... does not have attribute setters.
... a syntax-friendly upgrade path the Moose is preserved.
Probably.
No. Starman, part of Perl's Plack project, is recommended.
See the sample code in httpd/cgi-bin/office.
Heaps: http://cmsmatrix.org/.
With your co-operation, I'd like to reserve the namespace App::Office::CMS, and perhaps even App::Office::Wiki, for my own code.
App::Office::Wiki
Of course, you're much better off using a TiddlyWiki http://tiddlywiki.org/wiki/Main_Page than waiting for me to start writing a wiki.
For massive wikiness (as distinct from wickedness :-) I draw your attention to both Silki and http://foswiki.org/Home/WebHome.
For example, when build_error_result is called, rather than build_success_result, the data sent to Javascript must be handled slightly differently.
This includes HandleError in DBI's connect() attributes.
This would allow the client to pass the menu item's id to the server, instead of the text
We don't.
This saves the user the effort of going to the Search tab to find a site or design
This is so View does not have to pass so many parameters to its 'has-a' attributes
Considered and rejected: HTML::Sanitizer, HTML::Scrubber.
https://github.com/ronsavage/App-Office-CMS.git
Email the author, or log a bug on RT:
https://rt.cpan.org/Public/Dist/Display.html?Name=App-Office-CMS.
App::Office::CMS was written by Ron Savage <ron@savage.net.au> in 2010.
Homepage: http://savage.net.au/index.html.
Australian copyright (c) 2010, Ron Savage.
All Programs of mine are 'OSI Certified Open Source Software'; you can redistribute them and/or modify them under the terms of The Perl License, a copy of which is available at: http://dev.perl.org/licenses/
To install App::Office::CMS, copy and paste the appropriate command in to your terminal.
cpanm
CPAN shell
perl -MCPAN -e shell install App::Office::CMS
For more information on module installation, please visit the detailed CPAN module installation guide.