Introduction

Controllers are a vital part of Masonite and is mainly what differs it from other Python frameworks which all implement the MVC structure differently. Controllers are simply classes with methods. These methods take a self parameter which is the normal self that Python methods require. Controller methods can be looked at as "function based views" if you are coming from Django as they are simply methods inside a class and work in similar ways.

Controllers have an added benefit over straight function based views as the developer has access to a full class they can manipulate however they want. In other words, controller methods may utilize class attributes, private methods and class constructors to break up and abstract logic. They provide a lot of flexibility.

Creating a Controller

Its very easy to create a controller with Masonite with the help of our craft command tool. We can simply create a new file inside app/http/controllers, name the class the same name as the file and then create a class with methods. We can also use the craft controller command to do all of that for us which is:

$ craft controller Dashboard

When we run this command we now have a new class in app/http/controllers/DashboardController.py called DashboardController. By convention, Masonite expects that all controllers have their own file since it’s an extremely easy way to keep track of all your classes since the class name is the same name as the file. This is very opionated but you can obviously put this class wherever you like.

Exact Controllers

Remember that Masonite will automatically append Controller to the end of all controllers. If you want to create the exact name of the controller then you can pass a -e or --exact flag.

$ craft controller Dashboard -e

or

$ craft controller Dashboard --exact

This will create a Dashboard controller located in app/http/controllers/Dashboard.py

Resource Controllers

Resource controllers are controllers that have basic CRUD / resource style methods to them such as create, update, show, store etc. We can create a resource controller by running:

$ craft controller Dashboard -r

or

$ craft controller Dashboard --resource

this will create a controller that looks like:

""" A Module Description """

class DashboardController: 
 """Class Docstring Description
 """

    def show(self): 
        pass

    def index(self): 
        pass

    def create(self): 
        pass

    def store(self): 
        pass

    def edit(self): 
        pass

    def update(self): 
        pass

    def destroy(self): 
        pass

Defining a Controller Method

Controller methods are very similar to function based views in a Django application. Our controller methods at a minimum should look like:

def show(self):
    pass

If you are new to Python, all controller methods must have the self parameter. The self parameter is the normal python self object which is just an instance of the current class as usual. Nothing special here.

Container Resolving

All controller methods and constructors are resolved by the container so you may also retrieve additional objects from the container by specifying them as a parameter in the method:

from masonite.request import Request
...

def show(self, request: Request):
    print(request) # Grabbed the Request object from the container

or by specifying them in the constructor:

from masonite.request import Request

class DashboardController:

    def __init__(self, request: Request):
        self.request = request

    def show(self):
        print(self.request) # Grabbed the Request object from the container

If you need a class in multiple controller methods then it is recommended to put it into the constructor in order to keep the controller DRY.

It’s important to note that unlike other frameworks, we do not have to specify our route parameters as parameters in our controller method. We can retrieve the parameters using the request.param('key') class method.

Returning JSON

You can return JSON in a few different ways. The first way is returning a dictionary which will then be parsed to JSON:

def show(self):
    return {'key': 'value'}

you may return a list:

def show(self):
    return ['key', 'value']

Or you may even return a model instance or collection. Take these 2 code snippets as an example:

from app.User import User

def show(self):
    return User.find(1)

or

from app.User import User

def show(self):
    return User.where('active', 1).get()

Returning a paginated response directly will include the collection data, along with results metadata.

Query parameters accepted are: 'page_size' and 'page'. These will be handled directly as part of the response, there is no need to pass them in explicitly.

Orator classes LengthAwarePaginator and Paginator will return slightly different responses.

LengthAwarePaginator:

from app.User import User

# with query params ?page_size=10&page=2
def index(self, request: Request):
    return User.paginate()

returns:

{
  "total": 44,
  "count": 10,
  "per_page": 10,
  "current_page": 2,
  "last_page": 5,
  "from": 11,
  "to": 20,
  "data": [ ... ]
}

Paginator:

from app.User import User

# no query params, therefore uses Orator default (15, 1)
def index(self, request: Request):
    return User.simple_paginate()

returns:

{
  "count": 15,
  "per_page": 15,
  "current_page": 1,
  "from": 1,
  "to": 15,
  "data": [ ... ]
}

Passing Route Parameters

Optionally you can pass route parameters along with your resolving code. This is useful to keep a nice clean codebase.

For example, these two code snippets are the same:

from masonite.request import Request
from masonite.view import View
...

def show(self, request: Request, view: View):
    return User.find(request.param('user_id'))

And this:

from masonite.view import View
...

def show(self, user_id, view: View):
    return User.find(user_id)

You can specify parameters along with any other container resolving.

Introduction

Masonite works on getting rid of all those mundane tasks that developers either dread writing or dread writing over and over again. Because of this, Masonite has several helper functions that allows you to quickly write the code you want to write without worrying about imports or retrieving things from the Service Container. Many things inside the Service Container are simply retrieved using several functions that Masonite sets as builtin functions which we call "Built in Helper Functions" which you may see them referred to as.

These functions do not require any imports and are simply just available which is similiar to the print() function. These functions are all set inside the HelpersProvider Service Provider.

You can continue to use these helper functions as much as you like but most developers use these to quickly mock things up and then come back to refactor later.

It may make more sense if we take a peak at this Service Provider:

Notice how we simply just add builtin functions via this provider.

Built In Helpers

The below list of helpers are "builtin" helpers meaning they are global in the same way that the print method is global. These helpers can be used without any imports.

Request

The Request class has a simple request() helper function.

is exactly the same as:

Notice we didn't import anything at the top of the file, nor did we inject anything from the Service Container.

View

The view() function is just a shortcut to the View class.

is exactly the same as:

Mail

Instead of resolving the mail class you can use the mail helper:

is exactly the same as:

Auth

The auth() function is a shortcut around getting the current user. We can retrieve the user like so:

is exactly the same as:

This will return None if there is no user so in a real world application this may look something like:

This is because you can't call the .id attribute on None

Container

We can get the container by using the container() function

is exactly the same as:

Env

We may need to get some environment variables inside our controller or other parts of our application. For this we can use the env() function.

is exactly the same as:

Resolve

We can resolve anything from the container by using this resolve() function.

is exactly the same as:

That's it! These are simply just functions that are added to Python's builtin functions.

Die and Dump

Die and dump is a common way to debug objects in PHP and other programming languages. Laravel has the concept of dd() which dies and dumps the object you need to inspect.

dd() is essentially adding a break point in your code which dumps the properties of an object to your browser.

For example we can die and dump the user we find:

You may also specify several parameters for see several values dumped at once:

If we then go to the browser and visit this URL as normal then we can now see the object fully inspected which will kill the script wherever it is in place and throw an exception but instead of showing the normal debugger it will use a custom exception handler and show the inspection of the object instead:

Non Built In Helpers

There are several helper methods that require you to import them in order to use them. These helpers are not global like the previous helpers.

Config

The config helper is used to get values in the config directory. For example in order to get the location in the config/storage.py file for example.

This function can be used to retrieve values from any configuration file but we will use the config/storage.py file as an example.

With a config/storage.py file like this:

We can get the value of the west key in the location inner dictionary like so:

Instead of importing the dictionary itself:

Optional

This helper that allows you to wrap any object in this helper and call attributes or methods on it even if they don't exist. If they exist then it will return the method, if it doesn't exist it will return None.

Take this example where we would normally write:

We can now use this code snippet instead:

Compact

Compact is a really nice helper that allows you to stop making those really repetitive dictionary statements in your controller methods

take this for example:

Notice how our Python variables are exactly the same as what we want our variables to be in our template.

With the compact function, now you can do:

You can also pass in a dictionary which will update accordingly:

Collect

You can use the same Collection class that orator uses when returning model collections. This can be used like so:

You have access to all the methods on a normal collection object.

Query String

Masonite uses this helper internally but if you find a need to parse query strings in the same way Masonite does then you can use this helper like this:

Gold Sponsors

Current Sponsors

Introduction

Masonite Routing is an extremely simple but powerful routing system that at a minimum takes a url and a controller. Masonite will take this route and match it against the requested route and execute the controller on a match.

All routes are created inside routes/web.py and are contained in a ROUTES constant. All routes consist of some form of HTTP route classes (like Get() or Post()). At the bare minimum, a route will look like:

Most of your routes will consist of a structure like this. All URI’s should have a preceding /. Routes that should only be executed on Post requests (like a form submission) will look very similar:

If you wish to not use string controllers and wish to instead import your controller then you can do so by specifying the controller as well as well as only passing a reference to the method. This will look like:

Route Options

There are a few methods you can use to enhance your routes. Masonite typically uses a setters approach to building instead of a parameter approach so to add functionality, we can simply attach more methods.

HTTP Verbs

There are several HTTP verbs you can use for routes:

Route Groups

Some routes may be very similar. We may have a group of routes under the same domain, uses the same middleware or even start with the same prefixes. In these instances we should group our routes together so they are more DRY and maintainable.

We can add route groups like so:

This alone is great to group routes together that are similar but in addition to this we can add specific attributes to the entire group like adding middleware:

In the case you are only using one middleware:

The , at the end of 'auth' ensures that it's treated as a tuple and not as an array of strings.

In this instance we are adding these 2 middleware to all of the routes inside the group. We have access to a couple of different methods. Feel free to use some or all of these options:

The prefix parameter will prefix that URL to all routes in the group as well as the name parameter. The code above will create routes like /dashboard/url1 with the name of post.create. As well as adding the domain and middleware to the routes.

All of the options in a route group are named parameters so if you think adding a groups attribute at the end is weird you can specify them in the beginning and add the routes parameter:

Multiple Route Groups

Even more awesome is the ability to nest route groups:

This will go to each layer and generate a route list essentially from the inside out. For a real world example we refactor routes from this:

into this:

This will likely be the most common way to build routes for your application.

View Routes

You can also use View routes which is just a method on the normal route class:

Redirect Route

You can also redirect right from the routes list using a Redirect route class:

Match Routes

You may have noticed above that we have a Match route class. This can match several incoming request methods. This is useful for matching a route with both PUT and PATCH.

Named Routes

We can name our routes so we can utilize these names later when or if we choose to redirect to them. We can specify a route name like so:

It is good convention to name your routes since route URI's can change but the name should always stay the same.

