Return to v2.5.0 docs


Configuration Routing struct mapper

Create a group of routes that exposes actions for manipulating a singular resource. A singular resource exposes URL patterns for the entire CRUD lifecycle of a single entity (show, new, create, edit, update, and delete) without exposing a primary key in the URL. Usually this type of resource represents a singleton entity tied to the session, application, or another resource (perhaps nested within another resource). If you need to generate routes for manipulating a collection of resources with a primary key in the URL, see the resources mapper method.

Name Type Required Default Description
name string Yes Camel-case name of resource to reference when build links and form actions. This is typically a singular word (e.g., profile).
nested boolean No false Whether or not additional calls will be nested within this resource.
path string No [runtime expression] Override URL path representing this resource. Default is a dasherized version of name (e.g., blogPost generates a path of blog-post).
controller string No Override name of the controller used by resource. This defaults to a pluralized version of name.
singular string No Override singularize() result in plural resources.
plural string No Override pluralize() result in singular resource.
only string No Limits the list of RESTful routes to generate. Can include show, new, create, edit, update, and delete.
except string No Excludes RESTful routes to generate, taking priority over the only argument. Can include show, new, create, edit, update, and delete.
shallow boolean No Turn on shallow resources.
shallowPath string No Shallow path prefix.
shallowName string No Shallow name prefix.
constraints struct No Variable patterns to use for matching.
mapFormat boolean No [runtime expression] Whether or not to add an optional .[format] pattern to the end of the generated routes. This is useful for providing formats via URL like json, xml, pdf, etc.

    // With default arguments

    // Point auth URL to controller at `controllers/sessions/Auth.cfc`
    .resource(name="auth", controller="sessions.auth")

    // Limited list of routes generated by `only` argument.
    .resource(name="profile", only="show,edit,update")

    // Limited list of routes generated by `except` argument.
    .resource(name="cart", except="new,create,edit,delete")

    // Nested resource
    .resource(name="preferences", only="index", nested=true)
      .get(name="editPassword", to="passwords##edit")
      .patch(name="password", to="passwords##update")


    // Overridden `path`
    .resource(name="blogPostOptions", path="blog-post/options")


Related Functions