Web Application
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
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
- Yes: check if the page $cgi->param('page') requires any rights to be displayed
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.