NAME

OpenFrame::AppKit::App - The OpenFrame AppKit application class

SYNOPSIS

    package MyApplication;

    use strict;

    use OpenFrame::AppKit::App;
    use base qw ( OpenFrame::AppKit::App );

DESCRIPTION

The OpenFrame::AppKit::App class is designed to be inherited from. It provides all the basic functionality of a pipeline segment, as well as basic functionality that applications will need to start running.

To create an application, all you need to do to get started is subclass OpenFrame::AppKit::App.

    package MyApplication;

    use strict;

    use OpenFrame::AppKit::App;
    use base qw ( OpenFrame::AppKit::App );

In your server code you can now instantiate your application:

    my $app = MyApplication->new();

However, applications require a little more information to act in the manner we have come to expect. Applications in common web applications act when a url is requested that they listen to. Your new application is capable of that, but you need to tell it which URIs to match against. You do this by using the uri() method of that OpenFrame::AppKit::App helpfully provides. If for instance you wanted your application to execute whenever you went to '/myapp.html' URL then simply use the URI method to specify a regular expression to match:

    $app->uri( qr!/myapp\.html! );

OpenFrame::AppKit::App uses the concept of namespaces to keep your application's data seperate from other application's data in the global session. You can specify the namespace of your application by using the namespace() method, that once again, OpenFrame::AppKit::App provides:

    $app->namespace( 'myapplication' );

As you have probably noticed, the work needed to set up your applications initialization is performed through method calls to your application. All methods that have been demonstrated here are capable of being chained:

    my $app = MyApplication->new()
                           ->uri( qr!/myapp\.html! )
                           ->namespace( 'myapplication' );

All this is very useful, but so far the application still does nothing at all. This will change. OpenFrame::AppKit::App applications act by default as state machines. These states are specified by parameters sent to the OpenFrame server. In the case of an HTTP GET message you can see them on the end of a URL:

    http://some.server.com/test.cgi?name=value

In this case there is one parameter, name and one value value. The application's state machine looks at the parameters, your application acts on values. To set up your state machine you create a method in your application called entry_points(). This method should return a hash of arrays. In the hash, the keys represent methods in your module, and then elements in the array represent parameters that have to exist in order for your application to be run:

    sub entry_points {
        return {
                form_filled => [ 'name', 'age' ]
               };
    }

Each of the keys in your hash is an entry point, and needs a subroutine in your module to perform the work.

    sub form_filled {

    }

In the case that you want a method to be called even if there are no parameters matched, OpenFrame automatically calls a method called default() for you.

Whenever OpenFrame::AppKit calls an entry point in your application it calls it with two parameters. The first of the two parameters is the Application object itself. The second is the Pipeline store (but I'll talk about that in a little while, its not important right now). A method that your application will use nearly every time it is in an entry point is the request() method. It returns the OpenFrame::Request object that you can use to find out the exact uri that has been called as well as the paramaters and values supplied to it.

    sub form_filled {
        my $self  = shift;
        my $store = shift;

        my $request = $self->request();
        my $uri     = $request->uri();
        my $args    = $request->arguments();
    }

For more information about the request object and what it does, you can see the OpenFrame::Request documentation. For now we'll talk only about the $args variable, which is a hash reference. Lets assume that your application is up and running, and receiving requests. If you were to receive a request that was represented in URI form as:

    http://some.server.com/myapp.html?name=Bob&age=34

Then you could expect to find that your $args hash would look like:

    $args = {
             name => 'Bob',
             age  => 34
            }

    my $name = $args->{name};

The $name variable would hold the value Bob.

When you write an application any data that you want to provide to the template writer (which may be yourself) should be placed inside the $self object. $self is a hash, and provided you don't use the ::appkit key you can place whatever you'd like in there.

AUTHOR

James A. Duncan <jduncan@fotango.com>

COPYRIGHT

Copyright 2002 Fotango Ltd.

This code is released under the same terms as perl itself.

http://opensource.fotango.com/

cpanm OpenFrame::AppKit

perl -MCPAN -e shell
install OpenFrame::AppKit