Routing
Masonite ships with a really powerful routing engine. Routing helps link a browser URL to its controller and controller action.
Routes are created by importing the
Route class and defining the HTTP verb you would like with the URL and the controller you would like to use. These routes need to be wrapped in a ROUTES list inside your routes file.The first parameter is the URL you would like to be available in your application. In the above example, this will allow anybody to go to the
/welcome URL.You may choose to define any one of the available verbs:
Route.get('/welcome', '[email protected]')
Route.post('/welcome', '[email protected]')
Route.put('/welcome', '[email protected]')
Route.patch('/welcome', '[email protected]')
Route.delete('/welcome', '[email protected]')
Route.options('/welcome', '[email protected]')
Route.view('/url', 'view.name', {'key': 'value'})
Route.resource('/users', 'UsersController')
Route.api('/users', 'UsersApiController')
In addition to these route verbs you can use built in routes:
Route.redirect('/old', '/new', status=301)
Route.permanent_redirect('/old', '/new')
There are multiple ways to bind a controller to a route.
You can use a string binding defining the controller class and its method
{ControllerClass}@{controller_method}:Route.get('/welcome', '[email protected]')
When using string binding, you must ensure that this controller class can be imported correctly and that the controller class is in a registered controller location.
Note that this is the prefered way as it will avoid circular dependencies as no import is required in your route file.
You can import your controllers in your route file and provide a class name or a method class:
from app.controllers import WelcomeController
Route.get('/welcome', WelcomeController)
Here as no method has been defined the
__call__ method of the class will be bound to this route. It means that you should define this method in your controller:class WelcomeController(Controller):
def __call__(self, request:Request):
return "Welcome"
For convenience, you can provide the method class instead:
from app.controllers import WelcomeController
Route.get('/welcome', WelcomeController.show)
You can also bind the route to a controller instance:
from app.controllers import WelcomeController
controller = WelcomeController()
Route.get('/welcome', controller)
Here as no method has been defined the
__call__ method of the class will be bound to this route. It means that you should define this method in your controller:class WelcomeController(Controller):
def __call__(self, request:Request):
return "Welcome"
You may define several available methods on your routes to modify their behavior during the request.
Route.get('/welcome', '[email protected]').middleware('web')
Route.get('/settings', '[email protected]').middleware('auth', 'web')
This will attach the middleware key(s) to the route which will be picked up from your middleware configuration later in the request.
Route.get('/about', '[email protected]').exclude_middleware('auth', 'custom')
You can specify a name for your route. This is used to easily compile route information in other parts of your application by using the route name which is much more static than a URL.
Route.get('/welcome', '[email protected]').name('welcome')
You can specify the parameters in the URL that will later be able to be retrieved in other parts of your application. You can do this easily by specify the parameter name attached to a
@ symbol:Route.get('/dashboard/@user_id', '[email protected]')
Sometimes you want to optionally match routes and route parameters. For example you may want to match
/dashboard/user and /dashboard/user/settings to the same controller method. In this event you can use optional parameters which are simply replacing the @ symbol with a ?:Route.get('/dashboard/?option', '[email protected]')
You can specify the subdomain you want this route to be matched to. If you only want this route to be matched on a "docs" subdomain (docs.example.com):
Route.get('/dashboard/@user_id', '[email protected]').domain('docs')
Route compilers are a way to match on a certain route parameter by a specific type. For example, if you only watch to match where the
@user_id is an integer. You can do this by appending a : character and compiler name to the parameter:Route.get('/dashboard/@user_id:string', '[email protected]')
Available route compilers are:
integerint(alias for integer)stringsigneduuid
You can also create your own route compilers if you want to be able to support specific regex matches for routes.
All route compilers will need to be added to the top of your
register_routes() method in your Kernel.py file. def register_routes(self):
Route.set_controller_locations(self.application.make("controllers.location"))
Route.compile("handle", r"([\@\w\-=]+)")
#..
Note: The compile methods need to happen before the routes are loaded in this method so make sure it is at the top. You may also put it in any method that appears before theregister_routes()method.
Route groups are a great way to group mulitple routes together that have similiar options like a prefix, or multiple routes with the same middleware.
A route uses the
group() method that accepts a list of routes and keyword arguments for the options:ROUTES = [
Route.group([
Route.get('/settings', '[email protected]').name('settings'),
Route.get('/monitor', '[email protected]').name('monitor'),
],
prefix="/dashboard",
middleware=['web', 'cors'],
name="dashboard."),
domain="docs"
]
The prefix and name options will prefix the options set in the routes inside the group. In the above example, the names of the routes would
dashboard.settings with a URL of /dashboard/settings and dashboard.monitor and a URL of /dashboard/monitor.Route views are a quick way to return a view quickly without needing to build a controller just to return a view:
ROUTES = [
Route.view("/url", "view.name", {"key": "value"})
]
You could optionally pass in the methods you want this to be able to support if you needed to:
ROUTES = [
Route.view("/url", "view.name", {"key": "value"}, method=["get", "post"])
]
Application routes can be listed with the
routes:list Masonite command. Routes will be displayed in a table with relevant info such as route name, methods, controller and enabled middlewares for this route.Routes can be filtered by methods:
python craft routes:list -M POST,PUT
Routes can be filtered by name:
python craft routes:list -N users
Last modified 1mo ago