=head1 NAME

AppWrite - OpenFrame Application Writers Guide

=head1 DESCRIPTION

OpenFrame's application system is designed to be as simple to use as
possible.  An application sits on top of a URI or multiple URI's, as
defined by the config file.  An application has a number of entry
points which correspond to required paramters on the URI.

This guide will give a basic overview of how to write an application
for OpenFrame.

=head1 BASICS

  package OpenFrame::MyApplication;

  use strict;
  use OpenFrame::Application;
  use base qw (OpenFrame::Application);

  1;

The above snippet of code is a fully working OpenFrame application.
It doesn't do much, but it does work.  First of all, we'll cover how
to install it.

=head1 INSTALLATION

Installing an application is pretty straight forward.  If you look at
your config file (installed in /etc/openframe.conf by the
configbuilder app) you should see something like this somewhere in it:

    installed_applications => @
        %
            dispatch => Local
            name => default
            namespace => OpenFrame::Application
            uri => /

To those of you familiar with Data::Denter, you'll immedietly
recognize it as YAML.  The above list has one application installed:
the default application that is used if everything breaks.  To add a
new application you need to insert I<on top of> this application.  So,
make it look like the following:

    installed_applications => @
        %
            dispatch => Local
            name => myapp
            namespace => OpenFrame::MyApplication
            uri => /myapp
        %
            dispatch => Local
            name => default
            namespace => OpenFrame::Application
            uri => /

Provided you've installed the OpenFrame::MyApplication module (as
written above) you're application will execute when a URI with /myapp
is called.

Line by line an application entry looks complicated, but it really
isn't.  The first line, C<dispatch> tells the system where this
application runs.  The C<name> entry explains to OpenFrame where you
want to store the application run-time in the session (more on this
later).  The namespace is the module name of the application, and the
uri is where you want this application to execute.

The application dispatch mechanism also creates an entry inside the session
hash at application.current with the keys name, namespace, and method.
These correspond to the various pieces of the application that have been
dispatched.

=head1 A MORE COMPLEX EXAMPLE

To add functionality to the application, we'll add an entry point.
Edit the MyApplication file again, and add the following code just
before the C<1;>.

  our $epoints = { example => [ 'param' ] };

  sub default {
    my $self = shift;
    $self->{message} = "no parameters for this call";
  }

  sub example {
    my $self = shift;
    $self->{message} = "parameters are passed";
  }

To explain what we have done here, is to explain the OpenFrame
application system.  Every application has a list of entry points.
Entry points define what is required to trigger certain states within
the application.  The requirements are parameters passed on the
command line.  For every entry point, there should be a subroutine
which defines what happens at that point.  Inside your templating
system, after this application gets executed, you should be able to do
something like the code below, and have it display the message in the
appropriate place.

  <html>
    <head>
     <title>My First Application</title>
    </head>
    <body>
      Message is: [% application.myapp.message %]
    </body>
  </html>

You'll notice that the templating system wants points to something
called 'application.myapp.message'.  The reason for this is pretty
simple.  The templating system is always provided with the users
session as parameters.  The application is stored persistantly in the
location given by the name field of the config file.  So if you point
your templating system at application.<name>.<field> it will get the
correct field of the correct application.

=cut
