# info > CGI::Application

---
type: CommandReference
command: CGI::Application
mode: man
section: 3pm
source: man-pages
---

## Quick Reference

- `use base 'CGI::Application';` — subclass CGI::Application
- `sub setup { ... }` — define configuration
- `$self->start_mode('mode1');` — set default run mode
- `$self->run_modes({ 'mode1' => 'sub1', ... });` — define dispatch table
- `my $app = WebApp->new(); $app->run();` — instantiate and run
- `WebApp->psgi_app();` — create PSGI coderef
- `$self->load_tmpl('template.html');` — load HTML::Template object
- `$self->param('key', 'val');` — set/get application parameters

## Name

**CGI::Application** - Framework for building reusable web-applications

## Synopsis

perl
# WebApp.pm
package WebApp;
use base 'CGI::Application';

sub setup {
    my $self = shift;
    $self->start_mode('mode1');
    $self->mode_param('rm');
    $self->run_modes(
        'mode1' => 'do_stuff',
        'mode2' => 'do_more_stuff',
    );
}
sub do_stuff { ... }
sub do_more_stuff { ... }
1;

# webapp.cgi
use WebApp;
my $webapp = WebApp->new();
$webapp->run();

# webapp.psgi (PSGI)
use WebApp;
WebApp->psgi_app();
## Options (Methods)

### Constructor

- `WebApp->new( TMPL_PATH => 'path', QUERY => $q, PARAMS => { ... } )` — create new application instance. `TMPL_PATH` sets template directory, `QUERY` allows custom CGI query object, `PARAMS` sets custom parameters.

### Configuration Methods (typically called in `setup()`)

- `$self->start_mode('mode_name')` — set the default run mode (default: 'start')
- `$self->run_modes(\%hash)` or `$self->run_modes(\@array)` — define dispatch table. Keys are mode names, values are subroutine names or references.
- `$self->mode_param('param_name')` or `$self->mode_param(\&coderef)` or `$self->mode_param( path_info => 1 )` — set how the run mode is determined. Default CGI param is 'rm'.
- `$self->error_mode('mode_name')` — set a run mode to call on fatal errors.
- `$self->tmpl_path('path')` or `$self->tmpl_path( [ 'path1', 'path2' ] )` — set template directory path(s).
- `$self->html_tmpl_class('HTML::Template::Dumper')` — specify alternative template class.

### Essential Methods

- `$self->param('key')` — get parameter value.
- `$self->param('key', 'value')` — set parameter.
- `$self->param()` — return list of all parameter names.
- `$self->query()` — return the CGI query object.
- `$self->load_tmpl('file.html')` — load and return an `HTML::Template` object. Can also pass a scalar reference or filehandle.
- `$self->header_props( -type => 'text/html', -expires => '+3d' )` — set HTTP headers.
- `$self->header_add( -cookie => $extra_cookie )` — add additional headers.
- `$self->header_type('redirect')` or `'none'` — set header type.
- `$self->prerun_mode('new_mode')` — change run mode during `cgiapp_prerun`.
- `$self->get_current_runmode()` — return current run mode name.
- `$self->delete('param_name')` — delete a parameter.

### Hooks (optional overriding)

- `sub cgiapp_init { ... }` — called before `setup()`, receives `new()` arguments.
- `sub cgiapp_prerun { ... }` — called before run mode, can change mode via `prerun_mode`.
- `sub cgiapp_postrun { ... }` — called after run mode, receives output reference for modification.
- `sub teardown { ... }` — called after run, for cleanup.
- `sub cgiapp_get_query { ... }` — override to provide custom query object.

### PSGI Methods

- `WebApp->psgi_app( \%args )` — returns a PSGI coderef.
- `$app->run_as_psgi()` — returns PSGI response arrayref `[ status, headers, body ]`.

## Examples

### Basic Application Module

perl
package WidgetView;
use base 'CGI::Application';
use strict;

sub setup {
    my $self = shift;
    $self->start_mode('mode1');
    $self->run_modes(
        'mode1' => 'showform',
        'mode2' => 'showlist',
        'mode3' => 'showdetail',
    );
    $self->dbh_config();  # via CGI::Application::Plugin::DBH
}

sub showform {
    my $self = shift;
    my $q = $self->query();
    my $output = $q->start_html(-title => 'Widget Search Form');
    $output .= $q->start_form();
    $output .= $q->textfield(-name => 'widgetcode');
    $output .= $q->hidden(-name => 'rm', -value => 'mode2');
    $output .= $q->submit();
    $output .= $q->end_form();
    $output .= $q->end_html();
    return $output;
}
# ... other run modes
1;
### Instance Script

perl
#!/usr/bin/perl -w
use WidgetView;
my $webapp = WidgetView->new();
$webapp->run();
### PSGI Application

perl
use WebApp;
my $handler = sub {
    my $env = shift;
    my $webapp = WebApp->new({ QUERY => CGI::PSGI->new($env) });
    $webapp->run_as_psgi;
};
## See Also

- [CGI](https://metacpan.org/pod/CGI)
- [HTML::Template](https://metacpan.org/pod/HTML::Template)
- [CGI::Application::Framework](https://metacpan.org/pod/CGI::Application::Framework)
- [CGI::Application::Plugin::DBH](https://metacpan.org/pod/CGI::Application::Plugin::DBH)
- [CGI::Application::Plugin::Session](https://metacpan.org/pod/CGI::Application::Plugin::Session)
- [CGI::Application::Plugin::Redirect](https://metacpan.org/pod/CGI::Application::Plugin::Redirect)
- [CGI::Application::Plugin::ConfigAuto](https://metacpan.org/pod/CGI::Application::Plugin::ConfigAuto)
- [CGI::Application::Plugin::ValidateRM](https://metacpan.org/pod/CGI::Application::Plugin::ValidateRM)
- [CGI::Application::Plugin::TT](https://metacpan.org/pod/CGI::Application::Plugin::TT)
- [CGI::Application::Dispatch](https://metacpan.org/pod/CGI::Application::Dispatch)
- [CGI::PSGI](https://metacpan.org/pod/CGI::PSGI)

## Exit Codes

Not documented.