Resourceful Routes

In ColdBox, you can register resourceful routes to provide automatic mappings between HTTP verbs and URLs to event handlers and actions by convention. By convention, all resources map to a handler with the same name or they can be customized if needed. This allows for a standardized convention when building routed applications.
You can leverage the resources() method in your router to register resourceful routes.
1
// Creates all resources that point to a photos event handler by convention
2
resources( "photos" );
3
​
4
// Register multiple resources either as strings or arrays
5
resources( "photos,users,contacts" )
6
resources( [ "photos" , "users", "contacts" ] );
7
​
8
// Register multiple fluently
9
resources( "photos" )
10
    .resources( "users" )
11
    .resources( "contacts" );
12
​
13
// Creates all resources to the event handler of choice instead of convention
14
resources( resource="photos", handler="MyPhotoHandler" );
15
​
16
// All resources in a module
17
resources( resource="photos", handler="photos", module="api" );
18
​
19
// Resources in a ModuleConfig.cfc
20
router.resources( "photos" )
21
  .resources( resource="users", handler="user" )
Copied!
This single resource declaration will create all the necessary variations of URL patterns and HTTP Verbs to actions to handle the resource. Please see the table below with all the permutations it will create for you.
Resources Table
For in-depth usage of the resources() method, let's investigate the API Signature:
1
/**
2
* Create all RESTful routes for a resource. It will provide automagic mappings between HTTP verbs and URLs to event handlers and actions.
3
* By convention, the name of the resource maps to the name of the event handler.
4
* Example: `resource = photos` Then we will create the following routes:
5
* - `/photos` : `GET` -> `photos.index` Display a list of photos
6
* - `/photos/new` : `GET` -> `photos.new` Returns an HTML form for creating a new photo
7
* - `/photos` : `POST` -> `photos.create` Create a new photo
8
* - `/photos/:id` : `GET` -> `photos.show` Display a specific photo
9
* - `/photos/:id/edit` : `GET` -> `photos.edit` Return an HTML form for editing a photo
10
* - `/photos/:id` : `PUT/PATCH` -> `photos.update` Update a specific photo
11
* - `/photos/:id` : `DELETE` -> `photos.delete` Delete a specific photo
12
* 
13
* @resource         The name of a single resource or a list of resources or an array of resources
14
* @handler          The handler for the route. Defaults to the resource name.
15
* @parameterName    The name of the id/parameter for the resource. Defaults to `id`.
16
* @only             Limit routes created with only this list or array of actions, e.g. "index,show"
17
* @except           Exclude routes with an except list or array of actions, e.g. "show"
18
* @module           If passed, the module these resources will be attached to.
19
* @namespace        If passed, the namespace these resources will be attached to.
20
*/
21
function resources(
22
  required resource,
23
  handler=arguments.resource,
24
  parameterName="id",
25
  only=[],
26
  except=[],
27
  string module="",
28
  string namespace=""
29
)
Copied!
Scaffolding Resources
We have created a scaffolding command in CommandBox to help you register and generate resourceful routes. Just run the following command in CommandBox to get all the help you will need in generating resources:
1
coldbox create resource help
Copied!

Routing Methods

Named Routes

Last modified 1yr ago

Copy link

Edit on GitHub

Contents

Scaffolding Resources