Class Router

lucee.Component
    coldbox.system.web.routing.Router

init

Constructor

baseURL

Base routing URL

Attributes:

access - public

required - false

returntype - any

serializable - true

cachebox

DI *

Attributes:

access - public

required - false

returntype - any

inject - cachebox

serializable - true

delegate - getCache

controller

Attributes:

access - public

required - false

returntype - any

inject - coldbox

serializable - true

delegate - relocate,runEvent,runRoute

enabled

Flag to enable/disable routing

Attributes:

access - public

required - false

returntype - any

serializable - true

extensionDetection

Detect extensions flag, so it can place a 'format' variable on the rc

Attributes:

access - public

required - false

returntype - any

serializable - true

flash

Attributes:

access - public

required - false

returntype - any

inject - coldbox:flash

serializable - true

fullRewrites

This flag denotes if full URL rewrites are enabled or not. Meaning if the `index` is in the path of the rewriter or not. The default value is **false**.

Attributes:

access - public

required - false

returntype - any

serializable - true

log

Attributes:

access - public

required - false

returntype - any

inject - logbox:logger:{this}

serializable - true

logBox

Attributes:

access - public

required - false

returntype - any

inject - logbox

serializable - true

looseMatching

Loose matching flag for regex matches

Attributes:

access - public

required - false

returntype - any

serializable - true

moduleRoutingTable

Modules Routing Table

Attributes:

access - public

required - false

returntype - any

serializable - true

multiDomainDiscovery

This flag denotes that the routing service will discover the incoming base URL from the host + ssl + environment. If off, then it will use whatever the base URL was set in the router.

Attributes:

access - public

required - false

returntype - any

serializable - true

namespaceRoutingTable

Namespace routing tables

Attributes:

access - public

required - false

returntype - any

serializable - true

routes

The routing table

Attributes:

access - public

required - false

returntype - any

serializable - true

thisModule

Fluent route construct for modules

Attributes:

access - public

required - false

returntype - any

serializable - true

thisRoute

Fluent route construct

Attributes:

access - public

required - false

returntype - any

serializable - true

throwOnInvalidExtension

Throw an exception when extension detection is invalid or not

Attributes:

access - public

required - false

returntype - any

serializable - true

validExtensions

Initialize the valid extensions to detect

Attributes:

access - public

required - false

returntype - any

serializable - true

wirebox

Attributes:

access - public

required - false

returntype - any

inject - wirebox

serializable - true

delegate - getInstance

withClosure

Fluent route construct for with routing

Attributes:

access - public

required - false

returntype - any

serializable - true

addModuleRoutes

Register modules routes in the specified position in the main routing table, and returns itself

Parameters:

pattern - The pattern to match against the URL

module - The module to load routes for

append - Whether the module entry point route should be appended or pre-pended to the main routes array. By default we append to the end of the array

Returns:

Router

• static false

addNamespace

Register a namespace in the specified position in the main routing table, and returns itself

Parameters:

pattern - The pattern to match against the URL.

namespace - The name of the namespace to register

append - Whether the route should be appended or pre-pended to the array. By default we append to the end of the array

Returns:

Router

• static false

addRoute

Adds a route to dispatch and returns itself.

Parameters:

pattern - The pattern to match against the URL.

handler - The handler to execute if pattern matched.

action - The action in a handler to execute if a pattern is matched. This can also be a structure based on the HTTP method(GET,POST,PUT,DELETE). ex: {GET:'show', PUT:'update', DELETE:'delete', POST:'save'}

packageResolverExempt - If this is set to true, then the interceptor will not try to do handler package resolving. Else a package will always be resolved. Only works if :handler is in a pattern

matchVariables - DEPRECATED: Use RC or PRC structs instead. A string of name-value pair variables to add to the request collection when this pattern matches. This is a comma delimited list. Ex: spaceFound=true,missingAction=onTest

view - The view to dispatch if pattern matches. No event will be fired, so handler,action will be ignored.

viewNoLayout - If view is chosen, then you can choose to override and not display a layout with the view. Else the view renders in the assigned layout.

valuePairTranslation - Activate convention name value pair translations or not. Turned on by default

