ColdBox HMVC Documentation
DocsSourceSupportTraining
7.x
7.x
  • Introduction
    • Contributing Guide
    • Release History
      • What's New With 7.4.0
      • What's New With 7.3.x
      • What's New With 7.2.0
      • What's New With 7.1.0
      • What's New With 7.0.0
        • Release Notes
    • Upgrading to ColdBox 7
    • What is ColdBox
    • What is MVC
    • About This Book
      • Author
  • For Newbies
    • 60 Minute Quick Start
      • Installing ColdBox
      • My First ColdBox Application
      • My First Handler & View
      • Linking Events Together
      • Working with Events
      • Adding A Layout
      • Adding A Model
      • RESTFul Data
      • Next Steps
    • Getting Started Guide
  • Getting Started
    • Installation
    • Application Templates
    • Conventions
    • Configuration
      • ColdBox.cfc
        • Configuration Directives
          • CacheBox
          • ColdBox
          • Conventions
          • Environments
          • Flash
          • InterceptorSettings
          • Interceptors
          • Layouts
          • LayoutSettings
          • LogBox
          • Modules
          • ModuleSettings
          • Settings
          • WireBox
        • System Settings (Java Properties and Environment Variables)
      • Using Settings
      • Bootstrapper - Application.cfc
  • The Basics
    • Request Context
    • Routing
      • Requirements
        • Rewrite Rules
      • Application Router
      • Routing DSL
        • Routing By Convention
        • Pattern Placeholders
        • Routing Methods
        • Resourceful Routes
        • Named Routes
        • Routing Groups
        • Routing Namespaces
      • Building Routable Links
      • RESTFul Extension Detection
      • HTTP Method Spoofing
      • HTML Base Tag
      • Pathinfo Providers
    • Event Handlers
      • How are events called?
      • Getting & Setting Values
      • Setting Views
      • Relocating
      • Rendering Data
      • Sending Files
      • Interception Methods
        • Pre Advices
        • Post Advices
        • Around Advices
      • Model Integration
        • Model Data Binding
      • HTTP Method Security
      • Implicit Methods
      • Executing Events
      • Executing Routes
      • Viewlets - Reusable Events
      • Event Caching
      • Validation
    • Layouts & Views
      • Views
        • Rendering Views
        • Rendering External Views
        • Rendering With Local Variables
        • Rendering Collections
        • View Caching
        • View Helpers
        • View Events
      • Layouts
        • Basic Layouts
        • Default Layout
        • Nested Layouts
        • Overriding Layouts
        • Layouts From A Module
        • Layout Helpers
        • Layout Events
      • Implicit Layout-View Declarations
      • Helpers UDF's
      • ColdBox Elixir
    • Models
      • Domain Modeling
        • Service Layer
        • Data Layers
        • Book
      • Conventions Location
      • WireBox Binder
      • Super Type Usage Methods
      • Injection DSL
        • ColdBox Namespace
        • CacheBox Namespace
        • EntityService Namespace
        • Executor Namespace
        • Java Namespace
        • LogBox Namespace
        • Models Namespace
        • Provider Namespace
        • WireBox Namespace
      • Object Scopes
      • Coding: Solo Style
        • Datasource
        • Contact.cfc
        • ContactDAO.cfc
        • ContactService.cfc
        • Contacts Handler
      • Coding: ActiveEntity Style
        • ORM
        • Contact.cfc
        • Contacts Handler
        • Views
      • Coding: Virtual Service Layer
        • ORM
        • Contacts.cfc
        • Contacts Handler
        • Views
      • Coding: ORM Scaffolding
        • ORM
        • Contacts.cfc
        • Scaffold
    • Interceptors
      • How do they work?
        • Conventions
      • Interceptor Declaration
      • Interceptor Registration
      • Dynamic Registration
      • Core Interception Points
        • Application Life Cycle Events
        • Object Creating Events
        • Layout-View Events
        • Module Events
        • CacheBox Events
      • Restricting Execution
      • Interceptor Output Buffer
      • Custom Events
        • Configuration Registration
        • Programmatic Registration
        • Listening
        • Announcing Interceptions
      • Unregistering Interceptors
      • Reporting Methods
      • Interceptor Asynchronicity
        • Async Announcements
        • Async Listeners With Join
        • Async Listeners No Join
        • Asynchronous Annotations
  • HMVC
    • Modules
      • Core Modules
      • Locations
      • Parent Configuration
      • Module Layout
        • Changing The Module Layout
      • Module Service
        • Module Lifecycle
        • Module Registration
        • Module Activation
        • Module Unloading
        • Common Methods
        • Loading New Modules
        • Loading A-la-carte Modules
        • Module Events
      • ModuleConfig
        • Public Module Properties
        • The Decorated Variables
        • The configure() Method
        • Module Settings
        • Environment Control
        • Interceptor Events
      • Module Event Executions
      • URL Routing
        • Default Route Execution
        • Module Routes Files
      • Module Async Scheduling
      • Request Context Module Methods
      • Layout and View Renderings
        • Layout/View Discovery
        • Overriding Views
        • Overriding Layouts
        • Default Module Layout
        • Explicit Module Renderings
      • Models
      • Module CF Mappings
      • Module Dependencies
      • Module Helpers
      • Module Bundles
      • Module Inception
  • Testing
    • Testing Quick Start
    • Testing ColdBox Applications
      • Test Harness
      • ColdBox Testing Classes
      • Testing Methods
      • Integration Testing
        • Test Annotations
        • Life-Cycle Events
        • Request Setup()
        • The execute() Method
        • HTTP Testing Methods
        • Testing Without Virtual Application
      • Interceptor Testing
      • Model Object Testing
      • Tips & Tricks
  • Digging Deeper
    • Async Programming
      • Async Pipelines & Futures
      • Parallel Computations
      • Executors
      • Scheduled Tasks
    • ColdBox Proxy
      • Getting Started
      • The Base Proxy Object
      • The Event Handlers
        • Distinguishing Request Types
        • RenderData()
      • Proxy Events
      • Standard Return Types
      • Caveats & Gotchas
    • Controller Decorator
    • ColdBox Scheduled Tasks
    • Flash RAM
      • Flash Storage
      • Using Flash RAM
      • Creating Your Own Flash Scope
    • HTML Helper
    • REST Handler
    • Request Context Decorator
    • Recipes
      • Building REST APIs
      • ColdBox Exception Handling
      • Debugging ColdBox Apps
      • Clearing the View Cache
      • Basic HTTP Authentication Interceptor
  • Architecture Concepts
    • How ColdBox Works
