Name

Forward::Guides::Routes::Resources - Rails like resource routing for Plack web framework developers (Perl)

Plural Resources

Forward::Routes provides support for Rails like resource routing. The add_resources command generates a bunch of routes that can be used to dispatch to a controller's read, create, update and delete actions and to display CRUD related forms. Framework builders are responsible to load the respective controller classes and to execute the desired controller method. Forward::Routes just generates the routes and in case of a match, provides a match object with the needed controller and action parameters.

# Routes root object
my $routes = Forward::Routes->new;

# Add a resource
$routes->add_resources('cities');

# The following routes are generated:

HTTP     Path                 Controller  Action        Route name
request                       parameter   parameter
method          

GET      /cities/new          Cities      create_form   cities_create_form
GET      /cities/:id          Cities      show          cities_show
GET      /cities/:id/edit     Cities      update_form   cities_update_form
GET      /cities/:id/delete   Cities      delete_form   cities_delete_form
GET      /cities              Cities      index         cities_index
POST     /cities              Cities      create        cities_create
PUT      /cities/:id          Cities      update        cities_update
DELETE   /cities/:id          Cities      delete        cities_delete

Each generated route will usually dispatch to a specific method (see action parameter above) which is used to:

Action (method)       Used to

create_form           display a form to create a new item
show                  display an individual item
update_form           display a form to update an existing item
delete_form           display a form to confirm the deletion of an existing item
index                 list all items
create                create a new item
update                update an existing item
delete                delete an existing item

Multiple resources can be created with a single add_resources call:

# Add multiple resources
$routes->add_resources('cities', 'users', 'articles');

# equals
$routes->add_resources('cities'');
$routes->add_resources('users');
$routes->add_resources('articles');    

Singular Resources

Forward::Routes also supports singular resource routing. Singular resources are useful if the "id" is already known and has not to be part of the URL pattern. For example, the id might already be part of a higher level route (in case of nested routes) or could be derived from a cookie.

# Routes root object
my $routes = Forward::Routes->new;

my $author = $routes->add_route('author/:id');

# Add a singular resource to $author
$author->add_singular_resources('contact');

# The following routes are generated on top of author/:id:

HTTP     Path            Controller  Action        Route name
request                  parameter   parameter
method          

GET      /contact/new    Contact     create_form   contact_create_form
GET      /contact/edit   Contact     update_form   contact_update_form
GET      /contact        Contact     show          contact_show
PUT      /contact        Contact     update        contact_update
POST     /contact        Contact     create        contact_create
DELETE   /contact        Contact     delete        contact_delete

Customization

Resource routing is quite flexible and offers many customization options:

Forward::Guides::Routes::ResourceCustomization

Taking a look at the source

The internal code to generate a resource makes use of nested routes:

my $resource = $routes->add_route('cities');

# get => /cities
$resource->add_route
  ->via('get')
  ->to("Cities#index")
  ->name('cities_index');

# post => /cities
$resource->add_route
  ->via('post')
  ->to("Cities#create")
  ->name('cities_create');

# get => /cities/new
$resource->add_route('/new')
  ->via('get')
  ->to("Cities#create_form")
  ->name('cities_create_form');

# nested route with id placeholder, placeholder can contain everything
# but dots and slashed (constraint)
my $nested = $resource->add_route(':id')
  ->constraints('id' => qr/[^.\/]+/);

# get => /cities/paris
$nested->add_route
  ->via('get')
  ->to("Cities#show")
  ->name('cities_show');

# put => /cities/paris
$nested->add_route
  ->via('put')
  ->to("Cities#update")
  ->name('cities_update');

# delete => /cities/paris
$nested->add_route
  ->via('delete')
  ->to("Cities#delete")
  ->name('cities_delete');

# get => /cities/paris/edit
$nested->add_route('edit')
  ->via('get')
  ->to("Cities#update_form")
  ->name('cities_update_form');

# get => /cities/paris/delete
$nested->add_route('delete')
  ->via('get')
  ->to("Cities#delete_form")
  ->name('cities_delete_form');