A module can also include one or more custom routing files in order to take advantage of our routing DSL and also have better separation as they will be stored outside of the module configuration object. You do this by giving the path to the custom file to include in your routes structure:
This will look for a routes.cfm template in your module's config folder and load it. Please note that you do not need to specify a .cfm if you don't want to. You can load as many route files as you like.
If you want to use the ColdBox 5 Router.cfc inside your module you can simply place the Router.cfc inside the config folder and it will load by convention.
By now, we should all know the default SES route ColdBox offers: addRoute(":handler/:action?"). This means that we can target a handler with or without a package and an action for execution. In ColdBox we have also added a package resolver that will detect this pattern for module and package directories so we can do URL safe and SES friendly URLs for these executions by convention.
If we do not have this feature, this is how the URLs would look like:
However, thanks to package resolving in the SES interceptor we can do links like this:
Much better and nicer huh? Of course! So potentially, with one route we could write entire applications.
All modules have the capability to leverage URL routing in a portable manner. They will automatically register an entry point URL pattern via the this.entryPoint setting. If an incoming URL has that specific pattern, then it will search for the module's routing table for a match.
You can also add these entry points manually in the host application's routing file: config/Routes.cfm. However, you will loose all module portability. We do this by using a method called addModuleRoutes() method.
addModuleRoutes(pattern, module) : Insert the module routes at this location in the configuration file with the applied URL pattern.
The URL pattern is the normal URL Mappings pattern we are used to and the module is the name of the module you want to target. What this does is create an entry point pattern that will identify the module's routing capabilities. For example, we create the following:
What the previous method calls do is bind a static URL entry pattern to a module. So if the framework detects an incoming URL with the starting point to be /blog, it will then match the simpleblog routes. Once matched, it will now try to match the rest of the incoming URL with the module's custom routes. Let's do a full example, below are some custom routes for my blog module in its ModuleConfig.cfc:
Now, let's say the URL that is incoming is:
Then this will resolve to the /blog pattern in the host that says, now look in the module simpleblog for routes. The left over part of the URL is nothing or / so the pattern that matches is my first declared pattern:
This means, that we will execute the modules' blog handler and the showPosts method. Now, let's say the next URL that comes is:
Then this will match the simpleblog module via the static /blog entry point and then it tries to find a match for /2009/09 in the modules' routes and it does!