constraints - A structure of regex constraint overrides for variable placeholders. The key is the name of the variable, the value is the regex to try to match.

module - The module to add this route to

moduleRouting - Called internally by addModuleRoutes to add a module routing route.

namespace - The namespace to add this route to

namespaceRouting - Called internally by addNamespaceRoutes to add a namespaced routing route.

ssl - Makes the route an SSL only route if true, else it can be anything. If an ssl only route is hit without ssl, the interceptor will redirect to it via ssl

append - Whether the route should be appended or pre-pended to the array. By default we append to the end of the array

response - An HTML response string to send back or a closure to be executed that should return the response. The closure takes in a 'params' struct of all matched params and the string will be parsed with the named value pairs as ${param}

statusCode - The HTTP status code to send to the browser response.

condition - A closure or UDF to execute that MUST return true to use route if matched or false and continue.

name - The name of the route

domain - The domain to match, including wildcards

redirect - If used, then the route will dispatch a relocation to this value as the new route using the `statuCode` default of 301 (Permanent) or if you define a `statusCode` we will use that.

event - The event to execute if route matches

verbs - The allowed HTTP Verbs for the route

layout - The view layout to use

headers - The HTTP headers to attach to the response if route matches

rc - The RC name value pairs to attach if the response matches

prc - The PRC name value pairs to attach if the response matches

viewModule - The module the view belongs to

layoutModule - The module the layout belongs to

meta - Additional metadata to add to the incoming route

Returns:

SES

• static false

apiResources

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

Parameters:

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

• static false

append

Appends the route to the routing table. By default all routes are appended.

route( "hello", "main.index" ).append();

• static false

as

Registers the route as a named route

route( "hello", "main.index" ).as( "main" )

Parameters:

name - The name to use for the route

• static false

composeRoutingPath

Composes the base routing path with no host or protocol

• static false

composeRoutingUrl

Composes the base URL for the server using the following composition: - protocol - host + port - routing app mapping - full Url routing or front controller routing

• static false

configure

This method is to be implemented by the application router you create. This is where you will define all your routing.

• static false

constraints

Register a struct of constraints for the route

route( "hello", "main.index" ).constraints( { ... } )

Parameters:

map - A structure of regex constraint overrides for variable placeholders. The key is the name of the variable, the value is the regex to try to match.

• static false

delete

Register a route with DELETE restriction. Same as calling the following

route( "/hello", "hello" ).withVerbs( "DELETE" )

Parameters:

pattern - The pattern to register

target - A response closure/lambda or an event string to execute

• static false

end

This is a global route definition terminator. It will grab whatever the fluent API collected and create a route from it.

route( "hello" ).withHandler( "luis" ).withAction( "hello" ).end();

• static false

endWith Deprecated

End a with closure and returns itself

Deprecated:

This has been deprecated in favor of the group() function.

Returns:

Router

• static false

filterRouteActions

Get the correct route actions based on only and except lists

Parameters:

initial - The initial set of route actions

only - Limit actions with only

except - Exclude actions with except

• static false

findRouteByName

This function tries to find a specifc route by incoming name. If you need a route from a module then append the module address: `@moduleName` or prefix it like in run event calls `moduleName:routeName` in order to find the right route.

Parameters:

name - The name of the route

• static false

get

Register a route with GET restriction. Same as calling the following

route( "/hello", "hello" ).withVerbs( "GET" )

Parameters:

pattern - The pattern to register

target - A response closure/lambda or an event string to execute

• static false

getBaseURL

getCachebox

getController

getEnabled

getExtensionDetection

getFlash

getFullRewrites

getLog

getLogBox

getLooseMatching

getMemento

A quick snapshot of the router state

• static false

getModuleRoutes

Get a module's routes array

Parameters:

module - The module to get

• static false

getModuleRoutingTable

getModulesRoutingTable Deprecated

A quick ColdBox4 compatibility wrapper

Deprecated:

Please use `getModuleRoutingTable()` instead.

• static false

getMultiDomainDiscovery

getNamespaceRoutes

Get a namespace routes array

Parameters:

namespace - The namespace to get

• static false

getNamespaceRoutingTable

getRoutes

getThisModule

