Displaying JSON Records with Templates

Writing every task inside a Python HTML string repeats the page structure whenever the records change. A template describes the structure once and marks where values belong. We use Jinja templates, which run on the server before the browser receives the response.

Continue in the same web-app folder and environment from Chapter 2. This chapter replaces the inline-HTML application with a version that reads records from JSON and renders a template.

Add JSON Records and Templates

Keep main.py, .venv, and requirements.txt in web-app. Add support.py, tasks.json, and a templates folder containing tasks.html. The listings below provide the contents of each application file:

web-app/
  .venv/
  requirements.txt
  main.py
  support.py
  tasks.json
  templates/
    tasks.html

Save the JSON listing below as tasks.json, beside main.py.

From JSON Records to HTML

The tasks.json file contains JSON text:

[
  {
    "id": "T01",
    "title": "Read the article",
    "category": "reading"
  },
  {
    "id": "T02",
    "title": "Practise loops",
    "category": "practice"
  }
]

The short fragments below trace one record; the complete replacement files follow after the syntax practice. First, the JSON text above stores the title under "title". Second, read_records("tasks.json") constructs Python dictionaries from that text. The route can place the first dictionary in a context, which gives names to values available in a template:

records = read_records("tasks.json")
context = {"task": records[0]}

Here records[0] is a dictionary containing all three fields. The context key "task" names that whole dictionary; it does not rename the dictionary’s "title" field.

Third, a template looks up the named dictionary and one of its fields:

<p>{{ task["title"] }}</p>

Double braces insert a value. Bracket lookup chooses the dictionary field, just as it does in Python. Fourth, the server renders this fragment into returned HTML:

<p>Read the article</p>

The diagram below follows the title from JSON text to returned HTML:

A template looking up heading needs that name in its context. A context key named title does not also create a key named heading.

context = {"heading": "Study tasks"}

With this context, <h1>{{ heading }}</h1> produces <h1>Study tasks</h1>. Changing the key without changing the template breaks that connection.

context = {"heading": "Weekly study plan", "note": "Bring your notes"}

<h1>{{ note }}</h1>
<p>{{ note }}</p>

The next exercise supplies the application setup. FastAPI supplies request when it calls the route. The call to templates.TemplateResponse(...) combines the template selected by name with the values in context. Connect the record to that context and complete the template’s lookups.

You have connected one record to a template. A list page supplies {"tasks": records} so the template can repeat a fragment for every record. Its loop uses different delimiters:

<ul>
  {% for task in tasks %}
    <li>{{ task["title"] }}</li>
  {% endfor %}
</ul>

The for directive repeats the enclosed fragment. endfor closes that region; neither directive appears in the returned HTML. A condition chooses which fragment to render:

{% if tasks %}
  <p>Tasks are available.</p>
{% else %}
  <p>No tasks.</p>
{% endif %}

As in Python, an empty list is false. Jinja renders the first branch for a nonempty tasks list and the else branch for []. endif closes the choice.

Practise the interpolation, loop, and condition notation with small edits in templates/page.html.

Supplied JSON Reading Code

Now connect the local project to tasks.json. Save this reading function in support.py, beside main.py. It uses the JSON operations from the earlier parts:

import json

def read_records(path):
    with open(path, encoding="utf-8") as source:
        return json.load(source)

Supplied Application Setup

Replace the contents of main.py with this complete application. As in the earlier examples, app is the application and the decorator registers its route. templates reads HTML templates from the templates folder:

from fastapi import FastAPI, Request
from fastapi.templating import Jinja2Templates
from support import read_records

app = FastAPI()
templates = Jinja2Templates(directory="templates")
DATA_FILE = "tasks.json"

@app.get("/tasks")
def show_tasks(request: Request):
    context = {"tasks": read_records(DATA_FILE)}
    return templates.TemplateResponse(
        request=request, name="tasks.html", context=context
    )

Each GET request to /tasks calls show_tasks, which reads the file and builds a context. templates.TemplateResponse combines that context with tasks.html and returns the resulting HTML response.

A Complete List Template

Save this complete document as templates/tasks.html. The condition chooses between the repeated records and an empty-collection message:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Study tasks</title>
  </head>
  <body>
    <h1>Study tasks</h1>
    {% if tasks %}
      <ul id="task-list">
        {% for task in tasks %}
          <li>{{ task["title"] }} ({{ task["category"] }})</li>
        {% endfor %}
      </ul>
    {% else %}
      <p>No tasks.</p>
    {% endif %}
  </body>
</html>

Save all the files and wait for the server’s automatic reload to finish. If you stopped the server, start it again from the same web-app terminal:

uvicorn main:app --reload

Visit http://127.0.0.1:8000/tasks; you should see both titles and their categories. Keep this project for the following chapters.

For the supplied file, the loop runs twice in file order. For [], the condition selects the empty message and produces no task items. Try both documents in tasks.json and refresh after each change. Use View page source to compare the task list items with the empty-list paragraph. Restore the example records afterward.

If expected task items are missing, use Chapter 2’s print technique to inspect context inside show_tasks. Check that its "tasks" key contains the records the template needs.

Use the same loop and condition patterns to display a supplied list of records.

Data That Resembles Markup

A title can contain quotation marks, ampersands, or angle brackets. In the example file, change a record’s title field to "title": "Read \"Loops\" & <practice>". Save and refresh the page, then use View page source.

Restore the original records after comparing the page and its source.

task = {"id": "T01", "title": "Read <chapter> & practise", "category": "reading"}
context = {"task": task}

The next chapter selects a single record and gives it an address.

Check Your Understanding

1. In the complete list template, what does tasks refer to, and what does task refer to during one loop iteration? How does task["category"] select the value to display?
2. Suppose tasks contains one record whose title is an empty string. Which branch of {% if tasks %} runs? Explain which value the condition checks.
3. In the completed local project, which file would you edit to change a stored task title, and which file would you edit to change the page heading Study tasks? Explain how the project separates record data from page structure.
4. When a GET request to /tasks arrives, who supplies the request argument to show_tasks? Who supplies the template name and context in the call to templates.TemplateResponse(...)? Explain the difference between these two calls.