view release on metacpan or  search on metacpan

lib/Titanium.pm  view on Meta::CPAN

  # In "WebApp.pm"...
  package WebApp;
  use base 'Titanium';

  sub setup {
	my $c = shift;

	$c->start_mode('form_display');
	$c->run_modes([qw/
        form_display
        form_process
	/]);
  }
  sub form_display { 
        my $c = shift;
        my $errs = shift;

        my $t = $c->load_tmpl;
        $t->param($errs) if $errs;
        return $t->output;
  }
  sub form_process {
       my $c = shift;

       # Validate the form against a profile. If it fails validation, re-display
       # the form for the user with their data pre-filled and the errors highlighted. 
       my ($results, $err_page) = $c->check_rm('form_display','_form_profile');
       return $err_page if $err_page; 

       return $c->forward('form_success');   
  }

  # Return a Data::FormValidator profile
  sub _form_profile {
    my $c = shift;
    return {
        required => 'email',
    };
  }

  sub form_success { ... } 

  1;

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

Inside the run modes, the following methods are available:

    $c->query;                               # A query object. CGI.pm by default.
    $c->redirect('http://othersite.com');    # Basic redirection
    $c->dbh;                                 # DBI database handle
    $c->session();                           # A CGI::Session object
    $c->check_rm;                            # Form validation with Data::FormValidator
    $c->cfg('root_uri');                     # Config file access (YAML, Perl or INI formats)
    $c->fill_form;                           # Form filling with HTML::FillInForm
    $c->error( title => '..', msg => '..' ); # Easy error page generation
    $c->stream_file($file);                  # file streaming
    $c->log;                                 # A Log::Dispatch object

=head2 Development and Testing

Easily setup the project skeleton using the bundled L<cgiapp-starter> script. 

In development you can turn on a debugging screen and a developer pop-up to quickly catch
code, html and performance issues, thanks to L<CGI::Application::Plugin::DebugScreen|CGI::Application::Plugin::DebugScreen> and 
L<CGI::Application::Plugin::DevPopup|CGI::Application::Plugin::DevPopup>.  

For automated testing, L<Test::WWW::Mechanize::CGIApp|Test::WWW::Mechanize::CGIApp> is bundled, allowing you
to functionally test your web application without involving a full web server. 
If you'd rather test against full web server, L<Test::WWW::Mechanize|Test::WWW::Mechanize> is there, too.  

=head2 Dispatching with Clean URIs

Modern web frameworks dispense with cruft in URIs. Instead of: 

 /cgi-bin/item.cgi?rm=view&id=15

A clean URI to describe the same resource might be:

 /item/15/view

The process of mapping these URIs to run modes is called dispatching and is
handled by L<CGI::Application::Dispatch|CGI::Application::Dispatch>. It comes
with a default dispatch table that automatically creates URLs in this pattern
for you:

 /app/module_name/run_mode

There's plenty of flexibility to design your own URIs if you'd like. 

=head1 Elements of Titanium

* B<Titanium is solid and mature>. While it has a new name, the reality is that
Titanium is simply a more user-friendly packaging of the mature
CGI::Application framework and some useful plugins. These packages have already
been refined and vetted.  The seed framework was first released in 2000 and by
2005 was mature.  Titanium contains no real code of its own, and there is no
intention to do so in the future. Instead, we may select other mature plugins
to include in the future.  Other "Titanium alloys" in the "Titanium::Alloy::"
name space may also come to exist, following the same philosophy, but choosing
to bundle a different combination of plugins. 

* B<Titanium is lightweight>. Titanium has a very light core and the plugins it
uses employ lazy-loading whenever possible. That means that while we have
built-in database plugin, we don't have to load DBI or make a database
connection until you actually use the database connection. Titanium runs well
in a plain CGI environment and provides excellent performance in a persistent
environment such as FastCGI or mod_perl. Titanium apps are compatible with the
dozens of published plugins for L<CGI::Application|CGI::Application>, so you
can add additional features as your needs evolve. 

=head1 DESCRIPTION

It is intended that your Application Module will be implemented as a sub-class
of Titanium. This is done simply as follows:

    package My::App;