getThisRoute

getThrowOnInvalidExtension

getValidExtensions

getWirebox

getWithClosure

group

This is the new approach to the with closure approach which has been marked as deprecated. You can pass any route option via the options structure and those values will be prefixed against any routing values done within the body closure.

group( { pattern="/api", target="api", handler="api" }, function( options ){
route( "/", "main.index" );
route( "/echo", "echo" );
route( "/users/:id" ).withAction( { get : "index", post : "save" } ).toHandler( "users" );
} )

Parameters:

options - The route options that match routing, look at the addRoute() method

body - The closure or lambda to contain all the routing methods to be grouped with the options data.

• static false

header

Add a header to a route

route( "hello", "main.index" ).header( "name", "hello" )

Parameters:

name - The header name

value - The header value

overwrite - Overwrite if already defined

• static false

headers

Appends a collection of header name-values to a pattern

route( "hello" ).headers( { ... } ).to( "main.index" )

Parameters:

map - The structure of headers to issue

overwrite - Overwrite the elements

• static false

includeRoutes Deprecated

Includes a routes configuration file as an added import and returns itself after import

Deprecated:

Please use the Routes class approach instead

Parameters:

location - The include location of the routes configuration template.

Returns:

Router

• static false

initRouteDefinition

Construct a route definition construct

• static false

isValidExtension

Verifies if an extension is valid in the Router

Parameters:

extension - The extension to validate

• static false

meta

Appends a collection of metadata name-values to a pattern

route( "hello" ).meta( { secure : true, perms : [] } ).to( "main.index" )

Parameters:

map - The structure of metadata to store within the route

overwrite - Overwrite the elements

• static false

options

Register a route with OPTIONS restriction. Same as calling the following

route( "/hello", "hello" ).withVerbs( "OPTIONS" )

Parameters:

pattern - The pattern to register

target - A response closure/lambda or an event string to execute

• static false

packageResolver

Turn package resolver on/off

route( "hello", "main.index" ).packageResolver( false );

Parameters:

toggle - The boolean toggle

• static false

patch

Register a route with PATHC restriction. Same as calling the following

route( "/hello", "hello" ).withVerbs( "PATHC" )

Parameters:

pattern - The pattern to register

target - A response closure/lambda or an event string to execute

• static false

post

Register a route with POST restriction. Same as calling the following

route( "/hello", "hello" ).withVerbs( "POST" )

Parameters:

pattern - The pattern to register

target - A response closure/lambda or an event string to execute

• static false

prc

Register a private request collection name-value pair if the route matches

route( "hello", "main.index" ).prc( "private", true )

Parameters:

name - The key name

value - The value

overwrite - Overwrite the value

• static false

prcAppend

Appends a collection of name-values to the PRC if the route matches

route( "hello", "main.index" ).prcAppend( { ... } )

Parameters:

map - The structure to append

overwrite - Overwrite elements, default behavior

• static false

prepend

Prepends the route to the routing table. By default all routes are appended.

route( "hello", "main.index" ).prepend();

• static false

processRouteOptionals

Process route optionals

Parameters:

thisRoute - The route structure

• static false

processWith

process a with closure

Parameters:

args - The arguments to process

Returns:

Router

• static false

put

Register a route with PUT restriction. Same as calling the following

route( "/hello", "hello" ).withVerbs( "PUT" )

Parameters:

pattern - The pattern to register

target - A response closure/lambda or an event string to execute

• static false

rc

Register a request collection name-value pair if the route matches

route( "hello", "main.index" ).rc( "private", true )

Parameters:

name - The key name

value - The value

overwrite - Overwrite the value

• static false

rcAppend

Appends a collection of name-values to the RC if the route matches

route( "hello", "main.index" ).rcAppend( { ... } )

Parameters:

map - The structure to append

overwrite - Overwrite elements, default behavior

• static false

removeModuleRoutes

Remove a module's routing table and registration points and return itself

Parameters:

module - The module to remove

Returns:

Router

• static false

removeNamespaceRoutes

Remove a namespace's routing table and registration points and return itself

Parameters:

namespace - The namespace to remove

Returns:

Router

• static false

resources

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

Parameters:

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