Powered by GitBook
On this page
  • Scaffolding Resources
  • API Resourceful Routes

Was this helpful?

Edit on GitHub
Export as PDF
  1. The Basics
  2. Routing
  3. Routing DSL

Resourceful Routes

Resourceful routes are convention based to help you create routing with less boilerplate.

Last updated 1 year ago

Was this helpful?

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

// Creates all resources that point to a photos event handler by convention
resources( "photos" );

// Register multiple fluently
resources( "photos" )
    .resources( "users" )
    .resources( "contacts" );

// Creates all resources to the event handler of choice instead of convention
resources( resource="photos", handler="MyPhotoHandler" );

// All resources in a module
resources( resource="photos", handler="photos", module="api" );

// Resources in a ModuleConfig.cfc
router.resources( "photos" )
  .resources( resource="users", handler="user" )

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

/photos

photos.index

Get all photos

GET

/photos/new

photos.new

Return the HTML form for creating a photo

POST

/photos

photos.create

Create a photo

GET

/photos/:id

photos.show

Show a photo by id

GET

/photos/:id/edit

photos.edit

Return the HTML form for editing the photo

PUT/PATCH

/photos/:id

photos.update

Update a photo by id

DELETE

/photos/:id

photos.delete

Delete a photo by id

For in-depth usage of the resources() method, let's investigate the API Signature:

/**
 * Create all RESTful routes for a resource. It will provide automagic mappings between HTTP verbs and URLs to event handlers and actions.
 *
 * By convention the following rules apply
 * - The name of the resource maps to the name of the event handler
 * - The default paremeter name is called `:id`
 * - The available actions are: index, new, create, show, edit, update, delete
 *
 * Example: `resource = photos` Then we will create the following routes:
 * - `/photos` : `GET` -> `photos.index` Display a list of photos
 * - `/photos/new` : `GET` -> `photos.new` Returns an HTML form for creating a new photo
 * - `/photos` : `POST` -> `photos.create` Create a new photo
 * - `/photos/:id` : `GET` -> `photos.show` Display a specific photo
 * - `/photos/:id/edit` : `GET` -> `photos.edit` Return an HTML form for editing a photo
 * - `/photos/:id` : `PUT/PATCH` -> `photos.update` Update a specific photo
 * - `/photos/:id` : `DELETE` -> `photos.delete` Delete a specific photo
 *
 * @resource      The name of a single resource to map
 * @handler       The handler for the route. Defaults to the resource name.
 * @parameterName The name of the id/parameter for the resource. Defaults to `id`.
 * @only          Limit routes created with only this list or array of actions, e.g. "index,show"
 * @except        Exclude routes with an except list or array of actions, e.g. "show"
 * @module        If passed, the module these resources will be attached to.
 * @namespace     If passed, the namespace these resources will be attached to.
 * @pattern       If passed, the actual URL pattern to use, else it defaults to `/#arguments.resource#` the name of the resource.
 * @meta          A struct of metadata to store with ALL the routes created from this resource
 */
function resources(
	required resource,
	handler,
	parameterName    = "id",
	only             = [],
	except           = [],
	string module    = "",
	string namespace = "",
	string pattern   = "",
	struct meta      = {}
){

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:

coldbox create resource help

API Resourceful 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.

apiResources( "users" );
apiResources( "photos" );
Verb
Route
Event
Purpose

GET

/photos

photos.index

Get all photos

POST

/photos

photos.create

Create a photo

GET

/photos/:id

photos.show

Show a photo by id

PUT/PATCH

/photos/:id

photos.update

Update a photo by id

DELETE

/photos/:id

photos.delete

Delete a photo by id

Here is the full method signature:

/**
 * Create all API RESTful routes for a resource. It will provide automagic mappings between HTTP verbs and URLs to event handlers and actions.
 *
 * By convention the following rules apply
 * - The name of the resource maps to the name of the event handler
 * - The default paremeter name is called `:id`
 * - The available actions are: index, create, show, update, delete
 *
 * Example: `resource = photos` Then we will create the following routes:
 * - `/photos` : `GET` -> `photos.index` Get a list of photos from the API
 * - `/photos` : `POST` -> `photos.create` Create a new photo
 * - `/photos/:id` : `GET` -> `photos.show` Get a specific photo from the API
 * - `/photos/:id` : `PUT/PATCH` -> `photos.update` Update a specific photo
 * - `/photos/:id` : `DELETE` -> `photos.delete` Delete a specific photo
 *
 * @resource      The name of a single resource to map
 * @handler       The handler for the route. Defaults to the resource name.
 * @parameterName The name of the id/parameter for the resource. Defaults to `id`.
 * @only          Limit routes created with only this list or array of actions, e.g. "index,show"
 * @except        Exclude routes with an except list or array of actions, e.g. "show"
 * @module        If passed, the module these resources will be attached to.
 * @namespace     If passed, the namespace these resources will be attached to.
 * @pattern       If passed, the actual URL pattern to use, else it defaults to `/#arguments.resource#` the name of the resource.
 * @meta          A struct of metadata to store with ALL the routes created from this resource
 */
function apiResources(
	required resource,
	handler,
	parameterName    = "id",
	only             = [],
	except           = [ "new", "edit" ],
	string module    = "",
	string namespace = "",
	string pattern   = "",
	struct meta      = {}
){
😉