Web Application

From TheSeed
Jump to: navigation, search

The Web Application is a framework to support fast, comprehesible and componentalized creation of applications on the web.

Overview

The Web Application framework will take care of the structure of your application in the web. Main features include:

  • menus
  • user authentication
  • page/action management
  • WebComponents

The following tutorial will describe how to set up your own application in the web using the WebApplication framework.

Setup

There are two modules required for the Web Application framework:

  • WebApplication
  • PPO

both must be checked out from the CVS. The following assumes you have set up a sandbox for your application. If you do not know how to set up a sandbox have bob do it ;) or go to Sandbox Setup.

cd ~/public_html/my-app/dist/releases/current/
cvs co WebApplication
cvs co PPO

Now create a directory for your application.

mkdir MyApp
cd MyApp

Now we fill in the neccessary elements that customize your application. You need to create the following things:

  • a cgi-script that becomes the centerpoint for your application
  • a directory called WebPage that will contain your different pages
  • an initial page for your application to display
  • a template file that describes the layout of your pages (optional)
  • a stylesheet that takes care of font-styles and the like (optional)
  • a directory for the images you want on your pages (optional)

To get things going, perform the following steps:

cp ../WebApplication/example/example.cgi myApp.cgi
cp ../WebApplication/example/Example.Makefile Makefile
mkdir WebPage
cp ../WebApplication/example/Example.pm WebPage/MyFirstPage.pm
cp ../WebApplication/WebLayoutDefault.tmpl MyAppLayout.tmpl
mkdir images
cd images
cp ../../WebApplication/images/* .

As you can see, there are example files for all of these that you can modify. At this point, your application is already up and running. Do a make and examine the result in the web:

http://bioseed.mcs.anl.gov/~juser/my-app/www/FIG/myApp.cgi

File:MyFirstApp.png

The WebApplication comes with a default stylesheet (css) that defines colours and fonts and so on. It's likely that you want change those at some point. To do so:

 go back to your working application directory: cd MyApp
 mkdir css
 cp ../WebApplication/css/default.css css/myapp.css

Now edit your myApp.cgi and replace the css filename in the following line:

 $layout->add_css(TMPL_PATH.'/myapp.css');

Your First Page

This is the demo page you have copied from the WepApplication directory. All it will do is print a page that reads 'Hello World'. When you go to the url of your application's script, this is the first page that will appear. This is because in the Web Application Script it is defined as the default first page.

package MyApp::WebPage::MyFirstPage;

use strict;
use warnings;

use base qw( WebPage );

1;

sub output {
  my ($self) = @_;

  my $content = "<h1>Hello World</h1>";

  return $content;
}

The logic of the Web Application will perform the following checks to see which page should be displayed:

  • was the cgi parameter page passed?
    • Yes: check if the page $cgi->param('page') requires any rights to be displayed
      • if there are no rights required, display the page
      • if there are rights required and there is no user, display the login page. After the login page has been processed, recheck to display this page.
      • if there are rights required and the user does not possess them, display an error
      • if there are rights required and the user does possess them, display the page
    • No: display the default first page
      • perform same authorization steps

Creating a new Page

If you wish to create a new page, simply create a new file in the WebPage directory of your application. You can copy the example file from the WebApplication directory as a template.

cd ~/public_html/myApp/dist/releases/current/myApp/WebPage/
cp ../WebApplication/Example.pm MyNewPage.pm

The name of the file, will be the value of the cgi page parameter which will display your page.

http://bioseed.mcs.anl.gov/~juser/myApp/www/FIG/myApp.cgi?page=MyNewPage

Would point to your new page.

Page Methods

When inside the your page module, you can access the inherited WebPage methods using

$self->method(params);

The following methods are available.

  • title (string)

Sets the title information for this page. This will be displayed in the title bar of your browser.

  • application

Returns the application object.

  • name

Returns the name of the current page.

  • url

Returns the url to the current page.

  • start_form (string, hashref)

Returns an opening html form tag. The string passed will be the html id of the form (optional). The hash reference is used to preserve the current state. The keys will be inserted as hidden fields with their values set to the values of the according hash entry.

  • end_form

Returns a closing html form tag.

The following are abstract functions which you can implement in your page.

  • init

This should include all functionality which must be called prior to calling the output method of the page. Component registration using

$self->application->register_component('ComponentType', 'ComponentID');

is an example of this.

  • require_javascript

This must return an array reference. Each element in the array must be the filename of a java script file. This file will automatically be included in the header of the page. If this method is not implemented, no extra java script will be included for this page.

  • require_css

This must return a string which must be the filename of the stylesheet file to be included for this page. If this method is not implementd, no extra stylesheet will be included for this page.

  • required_rights

This must return an arrayref of arrayrefs. Each element in the array must be a rights tuple. These are explained in the Using Rights section. If this method is not implemented, no rights will be required to see this page.

Application Methods

Since every page you create inherits from WebPage, you can access the application object using

my $application = $self->application;

The application object then offers the following functions

  • session

This will return the session object. The session object then allows access to the following functions

  • user
Returns the user object
  • get_entry
Returns the name and parameters of the page last visited.
  • cgi

Returns the cgi object

  • error

Sets the applications error message. This will cause an error page to be displayed. No other content will be seen on the page. If you wish to display the normal content of the page and in addition some note to the user, you can use the add_message method.

  • add_message

Adds a note or a warning to the page. This method takes two arguments, the first one can be either 'warning' or 'info', depending on which type of message you wish to add. The second parameter is the actual message.

  • page

Returns the current page object.

  • url

Returns the script url

  • redirect

Causes the url passed to be loaded instead of the current one.

  • register_component

Registers a component at the application. This component can be retrieved via the component' method.

  • component

Retrieves a previously requested component object.

  • register_action

Registers an action for this page with the application. If an unregistered action is called, an error will occur.

The following functions are usually only used in the Web Application Script of your application.

  • default

Sets the default first page to load if no cgi page parameter is given.

  • dbmaster

Sets the database master which will be used to crud user and session information.

  • layout

Sets the WebLayout used to build the application pages.

Menus

  • menu

Returns the menu object. The menu object then allows access to the following functions

  • add_category (category, url, target, right, sort_order)
  • delete_category (category)
  • get_categories
  • add_entry (category, entry, url, target)

Using Rights

The WebApplication also offers you the ability of Rights Management. This topic is described in detail at the WebApplication Rights page.

Web Components

The ability to include standard components into your application is one of the main features of the Web Application framework. This will give you a short introduction on how to use these components. A comprehesive list with detailed feature descriptions of currently available components is available on the Web Components page.

There are two methods of the application object that refer to components.

$application->register_component('ComponentName', 'ComponentID');
my $component = $application->component('ComponentID');

The first one registers a component for your page. This means an actual instance of the component type you request is created and stored in the application. This instance can now be accessed by the second method by passing the ID you chose for this component instance. The registration of a component must be done in a pages init method. After retrieving the requested component from the application object, you can then access its methods. Typically, components have getter/setter functions to set their parameters and an output method to return html content you can print onto your page.

The following code is using the Login component as an example.

sub init {
  my $self = shift;

  $self->application->register_component('Login', 'MyLogin');
}

sub output {
  my ($self) = @_;

  my $content = "";

  my $application = $self->application;
  my $cgi = $application->cgi;

  my $login_component = $application->component('MyLogin');
  $login_component->small_login(1);
  my $login = $login_component->output;

  $content .= "<h1>Hello World</h1>" . $login;

  return $content;
}

Advanced Customizing

If you are merely designing an manipulating pages, there is no need for you to ever look at any files outside the WebPage directory of you application. If you are setting up the application however, you need to check the Web Application Template and the Web Application Script. There are also Stylesheets that you can modify and you probably wish to exchange some images, like the logo.