view release on metacpan or  search on metacpan

lib/App/Office/CMS.pm  view on Meta::CPAN

L<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.

=back

=head1 FAQ

=over 4

=item o This module doesn't really create entire web sites!

True, but since it's Open Source, you can extend it yourself.

=item o But why don't you add millions of features!

I can give you 3 reasons for that: Canny, Microlight and Simple.

=item o Can I have 2 pages with the same name?

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.

=item o How is the code structured?

MVC (Model-View-Controller).

The sample scripts I<cms.cgi> and I<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:

=over 4

=item o Config.pm

This is used by all code.

=item o Create.pm

This is just used to create tables, populate them, and drop them.

Hence it won't be used by L<CGI> scripts, unless you write such a script yourself.

=item o Logger.pm

This simplifies logging by allowing me to say:

	$self -> log(debug => 'A message');
	$self -> log(info  => 'Another message');

=item o Validator.pm

This is used to validate CGI form data.

=back

=item o What's the database schema?

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 L<GraphViz::DBI>.

=item o Does the database server have pre-requisites?

The code is DBI-based, of course.

Also, the code assumes the database server supports $dbh -> last_insert_id(undef, undef, $table_name, undef).

=item o How do I back up the database?

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:

=over 4

=item o The command is run

=item o STDOUT and STDERR are captured

=item o If STDERR contains anything, the program exits

=item o Otherwise, STDOUT is written to the output file

=back

So, why are there 2 lines, and not something like 'pg_dump -U cms cms > /tmp/pg.cms.backup.dat'?

Because I use L<Capture::Tiny>, which does not want you to use redirection.

Lastly, the output is written using L<File::Slurper>.

=item o What's this thing called 'context' in the menus and pages tables?

It's the value ("$site_id/$design_id") which ties those 2 tables together, just like a foreign key.

=item o What are these fields menu_orientation_id and os_type_id in the designs table?

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.

=item o I added a field to update_page_form, but it's data vanishes.

Basdically, copy the code dealing with 'homepage'.

At the very least, ensure you've updated:

=over 4

=item o App::Office::CMS::Util::Create.create_pages_table()

=item o App::Office::CMS::Database.build_default_page()

=item o App::Office::CMS::Controller::Page

=over 4

=item o build_page_hash()

=item o build_success_result()

=item o check_page_name()

=item o update()

=back

=item o App::Office::CMS::Util::Validator.validate_page()

=item o App::Office::CMS::Database::Page.save_page_record()

=item o App::Office::CMS::View::Page.build_update_page_html()

=back

For site data, start with App::Office::CMS::Controller.build_site_hash().

=item o How to I replace the fundamental editing functionality?

Simply.

=over 4

=item o The 'Edit design' button

This is in site.tx. It's id is submit_edit_design. Leave it as is.

=item o The 'Edit design' Javascript

Clicking [Edit design] triggers a call to update_site_onsubmit(). This is in site.js.

=item o Calling the update_page_callback() function (1 of 2)

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 L<CGI::Application::Dispatch>, this calls C<App::Office::Controller::Page>'s
edit() method.

Change this path info to call a different module. So, 'custom_page/my_edit' will
call C<App::Office::Controller::CustomPage>'s my_edit() method.

=item o CustomPage.pm

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.

=item o Validator.pm

This is C<App::Office::CMS::Util::Validator>. You'll have to edit the
validate_design() method.

=item o The declaration of update_page_callback() (2 of 2)

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.

=item o *::View::Page

You'll need to patch the build_head_js() and build_update_page_html() methods
in this class.

=item o page.tx

This is populated by code in the *::View::Page::build_update_page_html() method.

=item o page.js

This is populated by code in *::View::Page::build_head_js() method.

=item o Site attributes 'v' Design attributes

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 C<App::Office::CMS::Database::Design>'s site2design() method.

=back

=item o Please explain the program, text file, and database table names

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.

=item o Will you re-write it to use a different Javascript library?

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] L<http://use.perl.org/~Ron+Savage/journal/37726>.

=item o How do I change the generated page formats?

The templates used for generating pages are found via the config option
page_template_path.