view release on metacpan or  search on metacpan

t/pms/RayApp.pm  view on Meta::CPAN

markup, the Web applications only process and return Perl data.
No markup handling is done in the code of individual applications,
thus application code can focus on the business logic. This reduces
the presentation noise in individual applications, increases
maintainability and speeds development.

The data returned by the application is then serialized to XML and
can be postprocessed by XSLT to desired output format, which may be
HTML, XHTML, WML or anything else. In order to provide all parties
involved (analysts, application programmers, Web designers, ...) with
a common specification of the data format, data structure description
(DSD) file is a mandatory part of the applications. The DSD describes
what parameters the application expects and what data it will return,
therefore, what XML will come out of that data. The data returned
by the application in a form of hash by the Perl code is fitted into
the data structure, creating XML file with agreed-on elements.

This way, application programmers know what data is expected from
their applications and Web designers know what XMLs the
prostprocessing stage will be dealing with, in advance. In addition,
application code can be tested separately from the presentation part,
and tests for both application and presentation part can be written
independently, in parallel. Of course, this also works if you are the
sole person on the project, playing the above mentioned roles.

The system will never produce unexpected data output, since the data
output is based on DSD which is known.

=head1 CONFIGURATION

Most of the use of RayApp is expected in the Web context. This
section summarizes configuration steps needed for the Apache HTTP
server. This version of RayApp works with Apache 2.0
and mod_perl 2.0.

Assume you have a Web application that should reside on URL

	http://server/sub/app.html

The application consists of three files:

	/opt/www/app.dsd
	/opt/www/app.pl
	/opt/www/app.xsl

Yes, instead of sticking application code and presentation into one
file, we separate them completely.

Whenever a request for /sub/app.html comes, the DSD
/opt/www/app.dsd is loaded, app.pl (or app.mpl) executed and its
output serialized to HTML using app.xsl. For syntax of app.dsd, see
B<RayApp::DSD>. In the app.pl script, there has to be at least one
function, called B<handler>, and this function should return Perl hash
with data matching the DSD. The whole content of the .pl is evaluated
in a B<package> context in a B<Apache::Registry> manner, so two
B<handler> methods from different applications do not clash. In
app.xsl, there should be an XSLT stylesheet.

If you issue a request for /sub/app.xml, the presentation
postprocessing is skipped and you get the XML output -- ideal for
debugging.

If the app.html file exists in the filesystem, it "overrides" any
attempts to is generate dynamic content, and the file is returned.
Likewise, if there is a app.xml file in the filesystem and there is
a request for app.xml, the XML file is returned. If there is app.xml
but no app.html and a request for app.html comes, the app.xml is
serialized using app.xsl. So B<RayApp> can be used not only for fully
dynamic sites, but also as a XSLT processor.

You will need to configure Apache for B<RayApp> to do its job. It
can operate both in the mod_perl and in pure CGI way.

=head2 Pure mod_perl approach

If you have a mod_perl 2 support in your Apache 2 and want to use
it to run you B<RayApp>-based applications, the following setup
will give you the correct result:

	Alias /sub /opt/www
	<LocationMatch ^/sub/(.+\.(html|xml))?$/>
		SetHandler perl-script
		PerlResponseHandler RayApp::mod_perl
	</LocationMatch>

The Alias directive ensures that the DSD and Perl code will be
correctly found in the /opt/www/ directory, for requests coming to
/sub/ Location.

Instead of perl-script, you can also use C<SetHandler modperl>.

=head2 CGI approach

In the B<RayApp> distribution, there is a script
B<rayapp_cgi_wrapper>. Assuming it was installed in the B</usr/bin>
directory, the configuration is

	ScriptAliasMatch ^/sub/(.+(\.(html|xml))?)?$ /usr/bin/rayapp_cgi_wrapper/$1
	<Location /sub>
		SetEnv RAYAPP_DIRECTORY /opt/www
	</Location>

With the B<ScriptAliasMatch> directive in effect, the request will
be processed by B<usr/bin/rayapp_cgi_wrapper>, and the
C<SetEnv RAYAPP_DIRECTORY> tells B<RayApp> where on the filesystem
should it find the necessary files of the application (the same
as B<Alias> with mod_perl setup).
Here we partly simulate the work that Apache would have done for us
in the static files case.

Both B<LocationMatch> in mod_perl case and B<Location> in CGI case can
of course contain additional configuration options for Apache,
like B<Order> / B<Allow>, and configuration of B<RayApp>, described
in the next section.

=head2 More detailed setup

For mod_perl, the configuration is done using B<PerlSetVar> and the
variable name in in mixed capitals. For CGI, enviroment variables are
used, set using B<SetEnv> and the variable name is in all capitals,
words separated by underscores. For example, for mod_perl the directive