• static false

route

Initiate a new route registration. Please note that you must finalize the registration by calling a terminator fluently. Unless, you pass in a target which can be a response closure/lambda or an event string.

// with terminator
route( "/home" ).to( "main.index" )
// with inline lambda
route( "/home", function( event, rc, prc ){ return "hello"; }  )
// with inline event
route( "/home", "main.index" )
// with inline event + name
route( "/home", "main.index", "home" )

Parameters:

pattern - The pattern to register

target - A response closure/lambda or an event string to execute

name - The name of the route, defaults to the the pattern

• static false

setBaseURL

Parameters:

baseURL

setCachebox

Parameters:

cachebox

setController

Parameters:

controller

setEnabled

Parameters:

enabled

setExtensionDetection

Parameters:

extensionDetection

setFlash

Parameters:

flash

setFullRewrites

Parameters:

fullRewrites

setLog

Parameters:

log

setLogBox

Parameters:

logBox

setLooseMatching

Parameters:

looseMatching

setModuleRoutingTable

Parameters:

moduleRoutingTable

setMultiDomainDiscovery

Parameters:

multiDomainDiscovery

setNamespaceRoutingTable

Parameters:

namespaceRoutingTable

setRoutes

Parameters:

routes

setThisModule

Parameters:

thisModule

setThisRoute

Parameters:

thisRoute

setThrowOnInvalidExtension

Parameters:

throwOnInvalidExtension

setValidExtensions

Parameters:

validExtensions

setWirebox

Parameters:

wirebox

setWithClosure

Parameters:

withClosure

startup

This method is called by the Routing Services to make sure the router is ready for operation. This is ONLY called by the routing services and only ONCE in the Application Life-Cycle

• static false

to

Terminates the route to execute an event

route( "old" ).to( "main.index" );
route( "old" ).to( "main" );
route( "old" ).to( "api:main.index" );

Parameters:

event - The event to execute

• static false

toAction

Terminates the route to execute a specific action or action struct. Usually the handler has already been defined beforehand.

route( "about/:handler" ).toAction( "index" )
route( "/api/v1/users" ).withHandler( "users" ).toAction( { GET : "index", POST : "save" } )

Parameters:

action - The action string or the action struct of HTTP verbs matching an action

• static false

toHandler

Terminates the route to execute a specific handler. Usually this will be done if the action is coming via the URL as a `:action` placeholder or you want the default `index` action to execute.

route( "about/:action" ).toHandler( "static" )
route( "users/:action?" ).toHandler( "users" )

Parameters:

handler - The handler to send this route to for processing

• static false

toModuleRouting

Terminate the route to be the entry point for module routing

route( "/api/v1" ).toModuleRouting( "API" );

Parameters:

module - The module to send the route to

• static false

toNamespaceRouting

Terminate the route to be the entry point for namespace routing

route( "/api/v1" ).toNamespaceRouting( "API" );

Parameters:

namespace - The namespace to send the route to

• static false

toRedirect

Redirects to a route or full HTTP URL if the pattern matched

route( "old" ).toRedirect( "/api/new" );
route( "old" ).toRedirect( "/api/new", 302 );
route( "old" ).toRedirect( "https://www.ortussolutions.com");
route( "/users/:id" ).toRedirect( function( route, params, event ){
return "/api/users/#params.id#";
})

Parameters:

target - The target URI

statusCode - The statusCode to use, defaults to 301

• static false

toResponse

Terminates the route to execute a response closure with optional status codes and texts

route( "old" ).toResponse( ( event, rc, prc ) => {
...
return "html/data"
} );

Parameters:

body - The body of the response a lambda or closure

statusCode - The status code to use, defaults to 200

Throws:

InvalidArgumentException

• static false

toView

Send a route to a view/layout combo

route( "hello", "main.index" ).toView( "hello" );
route( "hello", "main.index" ).toView( view="hello", layout="rest" );
route( "hello", "main.index" ).toView( view="hello", noLayout=true );

Parameters:

view - The view to render

layout - The layout to use or default one

noLayout - Use only the view or attach the layout

viewModule - The module the view comes from

layoutModule - The module the layout comes from

• static false

valuePairTranslation