Route Middleware

Middleware is a great way to execute classes, tasks or actions either before or after requests. We can specify middleware specific to a route after we have registered it in our config/middleware.py file but we can go more in detail in the middleware documentation. To add route middleware we can use the middleware method like so:

This middleware will execute either before or after the route is executed depending on the middleware.

Deeper Module Controllers

All controllers are located in app/http/controllers but sometimes you may wish to put your controllers in different modules deeper inside the controllers directory. For example, you may wish to put all your product controllers in app/http/controllers/products or all of your dashboard controllers in app/http/controllers/users. In order to access these controllers in your routes we can simply specify the controller using our usual dot notation:

Global Controllers

Controllers are defaulted to the app/http/controllers directory but you may wish to completely change the directory for a certain route. We can use a forward slash in the beginning of the controller namespace:

This can enable us to use controllers in third party packages.

You can also import the class directly and reference the method you want to use:

Route Parameters

Very often you’ll need to specify parameters in your route in order to retrieve information from your URI. These parameters could be an id for the use in retrieving a certain model. Specifying route parameters in Masonite is very easy and simply looks like:

That’s it. This will create a dictionary inside the Request object which can be found inside our controllers.

In order to retrieve our parameters from the request we can use the param method on the Request object like so:

Optional Route Parameters

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 @ with a ?:

You can also set default values if the route is not hit:

Route Compilers

Sometimes you will want to make sure that the route parameter is of a certain type. For example you may want to match a URI like /dashboard/1 but not /dashboard/joseph. In order to do this we simply need to pass a type to our parameter. If we do not specify a type then our parameter will default to matching all alphanumeric and underscore characters.

This will match all integers but not strings. So for example it will match /dashboard/10283 and not /dashboard/joseph

If we want to match all strings but not integers we can pass:

This will match /dashboard/joseph and not /dashboard/128372. Currently only the integer and string types are supported.

Adding Route Compilers

We can add route compilers to our project by specifying them in a Service Provider.

Make sure you add them in a Service Provider where wsgi is False. We can add them on the Route class from the container using the compile method. A completed example might look something like this:

We just need to call the compile() method on the Route class and make sure we specify a regex string by preceding an r to the beginning of the string.

Subdomain Routing

You may wish to only render routes if they are on a specific subdomain. For example you may want example.com/dashboard to route to a different controller than joseph.example.com/dashboard.

Out of the box this feature will not work and is turned off by default. We will need to add a call on the Request class in order to activate subdomains. We can do this in the boot method of one of our Service Providers that has wsgi=False:

To use subdomains we can use the .domain() method on our routes like so:

This route will match to joseph.example.com/dashboard but not to example.com/dashboard or test.example.com/dashboard.

It may be much more common to match any subdomain. For this we can pass in an asterisk instead.

This will match all subdomains such as test.example.com/dashboard, joseph.example.com/dashboard but not example.com/dashboard.

If a match is found, it will also add a subdomain parameter to the Request class. We can retrieve the current subdomain like so:

Introduction

Masonite tries to make static files extremely easy and comes with whitenoise out of the box. Whitenoise wraps the WSGI application and listens for certain URI requests that can be resistered in your configuration files.

Configuration

All configurations that are specific to static files can be found in config/storage.py. In this file you'll find a constant file called STATICFILES which is simply a dictionary of directories as keys and aliases as the value.

The directories to include as keys is simply the location of your static file locations. For example, if your css files are in storage/assets/css then put that folder location as the key. For the value, put the alias you want to use in your templates. For this example, we will use css/ as the alias.

For this setup, our STATICFILES constant should look like:

STATICFILES = {
    'storage/assets/css': 'assets/',
}

Now in our templates we can use:

<img src="/assets/style.css">

Which will get the storage/assets/css/style.css file.

Static Template Function

All templates have a static function that can be used to assist in getting locations of static files. You can specify the driver and locations you want using the driver name or dot notation.

Take this for example:

....
's3': {
  's3_client': 'sIS8shn...'
  ...
  'location': 'https://s3.us-east-2.amazonaws.com/bucket'
  },
....

...
<img src="{{ static('s3', 'profile.jpg') }}" alt="profile">
...

this will render:

<img src="https://s3.us-east-2.amazonaws.com/bucket/profile.jpg" alt="profile">

You can also make the config location a dictionary and use dot notation:

