view release on metacpan or  search on metacpan

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

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
would be

	PerlSetVar RayAppDirectoryIndex index.html

and for CGI, it would read

	SetEnv RAYAPP_DIRECTORY_INDEX index.html

Supported options:

=over 4

=item RayAppDirectoryIndex / RAYAPP_DIRECTORY_INDEX

Similar to Apache's B<DirectoryIndex> directive, this will be used
for requests ending with a slash, or generaly requests resulting
into requests for directories. As B<RayApp>'s output is dynamically
generated, pure B<DirectoryIndex> cannot be used.

If not set, nothing will be served for directory requests.

=item RayAppInputModule / RAYAPP_INPUT_MODULE

As already noted, B<RayApp> runs the B<handler> function found
in the application file (app.pl). Often applications share the same
context -- all of them want to be passed an open B<$dbh> database
handler (instead of doing their own DBI->connect), all of them want to
be passed the request object to query the input parameters.

The option B<RayAppInputModule> specifies a module name which will
be loaded and from which a B<handler> function will be called for
every request. The function should return a list of values that
will be passed in as parameters to the application B<handler>.

The first parameter passed to this input module B<handler> is the
B<RayApp::DSD> object, for mod_perl the second argument is the request
(B<Apache2::RequestRec>) object. An example of an input module might
be

	package Application::Input;

	use RayApp::Request ();
	use DBI ();
	sub handler {
		my ($dsd, $r) = @_;
		if (defined $dsd) {
			$dsd->validate_parameters($q)
				or die $dsd->errstr;
		}
		my $dbh = DBI->connect('dbi:Oracle:prod',
			'scott', 'tiger',
			{ RaiseError => 1, AutoCommit => 0 });
		my $q = new RayApp::Request($r);
		return ($dbh, $q);
	}
	1;

Here we first validate parameters against DSD (you can optionally
die or just log an error, depending on how strict you want to be),
we connect to the database, so that the applications get connection
to their database backend, and we use B<RayApp::Request> to get
uniform (for mod_perl and CGI) query object. The values B<$dbh> and
B<$q> are returned and will be passed as argument to the application
B<handler>.

=item RayAppStyleParamModule / RAYAPP_STYLE_PARAM_MODULE

There are often additional data except the core data of the
application that you might like to process in your XSLT
stylesheets -- id of the authenticated user, the full and
relative URLs of the currently running application, some sticky
preferences of the user. They are more related to the presentation
than to the business logic of the application, so you do not want to
have them in your DSD and have all your applications generate them and
return them.

The option B<RayAppStyleParamModule> specifies a module name from
which a B<handler> function will be called for every request that goes
to the postprocessing stage. It will be passed the DSD object and the
same arguments as the application B<handler> (those returned by
B<RayAppInputModule>) and it should return a list of key => value
pairs that will be passed to the stylesheet.

A simple style parameter module might look like this:

	package Application::Style_params;
	sub handler {
		my ($dsd, $dbh, $q) = @_;
		return (
			my_full_url => $q->url( -full => 1 ),
			my_relative_url => $q->url( -relative => 1 ),
			dbuser => $dbh->{'Username'},
                );
	}
	1;

and in the XSLT you will get to them for example via

	<xsl:value-of select="$my_relative_url"/>

=item RayAppStyleStaticParams / RAYAPP_STYLE_STATIC_PARAMS

When a static .xml file is processed into HTML, the XSL
transformation is run, even if there was no application invocation
in the process. Normally, the B<handler> of module specified by
B<RayAppInputModule> would not be run in this case. If you want the
module to be run even in this case (thus generating input argument for
the B<RayAppStyleParamModule> module), set this option to true.

=head2 The applications

Having the Web server set up, you can write your first application
in B<RayApp> manner. For start, a simplistic application which only
returns two values will be enough.

First the DSD file, /opt/www/app.dsd:

	<?xml version="1.0"?>