Turns on/off the value pair translator from extra metadata in a URL

route( "hello", "main.index" ).valuePairTranslation( false );

Parameters:

toggle - The boolean toggle

• static false

with Deprecated

Starts a with closure, where all arguments will be prefixed for the next concatenated addRoute() methods until an endWith() is called

Deprecated:

This has been deprecated in favor of the group() function.

Parameters:

pattern - The pattern to match against the URL.

handler - The handler to execute if pattern matched.

action - The action in a handler to execute if a pattern is matched. This can also be a structure based on the HTTP method(GET,POST,PUT,DELETE). ex: {GET:'show', PUT:'update', DELETE:'delete', POST:'save'}

packageResolverExempt - If this is set to true, then the interceptor will not try to do handler package resolving. Else a package will always be resolved. Only works if :handler is in a pattern

matchVariables - A string of name-value pair variables to add to the request collection when this pattern matches. This is a comma delimited list. Ex: spaceFound=true,missingAction=onTest

view - The view to dispatch if pattern matches. No event will be fired, so handler,action will be ignored.

viewNoLayout - If view is chosen, then you can choose to override and not display a layout with the view. Else the view renders in the assigned layout.

valuePairTranslation - Activate convention name value pair translations or not. Turned on by default

constraints - A structure of regex constraint overrides for variable placeholders. The key is the name of the variable, the value is the regex to try to match.

module - The module to add this route to

moduleRouting - Called internally by addModuleRoutes to add a module routing route.

namespace - The namespace to add this route to

namespaceRouting - Called internally by addNamespaceRoutes to add a namespaced routing route.

ssl - Makes the route an SSL only route if true, else it can be anything. If an ssl only route is hit without ssl, the interceptor will redirect to it via ssl

append - Whether the route should be appended or pre-pended to the array. By default we append to the end of the array

domain - The domain to match, including wildcards

Returns:

Router

• static false

withAction

Registers a pattern into a specific action for execution. The action string can be a single action or a struct of HTTP Verb to actions map. Usually this is called to keep track of actions throughout a route definition and then follow it with a handler terminator or the global terminator: `end()`
Please see examples below:

route( "api/user" ).\withAction( { get : "index", delete : "delete" } ).toHandler( "User" );
route( "api/user/details" ).withAction( "details" ).toHandler( "User" );
route( "api/:handler" ).withAction( "index" ).end();

Parameters:

action - The action string or the action struct of HTTP verbs matching an action

• static false

withCondition

Registers a closure/lambda that will be called once the route matches to verify if we can proceed and execute its terminators. The closure/lambda must return boolean

route( "hello", "main.index" ).withCondition( () => return false )

Parameters:

condition - closure or lambda

• static false

withDomain

Registers a pattern that must exist under a domain pattern

route( "hello", "main.index" ).withDomain( ":username.forgebox.dev" )

Parameters:

domain - The domain construct

• static false

withHandler

Registers a pattern into a specific handler for execution. The handler string can include dot notations for folder paths or even a module `:` designator. Usually this is called if you want to delegate a route to a specific action terminator `toAction()`. This action can be a single action or a struct of HTTP Verbs to action maps. Please note that this is NOT the same as using the `toHandler()` terminator, which terminates the route addition to a specific handler.
Please see examples below:

route( "api/user" ).withHandler( "User" ).toAction( { get : "index", delete : "delete" } );
route( "api/user/details" ).withHandler( "User" ).toAction( "details" );

Parameters:

handler - The handler syntax

• static false

withModule

Registers a pattern into a specific module routing table

route( "hello", "main.index" ).withModule( "explorer" )

Parameters:

name - The module name

• static false

withNamespace

Registers a pattern into a specific Namespace routing table

route( "hello", "main.index" ).withNamespace( "myAPI" )

Parameters:

name - The namespace name

• static false

withSSL

Forces SSL on the route

route( "hello", "main.index" ).withSSL()

• static false

withVerbs

Restricts the route to specific HTTP Verbs. Just pass a list of allowed verbs

route( "hello", "main.index" ).withVerbs( "GET,POST,PUT" );

Parameters:

verbs - The list of HTTP Verbs

• static false