NAME

Squatting::Cookbook - Web Development Techniques for Squatting

INTRODUCTION

Squatting exists because I fell in love with Camping's API, and I couldn't bear the thought of building another site using some other API. When I decided that the next site I wanted to build would be implemented in Perl, I had no choice but to port Camping to Perl, and that's how Squatting was born.

My hope is that other Perl programmers will be able to appreciate how concise this API is, and I hope they'll see just how far a little bit of code can go.

Anatomy of a Squatting Application

Subclass Squatting

  package App;
  use base 'Squatting';
  our %CONFIG = ();

Make a Package for Your Controllers

If your app is called App, then:

Your controllers must be defined in a package called App::Controllers.
You must say use Squatting ':controllers'.
You must put your controllers in a package variable named @C.

  package App::Controllers;
  use Squatting ':controllers';
  our @C = (
    C(
      Home => [ '/' ],
      get  => sub {
        my ($self) = @_;
        $self->render('home');
      }
    ),
    C(
      Profile => [ '/~(\w+)' ],
      get => sub {
        my ($self, $name) = @_;
        my $v = $self->v;
        $v->{name} = $name;
        $self->render('profile');
      }
    )
  );

Anatomy of a Controller

Make a Package for Your Views

If your app is called App, then:

Your views must be defined in a package called App::Views.
You must say use Squatting ':views'.
You must put your views in a package variable named @V.

  package App::Views;
  use Squatting ':views';
  our @V = (
    V(
      'html',
      layout => sub {
      },
      home => sub {
      },
      profile => sub {
      },
    )
  );

Anatomy of a View

PROGRAMMING TECHNIQUES

COMET

Event Architecture

RESTless Controllers

How to Set Up Sessions

Continuity and Process Memory

Pure Continuity apps typically don't use persistent session storage, because they can use lexically scoped variables instead. However, Squatting apps are RESTful and stateless by default, so you can't count on the lexical scope of a controller to stick around between requests. Luckily, package variables *will* stick around, so that's what we'll use to implement persistent sessions.

  our %state;
  sub service {
    my ($app, $c, @args) = @_;
    my $cr  = $c->cr;
    my $sid = $cr->{session_id};
    if (defined $sid) {
      $c->state = $state{$sid} ||= {};
    } 
    $app->next::method($c, @args);
  }

Here, we override service() in the main module of our app so that $c->state will provide a hashref whose values will persist between requests.

Note that instead of writing $app->SUPER::service, we have to write $app->next::method, because Squatting is a sublcass of Class::C3::Componentised.

Without Continuity

The challenge is to find a way to assign unique session ids to each visitor, and use that session id as a key into a persistent store.

How to Use Various Templating Systems With Squatting

HTML::AsSubs

Tenjin

Template::Toolkit

HTML::Mason

HTML::Template

How to Internationalize and Localize Squatting Apps

How to be an OpenID Consumer

How to be an OpenID Provider

How to Compose Multiple Squatting Apps Into One App

  App->mount('AnotherApp', '/prefix');

How to Embed a Squatting App Into Other Frameworks

In order to embed a Squatting app into an app written in another framework, we need to be able to do the following things.

get incoming CGI parameters
get incoming HTTP request headers
get incoming HTTP method
set outgoing HTTP status
set outgoing HTTP response headers
set outgoing content

If we can do all these things, Squatting can make itself at home. Here are some concrete examples to get you started.

Catalyst

To embed a Squatting app into a Catalyst app, you can add code like this to your Root controller.

  use App 'On::Catalyst';
  App->init;
  App->relocate('/somewhere');
  sub somewhere : Local { App->catalyze($_[1]) }

If you want the Squatting app to be completely in charge, you don't even have to relocate() -- just redefine the default() method like this:

  use App 'On::Catalyst';
  App->init;
  sub default : Private { App->catalyze($_[1]) }

HTML::Mason

Raw mod_perl1

Raw mod_perl2

CGI

DEPLOYMENT TECHNIQUES

Let Squatting+Continuity Own Port 80

This is the simplest thing you could possibly do, but it's also somewhat limiting.

Reverse Proxying to Squatting+Continuity w/ Perlbal

Reverse Proxying to Squatting+Continuity w/ nginx

Piggy-Backing on Top of Other Frameworks

If you've embedded a Squatting app into another application, the rules and conventions governing the other application's framework take precedence. Follow their deployment guidelines, and you should be fine.

SCALING TECHNIQUES

This section is for those who wish to scale Squatting apps that are using a Continuity foundation. If any part of your site is RESTless and stateful, and you've suddenly got a lot of traffic to your site, this section is for you.

CPAN RT