/ 
OpenFrame-2.02
River stage one • 1 direct dependent • 1 total dependent
/ AppWrite

NAME

AppWrite - OpenFrame Application Writers Guide

OVERVIEW

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.

BASICS

  package OpenFrame::MyApplication;

  use strict;
  use warnings::register;
	
  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.

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 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, dispatch tells the system where this application runs. The 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.

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 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.