NAME

CatalystX::Controller::Sugar - Sugar for Catalyst controller

VERSION

0.0702

DESCRIPTION

This module is written to simplify the way controllers are written. I personally think that shifting off $c and $self in every action is tidious. I also wanted a simpler API to created chained actions, since I rarely use any other actions - except of "private".

SYNOPSIS

  package MyApp::Controller::Root;
  use CatalystX::Controller::Sugar;
 
  __PACKAGE__->config->{'namespace'} = q();
 
  # Private action
  private authenticate => sub {
    c->user_exists and return 1;
  };
 
  # Chain /
  chain sub {
    report debug => 'Someone tries to access %s', c->action;
  };

  # Endpioint /*
  chain '' => sub {
    res->body('not found');
  };

  # Endpoint /login
  chain login => {
    get => sub {}, # show template
    post => sub {
      forward 'authenticate' and go '';
    },
  };
 
  # Chain /user/[id]/*
  chain user => ['id'], sub {
    stash user => c->model('DB::User')->find($_[0]);
  };
 
  # Endpoint /user/[id]/view/*
  chain 'user:1' => view => sub {
    res->body(
      sprintf 'Person is called: %s', stash->{'user'}->name
    );
  };
 

Same with standard Catalyst syntax

  package MyApp::Controller::Root;
  use Moose;
  BEGIN { extends 'Catalyst::Controller' }
 
  __PACKAGE__->config->{'namespace'} = q();
 
  # Private action
  sub authenticate :Private {
    my($self, $c) = @_;
    $c->user_exists and return 1;
  }
 
  # Chain /
  sub root :Chained("/") PathPart("") CaptureArgs(0) {
    my($self, $c) = @_;
    $c->log->debug(sprintf 'Someone tries to access %s', $c->action);
  }

  # Endpioint /*
  sub default :Chained("/root") PathPart("") Args {
    my($self, $c) = @_;
    $c->res->body('not found');
  }

  # Endpoint /login
  sub login :Chained("/root") PathPart Args {
    my($self, $c) = @_;

    if(lc $c->req->method eq 'get') {
      return; # show template
    }
    elsif(lc $c->req->method eq 'post') {
      $c->forward('authenticate') and go('');
    }
  }
 
  # Chain /user/[id]/*
  sub user :Chained("/root") PathPart CaptureArgs(1) {
    my($self, $c, $id) = @_;

    $c->stash->{'id'} = $id; # alternative to captured('id');
    $c->stash->{'user'} = $c->model('DB::User')->find($id);
  }
 
  # Endpoint /user/[id]/view/*
  sub user_view :Chained("/user") PathPart('view') Args {
    my($self, $c) = @_;
    $c->res->body(sprintf 'Person is called: %s', $c->stash->{'user'}->name);
  }
 

NOTE

$self and $c is not part of the argument list inside a chain() or private() action. $c is acquired by calling c(), and $self is available by calling controller().

EXPORTED FUNCTIONS

chain

 1. chain sub { };

 2. chain $PathPart => sub { };
 3. chain $PathPart => $Int, sub { };
 4. chain $PathPart => \@CaptureArgs, sub { };

 5. chain $Chained => $PathPart => sub { };
 6. chain $Chained => $PathPart => $Int, sub { };
 7. chain $Chained => $PathPart => \@CaptureArgs, sub { };

 8. chain ..., \%method_map;

Same as:

 1. sub root : Chained('/') PathPart('') CaptureArgs(0) { }

 2. sub $PathPart : Chained('/root') Args { }
 3. sub $PathPart : Chained('/root') Args($Int) { }
 4. sub $PathPart : Chained('/root') CaptureArgs($Int) { }

 5. sub $PathPart : Chained($Chained) Args { }
 6. sub $PathPart : Chained($Chained) Args($Int) { }
 7. sub $PathPart : Chained($Chained) CaptureArgs($Int) { }

 8. Special case: See below

@CaptureArgs is a list of names of the captured arguments, which can be retrieved using captured().

$Int is a number of Args to capture at the endpoint of a chain. These cannot be aquired using captured(), but is instead available in @_.

%method_map can be used if you want to dispatch to a specific method, for a certain HTTP method: (The HTTP method is in lowercase)

 %method_map = (
    post => sub { ... },
    get => sub { ... },
    delete => sub { ... },
    default => sub { ... },
    #...
 );

private

 private $name => sub {};

Same as:

 sub $name :Private {}

forward

 @Any = forward $action;
 @Any = forward $action, \@arguments;

See Catalyst::forward().

go

 go $action;
 go $action, \@arguments;

See Catalyst::go().

c

 $context_obj = c;

Returns the context object for this request, an instance of Catalyst.

controller

 $controller_obj = controller;

Returns the current controller object.

req

 $request_obj = req;

Returns the request object for this request, an instance of Catalyst::Request.

res

 $response_obj = res;

Returns the response object for this request, an instance of Catalyst::Response.

captured

 $value = captured($name);

Retrieve data captured in a chain, using the names set with chain().

 chain '/' => 'user' => ['id'], sub {
   res->body( captured('id') );
 };

stash

 $value = stash $key;
 $hash_ref = stash $key => $value, ...;
 $hash_ref = stash;

Set/get data from the stash. The $hash_ref is a reference to what the stash is holding.

This will be the same as:

 $c->stash->{$key} = $value;

session

 $value = session $key;
 $hash_ref == session $key => $value;
 $hash_ref == session;

Set/get data from the session. The $hash_ref is a reference to what the session is holding.

This function will only work if a session module/plugin is loaded into Catalyst.

report

 report $level, $format, @args;

Almost the same as:

 $c->log->$level(sprintf $format, @args);

But undef values from @args are turned into "__UNDEF__", and objects and/or datastructructures are flatten, using Data::Dumper.

METHODS

init_meta

See Moose::Exporter.

BUGS

Please report any bugs or feature requests to bug-catalystx-controller-sugar at rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT & LICENSE

Copyright 2007 Jan Henning Thorsen, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Jan Henning Thorsen, <jhthorsen at cpan.org>

cpanm CatalystX::Controller::Sugar

perl -MCPAN -e shell
install CatalystX::Controller::Sugar