XML::Template
v3.20
Copyright (c) 2002-2003 Jonathan A. Waxman. All rights reserved.
This is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
NOTE: Because of apparent bugs in the way Perl 5.6.0 handles evals nested
in other evals, XML::Template requires Perl 5.8.0.
1. INSTALL REQUIRED PERL MODULES
---------------------------------
The following Perl modules are required by XML::Template. You should
install the latest versions of these modules, or at least the versions
indicated below before XML::Template is installed. They are all available
from CPAN.
Note that libgdome and libxml2 are prerequisites for XML::GDOME. You can
download them at http://gdome2.cs.unibo.it/#downloads and
http://xmlsoft.org/downloads.html, respectively.
CGI 2.91
Data::Dumper 2.12
DBIx::Wrap 1.00
HTML::Strip 1.01
IO::String 1.02
Mail::Sender 0.8.06
Parse::RecDescent 1.80
WWW::Auth 1.00
XML::GDOME 0.83
XML::SAX 0.12
After you have installed XML::GDOME, add the GDOME SAX parser to the
XML::SAX INI file:
perl -MXML::SAX -e "XML::SAX->add_parser ('XML::GDOME::SAX::Parser')->save_parsers ()"
2. UNCOMPRESS AND UNTAR ZIP FILE
---------------------------------
Uncompress and untar the XML::Template file in to a temporary directory:
gunzip XML-Template-3.20.tar.gz
tar xvf XML-Template-3.20.tar
3. MODIFY Config.pm
--------------------
Modify the file XML-Template-3.20/lib/XML/Template/Config.pm. There are
several configuration variables in this file that you may need to change.
In particular, if you installed XML::Template in a non-standard location,
modify the configuration variable BASEDIR.
4. INSTALL XML::Template
-------------------------
Quick
-----
cd XML-Template-3.20
perl Makefile.PL
make
make test
make install
Details
-------
The above will make and install the XML::Template modules in the standard
Perl library directory. See ExtUtils::MakeMaker for instructions on how
to install the XML::Template Perl modules in non-standard locations.
Additionally, sample configuration files and the siteadmin XHTML files
will be installed in /usr/local/xml-template. The following Makefile.PL
options can be used to initial the auxilliary XML::Template
files in non-standard locations:
XML-TEMPLATE_INSTALL The base directory for auxilliary
XML::Template files. The default is
/usr/local/xml-template.
XML-TEMPLATE_INSTALL_ADMIN The directory where the siteadmin XHTML
files will be installed. The default is
XML-TEMPLATE_INSTALL/admin.
XML-TEMPLATE_INSTALL_DOCS The directory where XML::Template
documentation files will be installed.
The default is XML-TEMPLATE_INSTALL/docs.
XML-TEMPLATE_VERBOSE Whether to output verbose installation
messages. The default is 0 (off).
For instance, if I wanted to install the auxilliary XML::Template files in
my home directory with verbose mode on, I would do
perl Makefile.PL XML-TEMPLATE_INSTALL=/home/jowaxman/xml-template \
XML-TEMPLATE_VERBOSE=1
5. CREATE THE CACHE FILE DIRECTORY
-----------------------------------
XML::Template converts X(HT)ML to Perl code and then evaluates that Perl
code to produce some output. By default, XML::Template writes the Perl
code it creates to files. When XML::Template is requested to display an
X(HT)ML file it has already converted to Perl code, it just loads the file
and evaluates it. This provides a huge performance improvement. The
default cache file directory (defined in Config.pm) is /tmp/xml-template.
XML::Template will create this directory if it does not exist. However,
if you are using XML::Template to display web pages, you will need to
modify the permissions on the cache file directory so your web server can
read and write to it. If you are running Apache, you should give the
cache file directory read and write group access to the web server user's
primary group. This is typically nobody or apache.
6. MODIFY SYSTEM-WIDE xml-template.conf
----------------------------------------
XML::Template uses XML cofiguration files that define the hosts that will
be using XML::Template, the available data sources, subroutines,
namespaces, and mappings between data sources and namespaces. There is a
system-wide configuration file in the XML::Template installation directory
(by default /usr/local/xml-template/xml-template.conf) that is first
loaded for every host. This configuration contains host entries and
resource entries common to all hosts. You should add a host entry for
any hosts that will be using XML::Template. For instance,
/home/xml-template
.localdomain
The basedir element tells XML::Template where the XHTML files for that
host are located and where that host's XML::Template XML configuration
file is located.
7. SET UP HOST DIRECTORY
-------------------------
For each host that will be using XML::Template, create a directory, for
instance, /home/xml-template. This is the directory in the basedir
element of the host entry in the system-wide XML::Template configuration
file.
Copy the sample host XML::Template configuration file from the
installation directory. For instance,
cp /usr/local/xml-template/xml-template_host.conf /home/xml-template/xml-template.conf
The contents of the host-specific configuration file will be appended to
the contents of the system-wide configuration file whenever an
XML::Template page is displayed. Typically, the system-wide configuration
will contain host, subroutine, and namespace entries and the host-specific
configuration will contain source and source-mapping entries.
8. SET UP DATABASE
-------------------
If you will be using the database related namespaces, you must first
create a (MySQL) database. For instance, suppose you wished to create a
database named xml-template:
mysqladmin -u root -p create xml-template
Next create a MySQL database user for this database. Enter the MySQL
shell:
mysql -u root -p mysql
Type the following MySQL commands:
grant all privileges on `xml-template`.* to `xml-template`@localhost identified by "password";
grant all privileges on `xml-template`.* to `xml-template`@'%' identified by "password";
flush privileges;
quit;
Replace password with the actual password for the database user.
Finally, create the database tables. Sample database table creation
commands are provided in /usr/local/xml-template/xml-template.sql.
mysql -u root -p < /usr/local/xml-template/xml-template.sql
Use the password for the MySQL database user you just created.
Next, create a password file in the host's base directory (the directory
in the basedir element of the host entry in the system-wide XML::Template
configuration file). This file should be names dbname.pwd, where dbname
is the actual name of the database you just created. In the current
example, the database password file would be
/home/xml-template/xml-template.sql. The first and only line in the file
should be the password for the database user you created.
Finally, modify the host-specific XML::Template configuration file in the
host's base directory. You will need to modify or add a source entry
under the sources element. You will also need to add or modify the source
mapping entries to use the source you just added.
9. SET UP THE WEB SERVER
-------------------------
If you will be using XML::Template to display web pages, you need to set
up your web server so it knows how to display XHTML files. Add a virtual
host entry:
ServerName hostname.domain
ServerAdmin root@hostname.domain
DocumentRoot /home/xml-template
Options FollowSymLinks ExecCGI Includes
AllowOverride None
Order allow,deny
Allow from all
AddHandler cgi-script .pl
AddHandler xhtml-handler .xhtml
Action xhtml-handler /xml-template.pl
where ipaddress is the actual IP address for the host. Replace
hostname.domain with the actual domain name of the host. You will
probably wish to change some of the above values.
The Action provides a handler script to run when any .xhtml files are
encountered. The above example tells Apache to run the script
xml-template.pl in the host's base directory (document root directory).
A sample handler script, /usr/local/xml-template/xml-template.pl, is
provided with XML::Template. You may need to modify this to suit your
application's specific needs. Then copy it into the host's base
directory.