NAME

Squatting::Controller - default controller class for Squatting

SYNOPSIS

  package App::Controllers;
  use Squatting ':controllers';
  our @C = (
    C(
      Thread => [ '/forum/(\d+)/thread/(\d+)-(\w+)' ],
      get => sub {
        my ($self, $forum_id, $thread_id, $slug) = @_;
        #
        # get thread from database...
        #
        $self->render('thread');
      },
      post => sub {
        my ($self, $forum_id, $thread_id, $slug) = @_;
        # 
        # add post to thread
        #
        $self->redirect(R('Thread', $forum_id, $thread_id, $slug));
      }
    )
  );

DESCRIPTION

Squatting::Controller is the default controller class for Squatting applications. Its job is to take HTTP requests and construct an appropriate response by setting up output headers and returning content.

API

Object Construction

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

The constructor takes a name, an arrayref or URL patterns, and a hash of method definitions. There is a helper function called C() that makes this slightly less verbose.

$self->clone([ %opts ])

This will create a shallow copy of the controller. You may optionally pass in a hash of options that will be merged into the new clone.

HTTP Request Handlers

$self->get(@args)

$self->post(@args)

$self->put(@args)

$self->delete(@args)

$self->head(@args)

$self->options(@args)

$self->trace(@args)

$self->connect(@args)

These methods are called when their respective HTTP requests are sent to the controller. @args is the list of regex captures from the URL pattern in $self->urls that matched $self->env->{REQUEST_PATH}.

Attribute Accessors

The following methods are lvalue subroutines that contain information relevant to the current controller and current request/response cycle.

$self->name

This returns the name of the controller.

$self->urls

This returns the arrayref of URL patterns that the controller responds to.

$self->cr

This returns the Continuity::Request object for the current session.

$self->env

This returns a hashref populated with a CGI-like environment. This is where you'll find the incoming HTTP headers.

$self->input

This returns a hashref containing the incoming CGI parameters.

Example: Interpreting the query ?x=5&y=true&z=2&z=1&z=3 .

  $self->input->{x} is         5
  $self->input->{y} is    "true"
  $self->input->{z} is [2, 1, 3]

@keys = $self->param

$value = $self->param($key)

$self->param($key, $value)

This is an accessor for "$self->input" that provides an API that's a subset of the CGI module's "param()" function. It exists, because there are many perl modules that can make use of an object that follows this API. It is not complete, but it should be good enough for WWW::Facebook::API::Canvas and many other modules.

$self->cookies

This returns a hashref that holds both the incoming and outgoing cookies.

Incoming cookies are just simple scalar values, whereas outgoing cookies are hashrefs that can be passed to CGI::Cookie to construct a cookie string.

Example: Setting a cookie named 'foo'

  $self->cookies->{foo} = { -Value => 'bar', -Expires => '+1d' };

Example: Getting the value of a cookie named 'baz'

  my $baz = $self->cookies->{baz};

$self->state

If you've setup sessions, this method will return the current session data as a hashref.

$self->v

This returns a hashref that represents the outgoing variables for this request. This hashref will be passed to a view's templates when render() is called.

$self->status

This returns an integer representing the outgoing HTTP status code. See HTTP::Status for more details.

  $self->status = 404;  # Resource Not Found

$self->headers

This returns a hashref representing the outgoing HTTP headers.

Example: Setting the outgoing Content-Type to text/plain

  $self->headers->{'Content-Type'} = 'text/plain';

$self->log

This returns a logging object if one has been set up for your app. If it exists, you should be able to call methods like "debug()", "info()", "warn()", "error()", and "fatal()" against it, and the output of this would typically end up in an error log.

$self->view

This returns the name of the default view for the current request. If it's undefined, the first view in @App::Views::V will be considered the default.

$self->app

This returns the name of the app that this controller belongs to.

Output

$self->render($template, [ $view ])

This method will return a string generated by the specified template and view. If a view is not specified, the first view object in @App::Views::V will be used.

$self->redirect($path, [ $status ])

This method is a shortcut for setting $self->status to 302 and $self->headers->{Location} to the specified URL. You may optionally pass in a different status code as the second parameter.