Resourceful Routes
In ColdBox, you can register resourceful routes (​
resources()) 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 and less typing 😉
1
// Creates all resources that point to a photos event handler by convention
2
resources( "photos" );
3
​
4
// Register multiple fluently
5
resources( "photos" )
6
.resources( "users" )
7
.resources( "contacts" );
8
​
9
// Creates all resources to the event handler of choice instead of convention
10
resources( resource="photos", handler="MyPhotoHandler" );
11
​
12
// All resources in a module
13
resources( resource="photos", handler="photos", module="api" );
14
​
15
// Resources in a ModuleConfig.cfc
16
router.resources( "photos" )
17
.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.
Verb
Route
Event
Purpose
GET
/photosphotos.index
Get all photos
GET
/photos/newphotos.new
Return the HTML form for creating a photo
POST
/photosphotos.create
Create a photo
GET
/photos/:idphotos.show
Show a photo by
idGET
/photos/:id/editphotos.edit
Return the HTML form for editing the photo
PUT/PATCH
/photos/:idphotos.update
Update a photo by
idDELETE
/photos/:idphotos.delete
Delete a photo by
idFor 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
*
4
* By convention the following rules apply
5
* - The name of the resource maps to the name of the event handler
6
* - The default paremeter name is called `:id`
7
* - The available actions are: index, new, create, show, edit, update, delete
8
*
9
* Example: `resource = photos` Then we will create the following routes:
10
* - `/photos` : `GET` -> `photos.index` Display a list of photos
11
* - `/photos/new` : `GET` -> `photos.new` Returns an HTML form for creating a new photo
12
* - `/photos` : `POST` -> `photos.create` Create a new photo
13
* - `/photos/:id` : `GET` -> `photos.show` Display a specific photo
14
* - `/photos/:id/edit` : `GET` -> `photos.edit` Return an HTML form for editing a photo
15
* - `/photos/:id` : `PUT/PATCH` -> `photos.update` Update a specific photo
16
* - `/photos/:id` : `DELETE` -> `photos.delete` Delete a specific photo
17
*
18
* @resource The name of a single resource to map
19
* @handler The handler for the route. Defaults to the resource name.
20
* @parameterName The name of the id/parameter for the resource. Defaults to `id`.
21
* @only Limit routes created with only this list or array of actions, e.g. "index,show"
22
* @except Exclude routes with an except list or array of actions, e.g. "show"
23
* @module If passed, the module these resources will be attached to.
24
* @namespace If passed, the namespace these resources will be attached to.
25
* @pattern If passed, the actual URL pattern to use, else it defaults to `/#arguments.resource#` the name of the resource.
26
* @meta A struct of metadata to store with ALL the routes created from this resource
27
*/
28
function resources(
29
required resource,
30
handler,
31
parameterName = "id",
32
only = [],
33
except = [],
34
string module = "",
35
string namespace = "",
36
string pattern = "",
37
struct meta = {}
38
){
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!
API Routes
If you are building mostly API routes and not full HTML app routes, you can use the shortcut method
apiResources() method instead. This method will work the same as above BUT it will exclude the new and edit actions for you since we are in API Land.1
apiResources( "users" );
2
apiResources( "photos" );
Copied!
Verb
Route
Event
Purpose
GET
/photosphotos.index
Get all photos
POST
/photosphotos.create
Create a photo
GET
/photos/:idphotos.show
Show a photo by
idPUT/PATCH
/photos/:idphotos.update
Update a photo by
idDELETE
/photos/:idphotos.delete
Delete a photo by
id​
Last modified 4mo ago
Copy link
Edit on GitHub