Templating With Jinja2 in Flask: Essentials

Jinja2 is a template engine written in pure Python. It provides a Django-inspired non-XML syntax but supports inline expressions and an optional sandboxed environment. It is small but fast, apart from being an easy-to-use standalone template engine. Flask is a Python-based micro web framework which allows you to write your web applications quickly and efficiently.

In this three-part series, I will start with the basics of Jinja2 templating from the perspective of Flask. In the subsequent parts of this series, I will cover advanced templating topics while learning how to lay out templates in a Flask-based application in a modular and extensible design.

I assume that you have a basic understanding of Flask and environment setup best practices using virtualenv to be followed while developing a Python application.

Installing Packages

Flask comes packaged with Jinja2, and hence we just need to install Flask. For this series, I recommend using the development version of Flask, which includes much more stable command-line support, among many other features and improvements to Flask in general.

1	pip install https://github.com/mitsuhiko/flask/tarball/master

Need for a Templating Engine?

In Flask, we can write a complete web application without the need for any third-party templating engine. Let's have a look at a small Hello World app below:

from flask import Flask

app = Flask(__name__)

@app.route('/')
@app.route('/hello')
@app.route('/hello/<user>')
def hello_world(user=None):
    user = user or 'Shalabh'
    return '''
    <html>
        <head>
            <title>Templating in Flask</title>
        </head>
        <body>
            <h1>Hello %s!</h1>
            <p>Welcome to the world of Flask!</p>
        </body>
    </html>''' % user
       
if __name__ == '__main__':
    app.run()

It is obvious that the above pattern of writing an application would not be feasible in a real web application where the HTML, CSS, and JS can reach thousands of lines of code. Here, templating saves us because we can structure our view code by keeping our templates separate. Flask provides support for Jinja2 by default, but any other templating engine can also be used as suited.

Laying Out Templates

By default, Flask expects the templates to be placed in a folder named templates at the application root level. Flask then automatically reads the contents by making this folder available for use with the render_template() method. I will demonstrate the same by restructuring the trivial Hello World application shown above.

The application structure would be as shown below.

1	flask_app/
2	my_app.py
3	templates/
4	- index.html

The Application Itself

flask_app/my_app.py

from flask import Flask, render_template, request

app = Flask(__name__)

@app.route('/')
@app.route('/hello')
@app.route('/hello/<user>')
def hello_world(user=None):
    user = user or 'Shalabh'
    return render_template('index.html', user=user)

flask_app/templates/index.html

<html>
  <head>
    <title>Templating in Flask</title>
  </head>
  <body>
    <h1>Hello {{ user }}!</h1>
    <p>Welcome to the world of Flask!</p>
  </body>
</html>

To run the application, just execute the following command on the command line:

1	flask --app=my_app run

Open up http://127.0.0.1:5000/ in a browser to see the application in action. The result would be the same in the case of http://127.0.0.1:5000/hello as well.

Try opening the URL with your name as the last part of it. So if your name is John, the URL would be http://127.0.0.1:5000/hello/John. Now the page would look like this:

Accessing the landing page with a custom name

It is pretty straightforward that in the method hello_world, the last part of the URL after hello is fetched from the request and passed to the context of the template being rendered using render_template(). This value is then parsed from the template context using the Jinja2 placeholder {{ user }}. This placeholder evaluates all the expressions that are placed inside it, depending on the template context.

Understanding Blocks and Inheritance in Templates

Usually, any web application will have a number of web pages that will be different from each other. Code blocks such as headers and footers will be the same in almost all the pages throughout the site. Likewise, the menu also remains the same. In fact, usually, just the center container block changes, and the rest usually remains the same. For this, Jinja2 provides a great way of inheritance among templates. It's a good practice to have a base template where we can structure the basic layout of the site along with the header and footer.

I will create a small application to showcase a list of products under different categories. For styling, I will use the Bootstrap framework to give a basic design to the templates. The application structure is now as shown below.

flask_app/
    my_app.py    
    templates/
        - base.html
        - home.html
        - product.html
    static/
        css/
            - main.css

The rest of the application code is demonstrated below.

flask_app/my_app.py

from flask import Flask, render_template, abort

app = Flask(__name__)