....
's3': {
  's3_client': 'sIS8shn...'
  ...
  'location': {
    'east': 'https://s3.us-east-2.amazonaws.com/east-bucket',
    'west': 'https://s3.us-west-16.amazonaws.com/west-bucket'
  },
....

and use the dot notation like so:

...
<img src="{{ static('s3.east', 'profile.jpg') }}" alt="profile">
...
<img src="{{ static('s3.west', 'profile.jpg') }}" alt="profile">
...

Serving "Root" Files

Sometimes you may need to serve files that are normally in the root of your application such as a robots.txt or manifest.json. These files can be aliased in your STATICFILES directory in config/storage.py. They do not have to be in the root of your project but instead could be in a storage/root or storage/public directory and aliased with a simple /.

For example a basic setup would have this as your directory:

resources/
routes/
storage/
  static/
  root/
    robots.txt
    manifest.json

and you can alias this in your STATICFILES constant:

STATICFILES = {
    # folder          # template alias
    'storage/static': 'static/',
    ...
    'storage/root': '/'
}

You will now be able to access localhost:8000/robots.txt and you will have your robots.txt served correctly and it can be indexed by search engines properly.

Thats it! Static files are extremely simple. You are now a master at static files!

Requests

Introduction

The Request class is initialized when the server first starts and is modified on every request. This means that the Request class acts as a singleton and is not reinitialized on every request. This presents both pros and cons during developing Masonite. It's great to not have to worry about a new object being instantiated every time but the con is that some attributes need to be reset at the end of the request.

The Request class is loaded into the IOC container first so any Service Provider will have access to it. The IOC container allows all parts of the framework to be resolved by the IOC container and auto inject any dependencies they need.

Getting Started

The Request class is bound into the IOC container once when the server is first started. This takes the WSGI environment variables generated by your WSGI server as a parameter. Because of this, we reload the WSGI values on every request but the actual Request object does not change. In other words, the memory address of the Request object is always the same but the class attributes will change of every request. This is done already for you by the Masonite framework itself. This Request class is bound and initialized inside the AppProvider Service Provider. We grab this request object by simply passing in Request into the parameters of anything resolved by the Service Container such as middleware, drivers and controller methods like so:

def show(self, request: Request):
    request #== <masonite.request.Request>

Masonite is smart enough to know that we need the Request class and it will inject it into our method for us.

Helper Function

Masonite ships with a HelpersProvider Service Provider which adds several helper functions. One of these helper functions is the request() function. This function will return the request object. Because of this, these two pieces of code are identical:

def show(self, request: Request):
    request.input('username')

def show(self):
    request().input('username')

Notice we didn't import anything at the top of our file and also didn't retrieve any objects from the IOC container. Masonite helper functions act just like any other built in Python function.

Usage

The Request has several helper methods attached to it in order to interact with various aspects of the request.

In order to get the current request input variables such as the form data during a POST request or the query string during a GET request looks like:

def show(self, request: Request):
    request.input('username')

Input Data

We can get all the request input variables such as input data from a form request or GET data from a query string. Note that it does not matter what HTTP method you are using, the input method will know what input data to get dependent on the current HTTP method (GET, POST, PUT, etc)

This will return all the available request input variables for that request as a dictionary.

# GET: /dashboard?user=Joe&status=1

def show(self, request: Request):
    return request.all() # {'user': 'Joe', 'status': '1'}

This method will get all of the request input variables to include any internal framework variables completely handled internally such as __token and __method. You can exclude them by passing in False into the method or specifying it explicitly:

# GET: /dashboard?user=Joe&status=1&__token=837674634

def show(self, request: Request):
    return request.all(internal_variables=False) # {'user': 'Joe', 'status': '1'}

To get a specific input:

# GET: /dashboard?firstname=Joe

def show(self, request: Request):
    return request.input('firstname') # Joe

Query Strings

Sometimes you want to only get the query strings or access the query strings. These can be times where you are posting to POST: /dashboard?firstname=Joe and want to access both the POST input AND the URL query strings.

You can do so simply:

# POST: /dashboard?firstname=Joe

def show(self, request: Request):
    request.query('firstname') # Joe
    request.query('firstname', 'default') # Joe
    request.query('lastname', 'default') # default

There may be times you have multiple parameters you need to fetch. By default Masonite will only fetch the first one but you may have an example like this:

# POST: /dashboard?firstname=Joe&firstname=Bob

def show(self, request: Request):
    request.query('firstname') # Joe
    request.query('firstname', multi=True) # ['Joe', 'Bob']

You may also get all the query params:

# POST: /dashboard?firstname=Joe

def show(self, request: Request):
    return request.all_query() # {'firstname': 'Joe'}

Input Cleaning

Input data will be cleaned of HTML tags and other security measures. This may cause unwanted return values if you are expecting something like a JSON string. If you want to opt to not clean the input you can specify that as a keyword argument:

request.input('firstname', clean=False) # Joe

Quotes

By default, Masonite will clean quotes in order to sanitize the input. If you would to preserve quotes you can set whether you would like quotes to be cleaned. A value of False will keep the quotes:

request.input('firstname', quotes=False)

To check if some request input data exists:

# GET: /dashboard?firstname=Joe

def show(self, request: Request):
    return request.has('firstname') # True

Getting Dictionary Input

If your input is a dictionary you have two choices how you want to access the dictionary. You can either access it normally:

request.input('payload')['user']['address'] # 123 Smith Rd

Or you can use dot notation to fetch the value for simplicity:

request.input('payload.user.address') # 123 Smith Rd

You can also use a * wildcard to get all values from a dictionary list. Take this code example:

"""
Payload: 
"user": {
    "id": 1,
    "addresses": [
        {"id": 1, 'street': "A Street"},
        {"id": 2, 'street': "B Street"}
    ] 
}
"""

request.input('user.addresses.*.id') # [1,2]

You may also use list indexes to fetch data:

"""
Payload: 
"user": {
    "id": 1,
    "addresses": [
        {"id": 1, 'street': "A Street"},
        {"id": 2, 'street': "B Street"}
    ] 
}
"""

request.input('user.addresses.2.street') # B Street

Only

You can only get a certain set of parameters if you have a need to do so. This can be used like:

# GET: /dashboard?firstname=Joe&lastname=Mancuso&active=1

def show(self, request: Request):
    return request.only('firstname', 'active') # {'firstname': 'Joe', 'active': '1'}

Without

We can specify a set of parameters to exclude from the inputs returned. For example:

# GET: /dashboard?firstname=Joe&lastname=Mancuso&active=1

def show(self, request: Request):
    return request.without('lastname') # {'firstname': 'Joe', 'active': '1'}

Notice it returned everything besides lastname.

URL Parameters

To get the request parameter retrieved from the url. This is used to get variables inside: /dashboard/@firstname for example.

# Route: /dashboard/@firstname
# GET: /dashboard/Joe

def show(self, request: Request):
    return request.param('firstname') # Joe

JSON Payloads

Sometimes you may want to handle incoming JSON requests. This could be form external API's like Github.

Masonite will detect that an incoming request is a JSON request and put the cast the JSON to a dictionary and load it into the payload request input. For example if you have an incoming request of:

{
    "name": "Joe",
    "email": "Joe@email.com"
}

Then we can fetch this input in a controller using the normal input() method like so:

def show(self, request: Request):
    request.input('name') # Joe

Cookies

You may also set a cookie in the browser. The below code will set a cookie named key to the value of value.

Creating

def show(self, request: Request):
    return request.cookie('key', 'value')

Not Encrypting

If you choose to not encrypt your values and create cookies with the plain text value then you can pass a third value of True or False. You can also be more explicit if you like:

def show(self, request: Request):
    return request.cookie('key', 'value', encrypt=False)

Expirations

All cookies are set as session cookies. This means that when the user closes out the browser completely, all cookies will be deleted.

def show(self, request: Request):
    return request.cookie('key', 'value', expires="5 minutes")

This will set a cookie thats expires 5 minutes from the current time.

HttpOnly

Again, as a security measure, all cookies automatically are set with the HttpOnly flag which makes it unavailable to any Javascript code. You can turn this off:

def show(self, request: Request):
    return request.cookie('key', 'value', http_only=False)

This will now allow Javascript to read the cookie.

Reading

You can get all the cookies set from the browser

def show(self, request: Request):
    return request.get_cookies()

You can get a specific cookie set from the browser

def show(self, request: Request):
    return request.get_cookie('key')

Again, all cookies are encrypted by default so if you set a cookie with encryption then this method will decrypt the cookie. If you set a cookie in plain text then you should pass the False as the second parameter here to tell Masonite not to decrypt your plain text cookie value.:

def show(self, request: Request):
    return request.get_cookie('key', decrypt=False)

This will return the plain text version of the cookie.

Deleting

You may also delete a cookie. This will remove it from the browser.

def show(self, request: Request):
    return request.delete_cookie('key')

User

You can also get the current user from the request. This requires the LoadUserMiddleware middleware which is in Masonite by default. This will return an instance of the current user.

def show(self, request: Request):
    return request.user()

Routes

You can also get a route URL via the route name. Let's say we have a route like this:

Get('/dashboard').name('dashboard')

We can get the URL from the route name like so:

def show(self):
    request().route('dashboard') # /dashboard

Route Parsing

if we have route parameters like this:

Get('/dashboard/@user').name('dashboard.user')

then we can pass in a dictionary:

def show(self, request: Request):
    request.route('dashboard.user', {'user': 1}) # /dashboard/1

You may also pass a list if that makes more sense to you:

def show(self, request: Request):
    request.route('dashboard.user', [1]) # /dashboard/1

This will inject that value for each parameter in order. For example if we have this route:

Get('/dashboard/@user/@id/@slug').name('dashboard.user')

then we can use:

def show(self, request: Request):
    request.route('dashboard.user', [1, 2, 'some-slug']) 
    # /dashboard/1/2/some-slug

Contains

We can also check if a route contains a specific pattern:

# GET /dashboard/user/1
def show(self, request: Request):
    request.contains('/dashboard/*/1') #== True

You can also use this in a template and pass in a show parameter to return a string instead. This is useful if you want to show active status classes depending on the current route:

<a href=".." class="{{ request().contains('/dashboard/*/edit', show='active')">
<a href=".." class="{{ request().contains('/dashboard/*/create', show='active')">

Current URL

We can get the current url with:

def show(self, request: Request):
    return request.path #== /dashboard/user

Redirection

You can specify a url to redirect to

def show(self, request: Request):
    return request.redirect('/home')

If the url contains http than the route will redirect to the external website

def show(self, request: Request):
    return request.redirect('http://google.com')

You can redirect to a named route

def show(self, request: Request):
    return request.redirect_to('dashboard')

You can also use the name parameter on the redirect method:

def show(self, request: Request):
    return request.redirect(name="dashboard")

You can also redirect to a specific controller. This will find the URL that is attached to the controller method

def show(self, request: Request):
    return request.redirect(controller="WelcomeController@show")

Sometimes your routes may require parameters passed to it such as redirecting to a route that has a url like: /url/@firstname:string/@lastname:string.

Redirecting to a named route with URL parameters:

def show(self, request: Request):
    return request.redirect_to('dashboard', {'firstname': 'Joseph', 'lastname': 'Mancuso'})

Redirecting to a url in your application with URL parameters:

def show(self, request: Request):
    return request.redirect('dashboard/@id', {'id': '1'})

Form Back Redirection

Masonite will check for a __back input and redirect to that route. We can specify one using the back() view helper function:

<form action="{{ route('dashboard.create') }}" method="POST">
    {{ csrf_field }}
    {{ back() }}
</form>

By default the back helper will return the current path so you can easily go back to the previous page after the form is submitted.

You can also specify a path to go back to:

<form action="{{ route('dashboard.create') }}" method="POST">
    {{ csrf_field }}
    {{ back('/another/path') }}
</form>

Redirecting Back

After submitting the form you can redirect back to wherever the back template method was pointing to using the back() method:

def show(self, request: Request):
    ...
    return request.back()

This will also flash the current inputs to the session. You can then get the inputs using the {{ old('key') }} template helper:

<form>
  <input type="text" name="email" value="{{ old ('email') }}">
  ...
</form>

Redirecting Back To Intended Routes

There are times where you want your user to visit a page where they must be logged in. You may have a check in your controller to redirect a user to the login page if they are not authenticated. You may easily redirect them back to the intended page after they login.

To activate the intended route you simply need to append .then_back() after the redirection. For example you may have this:

Assume the current URL is /dashboard

from masonite.request import Request

class DashboardController:

    def show(self, request: Request):
        if not self.request.user():
            return request.redirect('/login').then_back()

When you go to your login page you'll need to have the normal {{ back() }} form helper:

<form action="{{ route('login') }}" method="POST">
    {{ csrf_field }}
    {{ back() }}
    ...
</form>

In your LoginController (or wherever this form submits to) you simply need to use the redirect_intended method on the request class:

from masonite.request import Request

class LoginController(Controller):

    def store(self, request: Request)
        # ...
        if auth.login(request.input('email'), request.input('password')):
            return request.redirect_intended(default='/home')

This will redirect to the /dashboard route (because that was the intended route). If no route is intended then it will simply redirect to the default you specify (which is /home).

Redirecting Back With Errors

You can redirect back with validation error message or redirect back with input value:

def show(self, request: Request):
    errors = request.validate(
        required(['email', 'password'])
    )

    if errors:
        return request.back().with_errors(errors)

Redirecting Back With Inputs

When redirecting back there are times where you will also want to flash the inputs to the session. With this you can simply use the back() method but if you want a bit more control you can use the with_input() method.

def show(self, request: Request):
    errors = request.validate(
        required(['email', 'password'])
    )

    if errors:
        return request.redirect('/dashboard/errors').with_input()

You can then get the inputs using the {{ old('key') }} template helper:

<form>
  <input type="text" name="email" value="{{ old ('email') }}">
  ...
</form>

Default Back URL

We can also specify a default route just in case a form submitted does not specify one using a form helper:

def show(self, request: Request):
    return request.back(default='/hit/route')

This will check for the __back input and if it doesn't exist it will use this default route. This is the same as a redirect if you don't use the back() helper.

Encryption Key

You can load a specific secret key into the request by using:

request.key(key)

This will load a secret key into the request which will be used for encryptions purposes throughout your Masonite project.

Headers

You can also get and set any headers that the request has.

You can get all WSGI information by printing:

def show(self, request: Request):
    print(request.environ)

This will print the environment setup by the WSGI server. Use this for development purposes.

You can also get a specific header:

def show(self, request: Request):
    request.header('AUTHORIZATION')

This will return whatever the HTTP_AUTHORIZATION header if one exists. If that does not exist then the AUTHORIZATION header will be returned. If that does not exist then None will be returned.

We can also set headers:

def show(self, request: Request):
    request.header('AUTHORIZATION', 'Bearer some-secret-key')

request.header('AUTHORIZATION', 'Bearer some-secret-key')

This will set the AUTHORIZATION header instead of the HTTP_AUTHORIZATION header.

You can also set headers with a dictionary:

request.header({
    'AUTHORIZATION': 'Bearer some-secret-key',
    'Content-Type': 'application/json'
})

Status Codes

Masonite will set a status code of 404 Not Found at the beginning of every request. If the status code is not changed throughout the code, either through the developer or third party packages, as it passes through each Service Provider then the status code will continue to be 404 Not Found when the output is generated. You do not have to explicitly specify this as the framework itself handles status codes. If a route matches and your controller method is about to be hit then Masonite will set 200 OK and hit your route. This allows Masonite to specify a good status code but also allows you to change it again inside your controller method.

You could change this status code in either any of your controllers or even a third party package via a Service Provider.

For example, the Masonite Entry package sets certain status codes upon certain actions on an API endpoint. These can be 429 Too Many Requests or 201 Created. These status codes need to be set before the StartProvider is ran so if you have a third party package that sets status codes or headers, then they will need to be placed above this Service Provider in a project.

If you are not specifying status codes in a package and simple specifying them in a controller then you can do so freely without any caveats. You can set status codes like so:

request.status('429 Too Many Requests')

You can also use an integer which will find the correct status code for you:

request.status(429)

This snippet is exactly the same as the string based snippet above.

This will set the correct status code before the output is sent to the browser. You can look up a list of HTTP status codes from an online resource and specify any you need to. There are no limitations to which ones you can use.

Get Request Method Type

You can get the request method simply:

# PUT: /dashboard

def show(self, request: Request):
    return request.get_request_method() # 'PUT'

Changing Request Methods in Forms and URLs

Typically, forms only have support for GET and POST. You may want to change what HTTP method is used when submitting a form such as PATCH.

This will look like:

<form action="/dashboard" method="POST">
    <input type="hidden" name="__method" value="PATCH">
</form>

or you can optionally use a helper method:

<form action="/dashboard" method="POST">
    {{ request_method('PATCH') }}
</form>

When the form is submitted, it will process as a PATCH request instead of a POST request.

This will allow this form to hit a route like this:

from masonite.routes import Patch

ROUTES = [
    Patch('/dashboard', 'DashboardController@update')
]

You can also specify the request method in the query string of the url to change it on a link:

<a href="/dashboard?__method=PATCH" rel="nofollow">Dashboard patch</a>

This link will use the same route as above.

Request Information

You can get information related to the request like the scheme, domain and other attribute by accessing them right from the request class:

Getting Domain Information

You can get different parts of the domain using the below methods:

request.scheme() # https
request.host() # www.masonitecasts.com
request.port() # 8000

Path Information

You can easily get the current path and query string information:

request.full_path() # /dashboard/hello%20world
request.full_path(quoted=False) # /dashboard/hello world
request.query_string() # email=joe@masoniteproject.com
request.url() # www.masonitecasts.com/dashboard/hello%20world
request.url(include_standard_port=True) # www.masonitecasts.com:443/dashboard/hello%20world
request.full_url() # https://www.masonitecasts.com/dashboard/hello%20world

Validation

There is a convenient helper method you can use the validate the request. You can import the Validator class and use validation like so:

from masonite.request import Request
from masonite.validation import Validator

def show(self, request: Request, validate: Validator):
    errors = request.validate(
      validate.required('user')
    )

    if errors:
      return request.back().with_errors(errors)

Preface

This section of the documentation will contain various tutorials. These are guides that are designed to take you from beginning to end on building various types of projects with Masonite. We may not explain things in much detail for each section as this part of the documentation is designed to just get you familiar with the inner workings of Masonite.

Since this section of the documentation is designed to just get you up and coding with Masonite, any further explanations that should be presented are inside various "hint blocks." Once you are done with the tutorial or simply want to learn more about a topic it is advised that you go through each hint block and follow the links to dive deeper into the reference documentation which does significantly more explaining.

Hint Blocks

You will see various hint blocks throughout the tutorials. Below are examples of what the various colors represent.

Installation

Creating a Blog

In this tutorial we will walk through how to create a blog. We will touch on all the major systems of Masonite and it should give you the confidence to try the more advanced tutorials or build an application yourself.

Routing

Typically your first starting point for your Masonite development flow will be to create a route. All routes are located in routes/web.py and are extremely simple to understand. They consist of a request method and a route method. Routing is simply stating what incoming URI's should direct to which controllers.

For example, to create a GET request route it will look like:

from masonite.routes import Get

Get('/url', 'Controller@method')

We'll talk more about the controller in a little bit.

Creating our Route:

We will start off by creating a view and controller to create a blog post.

A controller is a simple class that holds controller methods. These controller methods will be what our routes will call so they will contain all of our application's business logic.

Let's create our first route now. We can put all routes inside routes/web.py and inside the ROUTES list. You'll see we have a route for the home page. Let's add a route for creating blogs.

ROUTES = [
    Get('/', 'WelcomeController@show').name('welcome'),

    # Blog Routes
    Get('/blog', 'BlogController@show')
]

You'll notice here we have a BlogController@show string. This means "use the blog controller's show method to render this route". The only problem here is that we don't yet have a blog controller.

Creating a Controller

All controllers are located in the app/http/controllers directory and Masonite promotes 1 controller per file. This has proven efficient for larger application development because most developers use text editors with advanced search features such as Sublime, VSCode or Atom. Switching between classes in this instance is simple and promotes faster development. It's easy to remember where the controller exactly is because the name of the file is the controller.

You can of course move controllers around wherever you like them but the craft command line tool will default to putting them in separate files. If this seems weird to you it might be worth a try to see if you like this opinionated layout.

Creating Our First Controller

Like most parts of Masonite, you can scaffold a controller with a craft command:

$ craft controller Blog

This will create a controller in app/http/controllers directory that looks like this:

"""A BlogController Module."""

from masonite.request import Request
from masonite.view import View
from masonite.controllers import Controller


class BlogController(Controller):
    """BlogController Controller Class."""

    def __init__(self, request: Request):
        """BlogController Initializer

        Arguments:
            request {masonite.request.Request} -- The Masonite Request class.
        """
        self.request = request

    def show(self, view: View):
        pass

Simple enough, right? You'll notice we have a show method we were looking for. These are called "controller methods" and are similiar to what Django calls a "view."

But also notice we now have our show method that we specified in our route earlier.

Returning a View

We can return a lot of different things in our controller but for now we can return a view from our controller. A view in Masonite are html files or "templates". They are not Python objects themselves like other Python frameworks. Views are what the users will see (or view).

This is important as this is our first introduction to Python's IOC container. We specify in our parameter list that we need a view class and Masonite will inject it for us.

For now on we won't focus on the whole controller but just the sections we are worried about. A ... means there is stuff in between code that we are not worried about:

from masonite.view import View 
...
def show(self, view: View):
    return view.render('blog')

Notice here we "type hinted" the View class. This is what Masonite calls "Auto resolving dependency injection". If this doesn't make sense to you right now don't worry. The more you read on the more you will understand.

Creating Our View

You'll notice now that we are returning the blog view but it does not exist yet.

All views are in the resources/templates directory. We can create a new file called resources/templates/blog.html or we can use another craft command:

$ craft view blog

This will create that template we wanted above for us.

We can put some text in this file like:

This is a blog

and then run the server

$ craft serve

and open up http://localhost:8000/blog. You will see "This is a blog" in your web browser.

Authentication

Most applications will require some form of authentication. Masonite comes with a craft command to scaffold out an authentication system for you. This should typically be ran on fresh installations of Masonite since it will create controllers routes and views for you.

For our blog, we will need to setup some form of registration so we can get new users to start posting to our blog. We can create an authentication system by running the craft command:

$ craft auth

We should get a success message saying that some new assets were created. You can check your controllers folder and you should see a few new controllers there that should handle registrations.

We will check what was created for us in a bit.

Database Setup

In order to register these users, we will need a database. Hopefully you already have some kind of local database setup like MySQL or Postgres but we will assume that you do not. In this case we can just use SQLite.

Now we just need to change a few environment variables so Masonite can create the SQLite database.

These environment variable can be found in the .env file in the root of the project. Open that file up and you should see a few lines that look like:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=masonite
DB_USERNAME=root
DB_PASSWORD=root

Go ahead and change those setting to your connection settings by adding sqlite to the DB_CONNECTION variable and whatever you want for your database which will be created for you when you migrate. We will call it blog.db:

DB_CONNECTION=sqlite
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=blog.db
DB_USERNAME=root
DB_PASSWORD=root

Migrating

Once you have set the correct credentials, we can go ahead and migrate the database. Out of the box, Masonite has a migration for a users table which will be the foundation of our user. You can edit this user migration before migrating but the default configuration will suit most needs just fine and you can always add or remove columns at a later date.

$ craft migrate

This will create our users table for us along with a migrations table to keep track of any migrations we add later.

Creating Users

Now that we have the authentication and the migrations all migrated in, let's create our first user. Remember that we ran craft auth so we have a few new templates and controllers.

Go ahead and run the server:

$ craft serve

Username: demo
Email: demo@email.com
Password: password

Migrations

Now that we have our authentication setup and we are comfortable with migrating our migrations, let's create a new migration where we will store our posts.

Our posts table should have a few obvious columns that we will simplify for this tutorial part. Let's walk through how we create migrations with Masonite.

Craft Command

$ craft migration create_posts_table --create posts

This command simply creates the start of a migration that will create the posts table. By convention, table names should be plural (and model names should be singular but more on this later).

This will create a migration in the databases/migrations folder. Let's open that up and starting on line 6 we should see something that looks like:

def up(self):
    """
    Run the migrations.
    """
    with self.schema.create('posts') as table:
        table.increments('id')
        table.timestamps()

Lets add a title, an author, and a body to our posts tables.

def up(self):
    """
    Run the migrations.
    """
    with self.schema.create('posts') as table:
        table.increments('id')
        table.string('title')

        table.integer('author_id').unsigned()
        table.foreign('author_id').references('id').on('users')

        table.string('body')
        table.timestamps()

Now we can migrate this migration to create the posts table

$ craft migrate

Models

Now that we have our tables and migrations all done and we have a posts table, let's create a model for it.

Models in Masonite are a bit different than other Python frameworks. Masonite uses Orator which is an Active Record implementation of an ORM. This bascially means we will not be building our model and then translating that into a migration. Models and migrations are separate in Masonite. Our models will take shape of our tables regardless of what the table looks like.

Creating our Model

Again, we can use a craft command to create our model:

$ craft model Post

Notice we used the singular form for our model. By default, Orator will check for the plural name of the class in our database (in this case posts) by simply appending an "s" onto the model. We will talk about how to specify the table explicitly in a bit.

The model created now resides inside app/Post.py and when we open it up it should look like:

"""A Post Database Model."""
from config.database import Model

class Post(Model):
    pass

Simple enough, right? Like previously stated, we don't have to manipulate the model. The model will take shape of the table as we create or change migrations.

Table Name

Again, the table name that the model is attached to is the plural version of the model (by appending an "s") but if you called your table something different such as "blog" instead of "blogs" we can specify the table name explicitly:

"""A Post Database Model."""
from config.database import Model

class Post(Model):
    __table__ = 'blog'

Mass Assignment

Orator by default protects against mass assignment as a security measure so we will explicitly need to set what columns we would like to be fillable:

"""A Post Database Model."""
from config.database import Model

class Post(Model):
    __fillable__ = ['title', 'author_id', 'body']

Relationships

The relationship is pretty straight forward here. Remember that we created a foreign key in our migration. We can create that relationship in our model like so:

"""A Post Database Model."""
from config.database import Model
from orator.orm import belongs_to

class Post(Model):
    __fillable__ = ['title', 'author_id', 'body']

    @belongs_to('author_id', 'id')
    def author(self):
        from app.User import User
        return User

Because of how Masonite does models, some models may rely on each other so it is typically better to perform the import inside the relationship like we did above to prevent any possibilities of circular imports.

Designing Our Blog

Let's setup a little HTML so we can learn a bit more about how views work. In this part we will setup a really basic template in order to not clog up this part with too much HTML but we will learn the basics enough that you can move forward and create a really awesome blog template (or collect one from the internet).

Now that we have all the models and migrations setup, we have everything in the backend that we need to create a layout and start creating and updating blog posts.

We will also check if the user is logged in before creating a template.

The Template For Creating

The URL for creating will be located at /blog/create and will be a simple form for creating a blog post

<form action="/blog/create" method="POST">
    {{ csrf_field }}

    <input type="name" name="title">
    <textarea name="body"></textarea>
</form>

Notice here we have this strange {{ csrf_field }} looking text. Masonite comes with CSRF protection so we need a token to render with the CSRF field.

Now because we have a foreign key in our posts table, we need to make sure the user is logged in before creating this so let's change up our template a bit:

{% if auth() %}
    <form action="/blog/create" method="POST">
        {{ csrf_field }}

        <label> Title </label>
        <input type="name" name="title"><br>

        <label> Body </label>
        <textarea name="body"></textarea>

        <input type="submit" value="Post!">
    </form>
{% else %}
    <a href="/login">Please Login</a>
{% endif %}

auth() is a view helper function that either returns the current user or returns None.

Static Files

For simplicity sake, we won't be styling our blog with something like Bootstrap but it is important to learn how static files such as CSS files work with Masonite so let's walk through how to add a CSS file and add it to our blog.

Firstly, head to storage/static/ and make a blog.css file and throw anything you like in it. For this tutorial we will make the html page slightly grey.

html {
    background-color: #ddd;
}

Now we can add it to our template like so right at the top:

<link href="/static/blog.css" rel="stylesheet">
{% if auth() %}
    <form action="/blog/create" method="POST">
        {{ csrf_field }}

        <label> Title </label>
        <input type="name" name="title"><br>

        <label> Body </label>
        <textarea name="body"></textarea>

        <input type="submit" value="Post!">
    </form>
{% else %}
    <a href="/login">Please Login</a>
{% endif %}

That's it. Static files are really simple. It's important to know how they work but for this tutorial we will ignore them for now and focus on more of the backend.

Javascript files are the same exact thing:

<link href="/static/blog.css" rel="stylesheet">
{% if auth() %}
    <form action="/blog/create" method="POST">
        {{ csrf_field }}

        <label> Title </label>
        <input type="name" name="title"><br>

        <label> Body </label>
        <textarea name="body"></textarea>

        <input type="submit" value="Post!">
    </form>
{% else %}
    <a href="/login">Please Login</a>
{% endif %}

<script src="/static/script.js"></script>

The Controller For Creating And The Container

Notice that our action is going to /blog/create so we need to direct a route to our controller method. In this case we will direct it to a store method.

Let's open back up routes/web.py and create a new route. Just add this to the ROUTES list:

from masonite.routes import Get, Post
...

Post('/blog/create', 'BlogController@store'),

and create a new store method on our controller:

...
def show(self, view: View): 
    return view.render('blog')

# New store Method
def store(self): 
    pass

Now notice above in the form we are going to be receiving 2 form inputs: title and body. So let's import the Post model and create a new post with the input.

from app.Post import Post
from masonite.request import Request
...

def store(self, request: Request):
    Post.create(
        title=request.input('title'),
        body=request.input('body'),
        author_id=request.user().id
    )

    return 'post created'

Also notice we used an input() method. Masonite does not discriminate against different request methods so getting input on a GET or a POST request doesn't matter. You will always use this input method.

Go ahead and run the server using craft serve and head over to http://localhost:8000/blog and create a post. This should hit the /blog/create route with the POST request method and we should see "post created".

Showing Our Posts

Lets go ahead and show how we can show the posts we just created. In this part we will create 2 new templates to show all posts and a specific post.

Creating The Templates

Let's create 2 new templates.

$ craft view posts
$ craft view single

Let's start with showing all posts

Creating The Controller

Let's create a controller for the posts to separate it out from the BlogController.

$ craft controller Post

Great! So now in our show method we will show all posts and then we will create a single method to show a specific post.

Show Method

Let's get the show method to return the posts view with all the posts:

from app.Post import Post

...

def show(self, view: View):
    posts = Post.all()

    return view.render('posts', {'posts': posts})

Posts Route

We need to add a route for this method:

Get('/posts', 'PostController@show')

Posts View

Our posts view can be very simple:

{% for post in posts %}
    {{ post.title }}
    <br>
    {{ post.body }}
    <hr>
{% endfor %}

Go ahead and run the server and head over to http://localhost:8000/posts route. You should see a basic representation of your posts. If you only see 1, go to http://localhost:8000/blog to create more so we can show an individual post.

Showing The Author

Remember we made our author relationship before. Orator will take that relationship and make an attribute from it so we can display the author's name as well:

{% for post in posts %}
    {{ post.title }} by {{ post.author.name }}
    <br>
    {{ post.body }}
    <hr>
{% endfor %}

Let's repeat the process but change our workflow a bit.

Single Post Route

Next we want to just show a single post. We need to add a route for this method:

Get('/post/@id', 'PostController@single')

Notice here we have a @id string. We can use this to grab that section of the URL in our controller in the next section below.

Single Method

Let's create a single method so we show a single post.

from app.Post import Post
from masonite.request import Request
from masonite.view import View
...

def single(self, view: View, request: Request):
    post = Post.find(request.param('id'))

    return view.render('single', {'post': post})

We use the param() method to fetch the id from the URL. Remember this key was set in the route above when we specified the @id

Single Post View

We just need to display 1 post so lets just put together a simple view:

{{ post.title }}
<br>
{{ post.body }}
<hr>

Go ahead and run the server and head over the http://localhost:8000/post/1 route and then http://localhost:8000/post/2 and see how the posts are different.

Updating and Deleting Posts

By now, all of the logic we have gone over so far will take you a long way so let's just finish up quickly with updating and deleting a posts. We'll assume you are comfortable with what we have learned so far so we will run through this faster since this is just more of what were in the previous parts.

Update Controller Method

Let's just make an update method on the PostController:

def update(self, view: View, request: Request):
    post = Post.find(request.param('id'))

    return view.render('update', {'post': post})

def store(self, request: Request):
    post = Post.find(request.param('id'))

    post.title = request.input('title')
    post.body = request.input('body')

    post.save()

    return 'post updated'

Since we are more comfortable with controllers we can go ahead and make two at once. We made one that shows a view that shows a form to update a post and then one that actually updates the post with the database.

Create The View

$ craft view update

<form action="/post/{{ post.id }}/update" method="POST">
    {{ csrf_field }}

    <label for="">Title</label>
    <input type="text" name="title" value="{{ post.title }}"><br>

    <label>Body</label>
    <textarea name="body">{{ post.body }}</textarea><br>

    <input type="submit" value="Update">
</form>

Create The Routes:

Remember we made 2 controller methods so let's attach them to a route here:

Get('/post/@id/update', 'PostController@update'),
Post('/post/@id/update', 'PostController@store'),

That should be it! We can now update our posts.

Delete Method

Let's expand a bit and made a delete method.

from masonite.request import Request
...

def delete(self, request: Request):
    post = Post.find(request.param('id'))

    post.delete()

    return 'post deleted'

Make the route:

Get('/post/@id/delete', 'PostController@delete'),

Notice we used a GET route here, It would be much better to use a POST method but for simplicity sake will assume you can create one by now. We will just add a link to our update method which will delete the post.

Update the Template

We can throw a delete link right inside our update template:

<form action="/post/{{ post.id }}/update" method="POST">
    {{ csrf_field }}

    <label for="">Title</label>
    <input type="text" name="title" value="{{ post.title }}"><br>

    <label>Body</label>
    <textarea name="body">{{ post.body }}</textarea><br>

    <input type="submit" value="Update">

    <a href="/post/{{ post.id }}/delete"> Delete </a>
</form>

Great! You now have a blog that you can use to create, view, update and delete posts! Go on to create amazing things!

Introduction

Lifecycle Overview

With that being said, not all Service Providers need to be ran on every request and there are good times to load objects into the container. For example, loading routes into the container does not need to be ran on every request. Mainly because they won't change before the server is restarted again.

Now the entry point when the server is first ran (with something like craft serve) is the wsgi.py file in the root of the directory. In this directory, all Service Providers are registered. This means that objects are loaded into the container first that typically need to be used by any or all Service Providers later. All Service Providers are registered regardless on whether they require the server to be running (more on this later).

Now it's important to note that the server is not yet running we are still in the wsgi.py file but we have only hit this file, created the container, and registered our Service Providers.

Right after we register all of our Service Providers, we break apart the provider list into two separate lists. The first list is called the WSGIProviders list which are providers where wsgi=True (which they are by default). We will use this list of a smaller amount of providers in order to speed up the application since now we won't need to run through all providers and see which ones need to run.

While we are in the loop we also create a list of providers where wsgi=False and boot those providers. These boot methods may contain things like Manager classes creating drivers which require all drivers to be registered first but doesn't require the WSGI server to be running.

Also, more importantly, the WSGI key is binded into the container at this time. The default behavior is to wrap the WSGI application in a Whitenoise container to assist in the straight forwardness of static files.

Once all the register methods are ran and all the boot methods of Service Providers where wsgi is false, and we have a WSGI key in the container, we can startup the server by using the value of the WSGI key.

We then make an instance of the WSGI key from the container and set it to an application variable in order to better show what is happening. Then this is where the WSGI server is started.

The Server

Now that we have the server running, we have a new entry point for our requests. This entry point is the app function inside bootstrap/start.py.

Now all wsgi servers set a variable called environ. In order for our Service Providers to handle this, we bind it into the container to the Environ key.

Next we run all of our Service Providers where wsgi is true now (because the WSGI server is running).

WSGI Service Providers

The Request Life Cycle is now going to hit all of these providers. Although you can obviously add any Service Providers you at any point in the request, Masonite comes with 5 providers that should remain in the order they are in. These providers have been commented as # Framework Providers. Because the request needs to hit each of these in succession, they should be in order although you may put any amount of any kind of Service Providers in between them.

We enter into a loop with these 5 Service Providers and they are the:

App Provider

This Service Provider registered objects like the routes, request class, response, status codes etc into the container and then loads the environment into these classes on every request so that they can change with the environment. Remember that we registered these classes when the server first started booting up so they remain the same class object as essentially act as singletons Although they aren't being reinstantiated with the already existing object, they are instantiated once and die when the server is killed.

Session Provider

If one of the middleware has instructed the request object to redirect, the view that is ready to execute, will not execute.

For example, if the user is planned on going to the dashboard view, but middleware has told the request to redirect to the login page instead then the dashboard view, and therefore the controller, will not execute at all. It will be skipped over. Masonite checks if the request is redirecting before executing a view.

Also, the request object can be injected into middleware by passing the Request parameter into the constructor like so:

from masonite.request import Request

class SomeMiddleware:

    def __init__(self, request: Request):
        self.request = request

    ...

This provider loads the ability to use sessions, adds a session helper to all views and even attaches a session attribute to the request class.

Route Provider

This provider takes the routes that are loaded in and makes the response object, static codes, runs middleware and other route displaying specific logic. This is the largest Service Provider with the most logic. This provider also searches through the routes, finds which one to hit and exectues the controller and controller method.

Status Code Provider

This provider is responsible for showing the nice HTTP status codes you see during development and production. This Service Provider also allows custom HTTP error pages by putting them into the resources/templates/errors directory.

Nothing too special about this Service Provide. You can remove this if you want it to show the default WSGI server error.

Start Response

This Service Provider collects a few classes that have been manipulated by the above Service Providers and constructs a few headers such as the content type, status code, setting cookies and location if redirecting.

Leaving the Providers

Once these 5 providers have been hit (and any you add), we have enough information to show the output. We leave the Service Provider loop and set the response and output which are specific to WSGI. The output is then sent to the browser with any cookies to set, any new headers, the response, status code, and everything else you need to display html (or json) to the browser.

Introduction

It's extremely simple to add commands to Masonite via the craft command tool and Service Providers. If you have been using Masonite for any amount of time you will learn that commands are a huge part of developing web applications with Masonite. We have made it extremely easy to create these commands and add them to craft to build really fast personal commands that you might use often.

Masonite uses the Cleo package for creating and consuming commands so for more extensive documentation on how to utilize commands themselves, how to get arguments and options, and how to print colorful text to the command line.

Getting Started

You can create commands by using craft itself:

$ craft command Hello

This will create a app/commands/HelloCommand.py file with boilerplate code that looks like this:

""" A HelloCommand Command """
from cleo import Command


class HelloCommand(Command):
    """
    Description of command

    command:name
        {argument : description}
    """

    def handle(self):
        pass

Let's create a simple hello name application which prints "hello your-name" to the console.

Where it says command:name inside the docstring we can put hello and inside the argument we can put name like so:

""" A HelloCommand Command """
from cleo import Command


class HelloCommand(Command):
    """
    Say hello to you

    hello
        {name : Your name}
    """

    def handle(self):
        pass

Inside the handle method we can get the argument passed by specifying self.argument('name'). Simply put:

""" A HelloCommand Command """
from cleo import Command


class HelloCommand(Command):
    """
    Say hello to you

    hello
        {name : Your name}
    """

    def handle(self):
        print('Hello {0}'.format(self.argument('name')))

That's it! Now we just have to add it to our craft command.

Adding Our Command To Craft

We can add commands to craft by creating a Service Provider and registering our command into the container. Craft will automatically run all the register methods on all containers and retrieve all the commands.

Let's create a Service Provider:

$ craft provider HelloProvider

This will create a provider in app/providers/HelloProvider.py that looks like:

''' A HelloProvider Service Provider '''
from masonite.provider import ServiceProvider


class HelloProvider(ServiceProvider):

    def register(self):
        pass

    def boot(self):
        pass

Let's import our command and register it into the container. Also because we are only registering things into the container, we can set wsgi = False so it is not ran on every request and only before the server starts:

''' A HelloProvider Service Provider '''
from masonite.provider import ServiceProvider
from app.commands.HelloCommand import HelloCommand

class HelloProvider(ServiceProvider):

    wsgi = False

    def register(self):
        self.app.bind('HelloCommand', HelloCommand())

    def boot(self):
        pass

Adding The Service Provider

Like normal, we need to add our Service Provider to the PROVIDERS list inside our config/providers.py file:

from app.providers.HelloProvider import HelloProvider

PROVIDERS = [
...
    # Application Providers
    UserModelProvider,
    MiddlewareProvider,

    # New Hello Provider
    HelloProvider,
]

That's it! Now if we run:

$ craft

We will see our new hello command:

  help              Displays help for a command
  hello             Say hello to you
  install           Installs all of Masonite's dependencies

and if we run:

$ craft hello Joseph

We will see an output of:

Hello Joseph

Introduction

The craft command tool is a powerful developer tool that lets you quickly scaffold your project with models, controllers, views, commands, providers, etc. which will condense nearly everything down to its simplest form via the craft namespace. No more redundancy in your development time creating boilerplate code. Masonite condenses all common development tasks into a single namespace.

For example, In Django you may need to do something like:

$ django-admin startproject
$ python manage.py runserver
$ python manage.py migrate

The craft tool condenses all commonly used commands into its own namespace

$ craft new
$ craft serve
$ craft migrate

All scaffolding of Masonite can be done manually (manually creating a controller and importing the view function for example) but the craft command tool is used for speeding up development and cutting down on mundane development time.

Commands

When craft is used outside of masonite directory, it will only show a few commands such as the new and install commands. Other commands such as commands for creating controllers or models are loaded in from the Masonite project itself.

The possible commands for craft include:

Tinker Command

You can "tinker" around with Masonite by running:

$ craft tinker

This command will start a Python shell but also imports the container by default. So we can call:

Type `exit()` to exit.
>>> app
<masonite.app.App object at 0x10cfb8d30>
>>> app.make('Request')
<masonite.request.Request object at 0x10d03c8d0>
>>> app.collect("Mail*Driver")
{'MailSmtpDriver': <class 'masonite.drivers.MailSmtpDriver.MailSmtpDriver'>,
'MailMailgunDriver': <class 'masonite.drivers.MailMailgunDriver.MailMailgunDriver'>
}
>>> exit()

And play around the container. This is a useful debugging tool to verify that objects are loaded into the container if there are any issues.

Show Routes Command

Another useful command is the show:routes command which will display a table of available routes that can be hit:

$ craft show:routes

This will display a table that looks like:

========  =======  =======  ========  ============
Method    Path     Name     Domain    Middleware
========  =======  =======  ========  ============
GET       /        welcome
GET       /home    home
GET       /user 
POST      /create  user   
========  =======  =======  ========  ============

Application Information

If you are trying to debug your application or need help in the Slack channel, it might be beneficial to see some useful information information about your system and environment. In this case we have a simple command:

$ craft info

This will give some small details about the current system which could be useful to someone trying to help you. Running the command will give you something like this:

Environment Information
-------------------------  ------------------
System Information         MacOS x86_64 64bit
System Memory              8 GB
Python Version             CPython 3.6.5
Virtual Environment        ✓
Masonite Version           2.0.6
Craft Version              2.0.7
APP_ENV                    local
APP_DEBUG                  True

Feel free to contribute any additional information you think is necessary to the command in the core repository.

Creating an Authentication System

To create an authentication system with a login, register and a dashboard system, just run:

 $ craft auth

This command will create several new templates, controllers and routes so you don’t need to create an authentication system from scratch, although you can. If you need a custom authentication system, this command will scaffold the project for you so you can go into these new controllers and change them how you see fit.

These new controllers are not apart of the framework itself but now apart of your project. Do not look at editing these controllers as editing the framework source code.

Creating Validators

Validators are classes based on validating form or request input. We can create validators by running:

$ craft validator LoginValidator

Creating Model Definition Docstrings

Masonite uses Orator which is an active record style ORM. If you are coming from other Python frameworks you may be more familiar with Data Mapper ORM's like Django ORM or SQLAlchemy. These style ORM's are useful since the names of the column in your table are typically the names of class attributes. If you forget what you named your column you can typically just look at the model but if your model looks something like:

class User(Model):
    pass

Then it is not apparent what the tables are. We can run a simple command though to generate a docstring that we can throw onto our model:

$ craft model:docstring table_name

Which will generate something like this in the terminal:

"""Model Definition (generated with love by Masonite)

id: integer default: None
name: string(255) default: None
email: string(255) default: None
password: string(255) default: None
remember_token: string(255) default: None
created_at: datetime(6) default: CURRENT_TIMESTAMP(6)
updated_at: datetime(6) default: CURRENT_TIMESTAMP(6)
customer_id: string(255) default: None
plan_id: string(255) default: None
is_active: integer default: None
verified_at: datetime default: None
"""

We can now copy and paste that onto your model and change whatever we need to:

class User(Model):
    """Model Definition (generated with love by Masonite)

    id: integer default: None
    name: string(255) default: None
    email: string(255) default: None
    password: string(255) default: None
    remember_token: string(255) default: None
    created_at: datetime(6) default: CURRENT_TIMESTAMP(6)
    updated_at: datetime(6) default: CURRENT_TIMESTAMP(6)
    customer_id: string(255) default: None
    plan_id: string(255) default: None
    is_active: integer default: None
    verified_at: datetime default: None
    """
    pass

You can also specify the connection to use using the --connection option.

$ craft model:docstring table_name --connection amazon_db

Creating Controllers

If you wish to scaffold a controller, just run:

$ craft controller Dashboard

This command will create a new controller under app/http/controllers/DashboardController.py. By convention, all controllers should have an appended “Controller” and therefore Masonite will append "Controller" to the controller created.

You can create a controller without appending "Controller" to the end by running:

$ craft controller Dashboard -e

This will create a app/http/controllers/Dashboard.py file with a Dashboard controller. Notice that "Controller" is not appended.

You may also create resource controllers which include standard resource actions such as show, create, update, etc:

$ craft controller Dashboard -r

You can also obviously combine them:

$ craft controller Dashboard -r -e

Creating a New Project

If you’d like to start a new project, you can run:

$ craft new project_name

This will download a zip file of the MasoniteFramework/masonite repository and unzip it into your current working directory. This command will default to the latest release of the repo.

You may also specify some options. The --version option will create a new project depending on the releases from the MasoniteFramework/masonite repository.

$ craft new project_name --version 1.3.0

Or you can specify the branch you would like to create a new project with:

$ craft new project_name --branch develop

After you have created a new project, you will have a requirements.txt file with all of the projects dependencies. In addition to this file, you will also have a .env-example file which contains a boilerplate of a .env file. In order to install the dependencies, as well as copy the example environment file to a .env file, just run:

$ craft install

The craft install command will also run craft key --store as well which generates a secret key and places it in the .env file.

Creating Migrations

All frameworks have a way to create migrations in order to manipulate database tables. Masonite uses a little bit of a different approach to migrations than other Python frameworks and makes the developer edit the migration file. This is the command to make a migration for an existing table:

$ craft migration name_of_migration --table users

If you are creating a migration for a table that does not exist yet which the migration will create it, you can pass the --create flag like so:

$ craft migration name_of_migration --create users

These two flags will create slightly different types of migrations.

Migrating

After your migrations have been created, edited, and are ready for migrating, we can now migrate them into the database. To migrate all of your unmigrated migrations, just run:

$ craft migrate

Rolling Back and Rebuilding Migrations

You can also refresh and rollback all of your migrations and remigrate them.

$ craft migrate:refresh

You can also rollback all migrations without remigrating

$ craft migrate:reset

Lastly, you can rollback just the last set of migrations you tried migrating

$ craft migrate:rollback

Models

If you'd like to create a model, you can run:

$ craft model ModelName

This will scaffold a model under app/ModelName and import everything needed.

If you need to create a model in a specific folder starting from the app folder, then just run:

$ craft model Models/ModelName

This will create a model in app/Models/ModelName.py.

Model Shortcuts

You can also use the -s and -m flags to create a seed or model at the same time.

$ craft model ModelName -s -m

This is a shortcut for these 3 commands:

$ craft model ModelName
$ craft seed ModelName
$ craft migration create_tablename_table --create tablename

Creating a Service Provider

Service Providers are a really powerful feature of Masonite. If you'd like to create your own service provider, just run:

$ craft provider DashboardProvider

This will create a file at app/providers/DashboardProvider.py

Creating Views

Views are simply html files located in resources/templates and can be created easily from running the command:

$ craft view blog

This command will create a template at resources/templates/blog.html

You can also create a view deeper inside the resources/templates directory.

$ craft view auth/home

This will create a view under resources/templates/auth/home.html but keep in mind that it will not create the directory for you. If the auth directory does not exist, this command will fail.

Creating Jobs

Jobs are designed to be loaded into queues. We can take time consuming tasks and throw them inside of a Job. We can then use this Job to push to a queue to speed up the performance of our application and prevent bottlenecks and slowdowns.

$ craft job SendWelcomeEmail

Running Queues

Masonite has a queue feature that allows you to load the jobs you create in the section above and run them either asyncronously or send them off to a message broker like RabbitMQ. You may start the worker by running:

$ craft queue:work

Packages

$ craft package name_of_package

Creating Commands

You can scaffold out basic command boilerplate:

$ craft command Hello

This will create a app/commands/HelloCommand.py file with the HelloCommand class.

Running the WSGI Server

You can run the WSGI server by simply running:

$ craft serve

This will set the server to auto-reload when you make file changes.

You can also set it to not auto-reload on file changes:

$ craft serve --dont-reload

or the shorthand

$ craft serve -d

Live Reloading

The serve command also has a live reloading option which will refresh any connected browsers so you can more quickly prototype your jinja templates.

This is not a great tool for changing Python code and any Python code changes may still require a browser refresh to see the changes.

$ craft serve --live-reload

Host and Port

You can bind to a host using -b and/or a port using -p

$ craft serve -b 127.0.0.1 -p 8080

Reloading Interval

Masonite comes with a pretty quick auto reloading development server. By default there will be a 1 second delay between file change detection and the server reloading. This is a fairly slow reloading interval and most systems can handle a much faster interval while still properly managing the starting and killing of process PID's.

You can change the interval to something less then 1 using the -i option:

$ craft serve -r -i .1

You will notice a considerably faster reloading time on your machine. If your machine can handle this interval speed (meaning your machine is properly starting and killing the processes) then you can safely proceed using a lower interval during development.

Encryption

To generate a secret key, we can run:

$ craft key

This will generate a 32 bit string which you can paste into your .env file under the KEY setting.

You may also pass the --store flag which will automatically add the key to your .env file:

$ craft key --store

This command is ran whenever you run craft install

Great! You are now a master at the craft command line tool.

Testing

You can also scaffold out basic test cases. You can do this by running:

$ craft test NameOfTest

This will scaffold the test in the base tests/ directory and you can move it to wherever you like from there.

Publish

Masonite has the concept of publishing where you can publish specific assets to a developers application. This will allow them to make tweaks to better fit your package to their needs.

You can publish a specific provider by running:

$ craft provider ProviderName

You can also optionally specify a tag:

$ craft provider ProviderName --tag name

You should read more about publishing at the publishing documentation page.

Views

Introduction

Views contain all the HTML that you’re application will use to render to the user. Unlike Django, views in Masonite are your HTML templates. All views are located inside the resources/templates directory.

All views are rendered with Jinja2 so we can use all the Jinja2 code you are used to. An example view looks like:

<html>
  <body>
    <h1> Hello {{ 'world' }}</h1>
  </body>
</html>

Creating Views

Since all views are located in resources/templates, we can use simply create all of our views manually here or use our craft command tool. To make a view just run:

$ craft view hello

This will create a template under resources/templates/hello.html.

Calling Views

The View class is loaded into the container so we can retrieve it in our controller methods like so:

from masonite.view import View

def show(self, view: View):
    return view.render('dashboard')

This is exactly the same as using the helper function above. So if you choose to code more explicitly, the option is there for you.

Global Views

Some views may not reside in the resources/templates directory and may even reside in third party packages such as a dashboard package. We can locate these views by passing a / in front of our view.

For example as a use case we might pip install a package:

$ pip install package-dashboard

and then be directed or required to return one of their views:

def show(self, view: View):
    return view.render('/package/views/dashboard')

This will look inside the dashboard.views package for a dashboard.html file and return that. You can obviously pass in data as usual.

Caveats

It's important to note that if you are building a third party package that integrates with Masonite that you place any .html files inside a Python package instead of directly inside a module. For example, you should place .html files inside a file structure that looks like:

package/
  views/
    __init__.py
    index.html
    dashboard.html
setup.py
MANIFEST.in
...

ensuring there is a __init__.py file. This is a Jinja2 limitation that says that all templates should be located in packages.

Accessing a global view such as:

def show(self, view: View):
    return view.render('/package/dashboard')

will perform an absolute import for your Masonite project. For example it will locate:

app/
config/
databases/
...
package/
  dashboard.html

Or find the package in a completely separate third part module. So if you are making a package for Masonite then keep this in mind of where you should put your templates.

Passing Data to Views

Most of the time we’ll need to pass in data to our views. This data is passed in with a dictionary that contains a key which is the variable with the corresponding value. We can pass data to the function like so:

def show(self, view: View, request: Request):
    return view.render('dashboard', {'id': request.param('id')})

This will send a variable named id to the view which can then be rendered like:

<html>
  <body>
    <h1> {{ id }} </h1>
  </body>
</html>

View Syntax

Masonite also enables Jinja2 Line Statements by default which allows you to write syntax the normal way:

{% extends 'nav/base.html' %}

{% block content %}
    {% for element in variables %}
        {{ element }}
    {% endfor %}

    {% if some_variable %}
        {{ some_variable }}
    {% endif %}

{% endblock %}

Or using line statements with the @ character:

@extends 'nav/base.html'

@block content
    @for element in variables
        {{ element }}
    @endfor

    @if some_variable
        {{ some_variable }}
    @endif

@endblock

The choice is yours on what you would like to use but keep in mind that line statements need to use only that line. Nothing can be after after or before the line.

Adding Environments

You can also add Jinja2 environments to the container which will be available for use in your views. This is typically done for third party packages such as Masonite Dashboard. You can extend views in a Service Provider in the boot method. Make sure the Service Provider has the wsgi attribute set to False. This way the specific Service Provider will not keep adding the environment on every request.

from masonite.view import View

wsgi = False

...

def boot(self, view: View):
    view.add_environment('dashboard/templates')

By default the environment will be added using the PackageLoader Jinja2 loader but you can explicitly set which loader you want to use:

from jinja2 import FileSystemLoader
from masonite.view import View
...
wsgi = False

...

def boot(self, view: View):
    view.add_environment('dashboard/templates', loader=FileSystemLoader)

The default loader of PackageLoader will work for most cases but if it doesn't work for your use case, you may need to change the Jinja2 loader type.

Using Dot Notation

If using a / doesn't seem as clean to you, you can also optionally use dots:

def show(self, view: View):
    view.render('dashboard.user.show')

if you want to use a global view you still need to use the first /:

def show(self, view: View):
    view.render('/dashboard.user.show')

Helpers

There are quite a few built in helpers in your views. Here is an extensive list of all view helpers:

Request

You can get the request class:

<p> Path: {{ request().path }} </p>

Static

You can get the location of static assets:

If you have a configuration file like this:

....
's3': {
  's3_client': 'sIS8shn...'
  ...
  'location': 'https://s3.us-east-2.amazonaws.com/bucket'
  },
....

...
<img src="{{ static('s3', 'profile.jpg') }}" alt="profile">
...

this will render:

<img src="https://s3.us-east-2.amazonaws.com/bucket/profile.jpg" alt="profile">

CSRF Field

You can create a CSRF token hidden field to be used with forms:

<form action="/some/url" method="POST">
    {{ csrf_field }}
    <input ..>
</form>

CSRF Token

You can get only the token that generates. This is useful for JS frontends where you need to pass a CSRF token to the backend for an AJAX call

<p> Token: {{ csrf_token }} </p>

Current User

You can also get the current authenticated user. This is the same as doing request.user().

<p> User: {{ auth().email }} </p>

Request Method

On forms you can typically only have either a GET or a POST because of the nature of html. With Masonite you can use a helper to submit forms with PUT or DELETE

<form action="/some/url" method="POST">
    {{ request_method('PUT') }}
    <input ..>
</form>

This will now submit this form as a PUT request.

Route

You can get a route by it's name by using this method:

<form action="{{ route('route.name') }}" method="POST">
    ..
</form>

If your route contains variables you need to pass then you can supply a dictionary as the second argument.

<form action="{{ route('route.name', {'id': 1}) }}" method="POST">
    ..
</form>

or a list:

<form action="{{ route('route.name', [1]) }}" method="POST">
    ..
</form>

Another cool feature is that if the current route already contains the correct dictionary then you do not have to pass a second parameter. For example if you have a 2 routes like:

Get('/dashboard/@id', 'Controller@show').name('dashboard.show'),
Get('/dashhboard/@id/users', 'Controller@users').name('dashhboard.users')

If you are accessing these 2 routes then the @id parameter will be stored on the user object. So instead of doing this:

<form action="{{ route('dashboard.users', {'id': 1}) }}" method="POST">
    ..
</form>

You can just leave it out completely since the id key is already stored on the request object:

<form action="{{ route('dashboard.users') }}" method="POST">
    ..
</form>

Back

This is useful for redirecting back to the previous page. If you supply this helper then the request.back() method will go to this endpoint. It's typically good to use this to go back to a page after a form is submitted with errors:

<form action="/some/url" method="POST">
    {{ back(request().path) }}
</form>

Now when a form is submitted and you want to send the user back then in your controller you just have to do:

def show(self, request: Request):
    # Some failed validation
    return request.back()

Old

The request.back() method will also flash the current inputs to the session so you can get them when you land back on your template. You can get these values by using the old() method:

<form>
  <input type="text" name="email" value="{{ old('email') }}">
  ...
</form>

Session

You can access the session here:

<p> Error: {{ session().get('error') }} </p>

Sign

You can sign things using your secret token:

<p> Signed: {{ sign('token') }} </p>

Unsign

You can also unsign already signed string:

<p> Signed: {{ unsign('signed_token') }} </p>

Encrypt

This is just an alias for sign

Decrypt

This is just an alias for unsign

Config

This allows you to easily fetch configuration values in your templates:

<h2> App Name: {{ config('application.name') }}</h2>

Optional

Allows you to fetch values from objects that may or may not be None. Instead of doing something like:

{% if auth() and auth().name == 'Joe' %}
    <p>Hello!</p>
{% endif %}

You can use this helper:

{% if optional(auth()).name == 'Joe' %}
    <p>Hello!</p>
{% endif %}

DD

This is the normal dd helper you use in your controllers

Hidden

You can use this helper to quickly add a hidden field

<form action="/" method="POST">
    {{ hidden('secret' name='secret-value') }}
</form>

Exists

Check if a template exists

{% if exists('auth/base') %}
    {% extends 'auth/base.html' %}
{% else %}
    {% extends 'base.html' %}
{% endif %}

Cookie

Gets a cookie:

<h2> Token: {{ cookie('token') }}</h2>

Url

Get the URL to a location:

<form action="{{ url('/about', full=True) }}" method="POST">

</form>

Jinja2

Below are some examples of the Jinja2 syntax which Masonite uses to build views.

Line Statements

It's important to note that Jinja2 statements can be rewritten with line statements and line statements are preferred in Masonite. In comparison to Jinja2 line statements evaluate the whole line, thus the name line statement.

So Jinja2 syntax looks like this:

{% if expression %}
    <p>do something</p>
{% endif %}

This can be rewritten like this with line statement syntax:

@if expression
    <p>do something</p>
@endif

It's important to note though that these are line statements. Meaning nothing else can be on the line when doing these. For example you CANNOT do this:

<form action="@if expression: 'something' @endif">

</form>

But you could achieve that with the regular formatting:

<form action="{% if expression %} 'something' {% endif %}">

</form>

Whichever syntax you choose is up to you.

Variables

You can show variable text by using {{ }} characters:

<p>
    {{ variable }}
</p>
<p>
    {{ 'hello world' }}
</p>

If statement

If statements are similar to python but require an endif!

Line Statements:

@if expression
    <p>do something</p>
@elif expression
    <p>do something else</p>
@else
    <p>above all are false</p>
@endif

Using alternative Jinja2 syntax:

{% if expression %}
    <p>do something</p>
{% elif %}
    <p>do something else</p>
{% else %}
    <p>above all are false</p>
{% endif %}

For Loops

For loop look similar to the regular python syntax.

Line Statements:

@for item in items
    <p>{{ item }}</p>
@endfor

Using alternative Jinja2 syntax:

{% for item in items %}
    <p>{{ item }}</p>
{% endfor %}

Include statement

An include statement is useful for including other templates.

Line Statements:

@include 'components/errors.html'

<form action="/">

</form>

Using alternative Jinja2 syntax:

{% include 'components/errors.html' %}

<form action="/">

</form>

Any place you have repeating code you can break out and put it into an include template. These templates will have access to all variables in the current template.

Extends

This is useful for having a child template extend a parent template. There can only be 1 extends per template:

Line Statements:

@extends 'components/base.html'

@block content
    <p> read below to find out what a block is </p>
@endblock

Using alternative Jinja2 syntax:

{% extends 'components/base.html' %}

{% block content %}
    <p> read below to find out what a block is </p>
{% endblock %}

Blocks

Blocks are sections of code that can be used as placeholders for a parent template. These are only useful when used with the extends above. The "base.html" template is the parent template and contains blocks, which are defined in the child template "blocks.html".

Line Statements:

<!-- components/base.html -->
<html>
    <head>
        @block css 
        <!-- block named "css" defined in child template will be inserted here -->
        @endblock
    </head>

<body>
    <div class="container">
        @block content
        <!-- block named "content" defined in child template will be inserted here -->
        @endblock
    </div>

@block js
<!-- block named "js" defined in child template will be inserted here -->
@endblock

</body>
</html>

<!-- components/blocks.html -->
@extends 'components/base.html'

@block css
    <link rel=".." ..>
@endblock

@block content
    <p> This is content </p>
@endblock

@block js
    <script src=".." />
@endblock

Using alternative Jinja2 syntax:

<!-- components/base.html -->
<html>
    <head>
        {% block css %} 
        <!-- block named "css" defined in child template will be inserted here -->
        {% endblock %}
    </head>

<body>
    <div class="container">
        {% block content %} 
        <!-- block named "content" defined in child template will be inserted here -->
        {% endblock %}
    </div>

{% block js %}
<!-- block named "js" defined in child template will be inserted here -->
{% endblock %}

</body>
</html>

<!-- components/blocks.html -->
{% extends 'components/base.html' %}

{% block css %}
    <link rel=".." ..>
{% endblock %}

{% block content %}
    <p> This is content </p>
{% endblock %}

{% block js %}
    <script src=".." />
{% endblock %}

As you see blocks are fundamental and can be defined with Jinja2 and line statements. It allows you to structure your templates and have less repeating code.

The blocks defined in the child template will be passed to the parent template.

The modern and developer centric Python web framework that strives for an actual batteries included developer tool with a lot of out of the box functionality with an extremely extendable architecture. Masonite is perfect for beginner developers getting into their first web applications as well as experienced devs that need to utilize the full potential of Masonite to get their applications done.

Masonite works hard to be fast and easy from install to deployment so developers can go from concept to creation in as quick and efficiently as possible. Use it for your next SaaS! Try it once and you’ll fall in love.

NOTE: Masonite 2.3 is no longer compatible with the masonite-cli tool. Please uninstall that by running pip uninstall masonite-cli. If you do not uninstall masonite-cli you will have command clashes

Some Notable Features Shipped With Masonite

• Easily send emails with the Mail Provider and the SMTP and Mailgun drivers.

• Send websocket requests from your server with the Broadcast Provider and Pusher and Ably drivers.

• IOC container and auto resolving dependency injection.

• Service Providers to easily add functionality to the framework.

• Extremely simple static files configured and ready to go.

• Active Record style ORM called Orator.

• An extremely useful command line tool called craft commands.

• Extremely extendable.

These, among many other features, are all shipped out of the box and ready to go. Use what you need when you need it.

Requirements

In order to use Masonite, you’ll need:

• Python 3.5+

• Latest version of OpenSSL

• Pip3

Linux

If you are running on a Linux flavor, you’ll need the Python dev package and the libssl package. You can download these packages by running:

Debian and Ubuntu based Linux distributions

$ sudo apt install python3-dev python3-pip libssl-dev build-essential python3-venv

Or you may need to specify your python3.x-dev version:

$ sudo apt-get install python3.6-dev python3-pip libssl-dev build-essential python3-venv

Enterprise Linux based distributions (Fedora, CentOS, RHEL, ...)

# dnf install python-devel openssl-devel

Installation

Masonite excels at being simple to install and get going. If you are coming from previous versions of Masonite, the order of some of the installation steps have changed a bit.

Firstly, open a terminal and head to a directory you want to create your application in. You might want to create it in a programming directory for example:

$ cd ~/programming
$ mkdir myapp
$ cd myapp

If you are on windows you can just create a directory and open the directory in the Powershell.

Activating Our Virtual Environment (optional)

Although this step is technically optional, it is highly recommended. You can create a virtual environment if you don't want to install all of masonite's dependencies on your systems Python. If you use virtual environments then create your virtual environment by running:

$ python -m venv venv
$ source venv/bin/activate

or if you are on Windows:

$ python -m venv venv
$ ./venv/Scripts/activate

Installing Masonite

Now we can install Masonite. This will give us access to a craft command we can use to finish the install steps for us:

$ pip install masonite

Once Masonite installs you will now have access to the craft command line tool. Craft will become your best friend during your development. You will learn to love it very quickly :).

You can ensure Masonite and craft installed correctly by running:

$ craft

You should see a list of a few commands like install and new