NAME

Squatting - A Camping-inspired Web Microframework for Perl

SYNOPSIS

Running an App:

  $ squatting App
  Please contact me at: http://localhost:4234/

Check out our ASCII art logo:

  $ squatting --logo

What a basic App looks like:

  # STEP 1 => Use Squatting for your App
  {
    package App;  # <-- I hope it's obvious that this name can whatever you want.
    use Squatting;
    our %CONFIG;  # <-- standard app config goes here
  }

  # STEP 2 => Define the App's Controllers
  {
    package App::Controllers;

    # Setup a list of controller objects in @C using the C() function.
    our @C = (
      C(
        Home => [ '/' ],
        get  => sub {
          my ($self) = @_;
          my $v = $self->v;
          $v->{title}   = 'A Simple Squatting Application';
          $v->{message} = 'Hello, World!';
          $self->render('home');
        },
        post => sub { }
      ),
    );
  }

  # STEP 3 => Define the App's Views
  {
    package App::Views;

    # Setup a list of view objects in @V using the V() function.
    our @V = (
      V(
        'html',
        layout  => sub {
          my ($self, $v, $content) = @_;
          "<html><head><title>$v->{title}</title></head>".
          "<body>$content</body></html>";
        },
        home    => sub {
          my ($self, $v) = @_;
          "<h1>$v->{message}</h1>"
        },
      ),
    );
  }

  # Models?  
  # - The whole world is your model.  ;-)
  # - I have no interest in defining policy here.
  # - Use whatever works for you.

DESCRIPTION

Squatting is a web microframework based on Camping. It originally used Continuity as its foundation, but it has since been generalized such that it can squat on top of any Perl-based web framework (in theory).

What does this mean?

Concise API: _why did a really good job designing Camping's API so that you could get the MOST done with the LEAST amount of code possible. I loved Camping's API so much that I ported it to Perl.
Tiny Codebase: The core of Squatting (which includes Squatting, Squatting::Controller, and Squatting::View) can be squished into less than 4K of obfuscated perl. Also, the number of Perl module dependencies has been kept down to a minimum.
RESTful Controllers By Default: Controllers are objects (not classes) that are made to look like HTTP resources. Thus, they respond to methods like get(), post(), put(), and delete().
RESTless Controllers Are Possible: Stateful continuation-based code can be surprisingly useful (especially for COMET), so we try to make RESTless controllers easy to express as well. (*)
Squatting Apps Can Have Multiple Views: Views are also objects (not classes) whose methods represent templates to be rendered. An app can also have more than one view. Changing a Squatting app's look and feel can be as simple as swapping out one view object for another.
Squatting Apps Are Composable: You can take multiple Squatting apps and compose them into a single app. For example, suppose you built a site and decided that you'd like to add a forum. You could take a hypothetical forum app written in Squatting and just mount it at an arbitrary path like /forum.
Squatting Apps Are Embeddable: Already using another framework? No problem. You should be able to embed Squatting apps into apps written in anything from CGI on up to Catalyst. Squatting aims to be compatible with EVERYONE.
Minimal Policy: You may use any templating system you want, and you may use any ORM you want. We only have a few rules on how the controller code and the view code should be organized, but beyond that, you are free as you want to be.

* RESTless controllers currently only work when you're Squatting::On::Continuity.

API

Use as a Base Class for Squatting Applications

  package App;
  use Squatting;
  our %CONFIG = ();
  1;

Just "use"ing Squatting makes a lot of magic happen. In the example above:

App becomes a subclass of Squatting.
App::Controllers is given this app's R() and C() functions.
App::Views is given this app's R() and V() functions.

App->service($controller, @args)

Every time an HTTP request comes in, this method is called with a controller object and a list of arguments. The controller will then be invoked with the HTTP method that was requested (like GET or POST), and it will return the content of the response as a string.

NOTE: If you want to do anything before, after, or around an HTTP request, this is the method you should override in your subclass.

App->init

This method takes no parameters and initializes some internal variables.

NOTE: You can override this method if you want to do more things when the App is initialized.

App->mount($AnotherApp => $prefix)

XXX - The "mount()" has been moved out of the core and into Squatting::With::Mount. Furthermore, Squatting::With::Mount has been implemented using Squatting::On::Squatting.

This method will mount another Squatting app at the specified prefix.

  App->mount('My::Blog'   => '/my/ridiculous/rantings');
  App->mount('Forum'      => '/forum');
  App->mount('ChatterBox' => '/chat');

NOTE: You can only mount an app once. Don't try to mount it again at some other prefix, because it won't work. This is a consequence of storing so much information in package variables and a strong argument for going all objects all the time.

App->relocate($prefix)

This method will relocate a Squatting app to the specified prefix. It's useful for embedding a Squatting app into apps written in other frameworks.

This also has a side-effect of setting $CONFIG{relocated} to $prefix.

Use as a Helper for Controllers

In this package, you will define a list of Squatting::Controller objects in @C.

  package App::Controllers;
  use Squatting ':controllers';
  our @C = (
    C(...),
    C(...),
    C(...),
  );

C($name => \@urls, %methods)

This is a shortcut for:

  Squatting::Controller->new(
    $name => \@urls, 
    app   => $App, 
    %methods
  );

R($name, @args, [ \%params ])

R() is a URL generation function that takes a controller name and a list of arguments. You may also pass in a hashref representing CGI variables as the very last parameter to this function.

Example: Given the following controllers, R() would respond like this.

  # Example Controllers
  C(Home    => [ '/' ]);
  C(Profile => [ '/~(\w+)', '/~(\w+)\.(\w+)' ]);

  # Generated URLs
  R('Home')                             # "/"
  R('Home', { foo => 1, bar => 2})      # "/?foo=1&bar=2"
  R('Profile', 'larry')                 # "/~larry"
  R('Profile', 'larry', 'json')         # "/~larry.json"

As you can see, @args represents the regexp captures, and "\%params" represents the CGI query parameters.

Use as a Helper for Views

In this package, you will define a list of Squatting::View objects in @V.

  package App::Views;
  use Squatting ':views';
  our @V = (
    V(
      'html',
      home => sub { "<h1>Home</h1>" },
    ),
  );

V($name, %methods)

This is a shortcut for:

  Squatting::View->new($name, %methods);

R($name, @args, [ \%params ])

This is the same R() function that the controllers get access to. Please use it to generate URLs so that your apps may be composable and embeddable.

AUTHOR

John BEPPU <beppu@cpan.org>

Scott WALTERS (aka scrottie) gets credit for the name of this module.

COPYRIGHT

The "MIT" License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

NAME

SYNOPSIS

DESCRIPTION

What does this mean?

API

Use as a Base Class for Squatting Applications

Use as a Helper for Controllers

Use as a Helper for Views

SEE ALSO

Google Group: squatting-framework

Squatting Source Code

Bavl Source Code

Continuity and Coro

Camping

Prototype-based OO

AUTHOR

COPYRIGHT

The "MIT" License