PRODUCTS = {
    'iphone': {
        'name': 'iPhone 5S',
        'category': 'Phones',
        'price': 699,
    },
    'galaxy': {
        'name': 'Samsung Galaxy 5',
        'category': 'Phones',
        'price': 649,
    },
    'ipad-air': {
        'name': 'iPad Air',
        'category': 'Tablets',
        'price': 649,
    },
    'ipad-mini': {
        'name': 'iPad Mini',
        'category': 'Tablets',
        'price': 549
    }
}

@app.route('/')
@app.route('/home')
def home():
    return render_template('home.html', products=PRODUCTS)

@app.route('/product/<key>')
def product(key):
    product = PRODUCTS.get(key)
    if not product:
        abort(404)
    return render_template('product.html', product=product)

In this file, I have hardcoded the product list to make the application simpler and focus only on the templating part. I have created two endpoints, home and product, where the former serves the purpose of listing all the products and the latter opens up the individual page.

flask_app/static/css/main.css

body {
  padding-top: 50px;
}
.top-pad {
  padding: 40px 15px;
  text-align: center;
}

This file holds a bit of custom CSS that I added to make the templates more legible. Let's look at the templates now.

flask_app/templates/base.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Jinja2 Tutorial - Tutsplus</title>
    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/css/bootstrap.min.css">
    <link href="{{ url_for('static', filename='css/main.css') }}" rel="stylesheet">
  </head>
  <body>
    <div class="navbar navbar-inverse navbar-fixed-top" role="navigation">
      <div class="container">
        <div class="navbar-header">
          <a class="navbar-brand" href="{{ url_for('home')}}">Tutsplus - Jinja2 Tutorial</a>
        </div>
      </div>
    </div>
    <div class="container">
      {% block container %}{% endblock %}
    </div>
    <!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
    
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
    <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.4.1/js/bootstrap.min.js"></script>

  </body>
</html>

Note the use of url_for() for creating URLs for static files and other links. It is a very handy tool which is provided by Flask. Read more about this in the documentation. Another important point to note here is the usage of {% block container %}{% endblock %}, which is a crucial component of Jinja2 working towards making the templates modular and inheritable. The next couple of files will make this clearer.

Control Flow

Python uses if, elif, else, and for loop statements to control program flow based on whether a condition is True or False. You can also incorporate these conditions in your Flask application to loop over the dictionary of products and display them on the home page. These conditional statements are put inside {% %} blocks. Update the home.html page as follows.

flask_app/templates/home.html

{% extends 'base.html' %}
 
{% block container %}
  <div class="top-pad">
    {% for id, product in products.items() %}
      <div class="well">
        <h2>
          <a href="{{ url_for('product', key=id) }}">{{product['name']}}</a>
          <small>$ {{ product['price']}}</small>
        </h2>
      </div>
    {% endfor %}
  </div>
{% endblock %}

See how this template extends base.html and provides the contents of {% block container %}. {% for %} behaves just like a normal for loop in any language which we are using here to create a list of products.

flask_app/templates/product.html

{% extends 'home.html' %}

{% block container %}
  <div class="top-pad">
    <h1>{{ product['name'] }}
      <small>{{ product['category'] }}</small>
    </h1>
    <h3>$ {{ product['price'] }}</h3>
  </div>
{% endblock %}

The above template implements the individual product page.

Now run the app by executing the following command.

1	flask --app=my_app run

The running app would look like the one shown in the screenshot below. Just open http://127.0.0.1:5000/home in the browser.

The application running with the Bootstrap framework

Click on any of the products to see the individual product page.

Filters

Filters can be applied to variables just as you would use Python methods. A pipe character separates filters in the Jinja templating language. For example, suppose you needed to capitalize the product's name on the home page; you would apply the upper filter as follows.

{% extends 'base.html' %}
 
{% block container %}
  <div class="top-pad">
    {% for id, product in products.items() %}
      <div class="well">
        <h2>
          <a href="{{ url_for('product', key=id) }}">{{product['name']| upper }}</a>
          <small>$ {{ product['price']}}</small>
        </h2>
      </div>
    {% endfor %}
  </div>
{% endblock %}

Now, if you run the server, you should notice that the Product name is in ALLCAPS.

Conclusion

In this tutorial, we have seen how to lay out the template structure in a Flask-based application using Jinja2. We also saw how blocks can be used to leverage the inheritance in templates.

In the next part of this series, we will see how to write a custom filter, a custom context processor, and a macro.

This post has been updated with contributions from Esther Vaati. Esther is a software developer and writer for Envato Tuts+.