put()

Signature

put() — returns struct

Available in: mapper Category: Routing

Description

Create a route that matches a URL requiring an HTTP PUT method. We recommend using this matcher to expose actions that update database records. This method is provided as a convenience for when you really need to support the PUT verb; consider using the patch matcher instead of this one.

Parameters

Name	Type	Required	Default	Description
name	string	no	—	Camel-case name of route to reference when build links and form actions (e.g., blogPost).
pattern	string	no	—	Overrides the URL pattern that will match the route. The default value is a dasherized version of name (e.g., a name of blogPost generates a pattern of blog-post).
to	string	no	—	Set controller##action combination to map the route to. You may use either this argument or a combination of controller and action.
controller	string	no	—	Map the route to a given controller. This must be passed along with the action argument.
action	string	no	—	Map the route to a given action within the controller. This must be passed along with the controller argument.
package	string	no	—	Indicates a subfolder that the controller will be referenced from (but not added to the URL pattern). For example, if you set this to admin, the controller will be located at admin/YourController.cfc, but the URL path will not contain admin/.
on	string	no	—	If this route is within a nested resource, you can set this argument to member or collection. A member route contains a reference to the resource’s key, while a collection route does not.
redirect	string	no	—	Redirect via 302 to this URL when this route is matched. Has precedence over controller/action. Use either an absolute link like /about/, or a full canonical link.

Examples

<cfscript>

mapper()
    // Route name:  ghostStory
    // Example URL: /ghosts/666/stories/616
    // Controller:  Stories
    // Action:      update
    .put(name="ghostStory", pattern="ghosts/[ghostKey]/stories/[key]", to="stories##update")

    // Route name:  goblins
    // Example URL: /goblins
    // Controller:  Goblins
    // Action:      update
    .put(name="goblins", controller="goblins", action="update")

    // Route name:  heartbeat
    // Example URL: /heartbeat
    // Controller:  Sessions
    // Action:      update
    .put(name="heartbeat", to="sessions##update")

    // Route name:  usersPreferences
    // Example URL: /preferences
    // Controller:  users.Preferences
    // Action:      update
    .put(name="preferences", to="preferences##update", package="users")

    // Route name:  orderShipment
    // Example URL: /shipments/5432
    // Controller:  orders.Shipments
    // Action:      update
    .put(
        name="shipment",
        pattern="shipments/[key]",
        to="shipments##update",
        package="orders"
    )

    // Example scoping within a nested resource
    .resources(name="subscribers", nested=true)
        // Route name:  launchSubscribers
        // Example URL: /subscribers/3209/launch
        // Controller:  Subscribers
        // Action:      launch
        .put(name="launch", to="subscribers##update", on="collection")

        // Route name:  discontinueSubscriber
        // Example URL: /subscribers/2251/discontinue
        // Controller:  Subscribers
        // Action:      discontinue
        .put(name="discontinue", to="subscribers##discontinue", on="member")
    .end()
.end();

</cfscript>