view release on metacpan or  search on metacpan

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

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 I<Build.PL> or I<Makefile.PL> has installed the code.

The module which reads the file is C<App::Office::CMS::Util::Config>.

Both I<Build.PL> or I<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.

=head2 Creating the database

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

=head2 Creating and populating the database tables

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:

=over 4

=item o Perl looks in the current directory structure for the modules

That is, Perl does not use the installed version of the code, if any.

=item o The code looks in the current directory structure for .htoffice.cms.conf

That is, it does not use the installed version of this file, if any.

=back

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.

=head1 Installing the module

Install L<App::Office::CMS> as you would for any C<Perl> module:

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.

=head2 Install the L<Text::Xslate> (HTML and Javascript) template files

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.

=head2 Install the FAQ web page

This FAQ is for using C<App::Office::CMS> via its CGI scripts, not for the generated web site.

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 L<Pod::Simple::HTML>).

So, copy the sample HTML file into your web server's doc root, or generate another version