scope()

Signature

scope() — returns struct

Available in: mapper Category: Routing

Description

The scope() function in Wheels is used to define a block of routes that share common parameters such as controller, package, path, or naming prefixes. All routes defined inside a scope() block automatically inherit these parameters unless explicitly overridden, making it easier to manage related routes. This is particularly useful for grouping routes under the same controller or package, adding a common URL prefix to multiple routes, applying shallow routing to nested resources, and reducing repetition while improving the maintainability of route definitions.

Parameters

Name	Type	Required	Default	Description
name	string	no	—	Name to prepend to child route names for use when building links, forms, and other URLs.
path	string	no	—	Path to prefix to all child routes.
package	string	no	—	Package namespace to append to controllers.
controller	string	no	—	Controller to use for routes.
shallow	boolean	no	—	Turn on shallow resources to eliminate routing added before this one.
shallowPath	string	no	—	Shallow path prefix.
shallowName	string	no	—	Shallow name prefix.
constraints	struct	no	—	Variable patterns to use for matching.
$call	string	no	scope

Examples

1. Set a default controller for multiple routes

<cfscript>
mapper()
    .scope(controller="freeForAll")
        .get(name="bananas", action="bananas")
        .root(action="index")
    .end()
.end();
</cfscript>

2. Apply a package/subfolder to multiple resources

<cfscript>
mapper()
    .scope(package="public")
        .resource(name="search", only="show,create")
    .end()
.end();
</cfscript>

3. Add a common URL path prefix

<cfscript>
mapper()
    .scope(path="phones")
        .get(name="newest", to="phones##newest")
        .get(name="sortOfNew", to="phones##sortOfNew")
    .end()
.end();
</cfscript>

4. Combine controller and path scoping

<cfscript>
mapper()
    .scope(controller="products", path="shop")
        .get(name="featured", action="featured")
        .get(name="sale", action="sale")
    .end()
.end();
</cfscript>

5. Use constraints for route variables

<cfscript>
mapper()
    .scope(path="users", constraints={userId="\d+"})
        .get(name="profile", pattern="[userId]/profile", action="show")
    .end()
.end();
</cfscript>