W05: Pages: HTML in Templates

A wedding invitation printer does not design every card from scratch. They have one beautiful card with blanks: Dear __, you are invited on ____. For each guest they fill in the blanks. A template is that card for web pages. The HTML is written once; Python fills in the blanks for each visitor. The stack uses Jinja for this, and every page in your app is a Jinja template.

HTML First

Templates are HTML with a few extras. If tags like <h1>, <p>, <ul>, <form> and <button> are new to you, read T05: HTML Tags and T06: HTML Forms & Blocks first. Everything there applies. The browser never sees Jinja: it only ever receives the finished HTML.

The Three Jinja Shapes

Jinja adds three things to HTML:

Shape Means Example
{{ ... }} print a value here {{ note.title }}
{% ... %} do something: a loop, a choice, include a file {% for note in notes %}
{# ... #} a comment, never sent {# TODO: dates #}

Here is the starter's list of notes, from app/templates/pages/index.html:

<ul id="notes" class="peer grid gap-2">
  {% for note in notes %}{% include "fragments/note_item.html" %}{% endfor %}
</ul>

For each note, Jinja pastes in the note_item.html fragment, with note filled in.

Safety for free: {{ note.title }} is escaped. If someone types <script> as a note title, the page shows the text <script>, it does not run it. Never turn this off.

The Frame: base.html

Every page shares the same <head>, the same scripts and the same outer box. That frame lives once, in app/templates/base.html, with a hole in the middle:

<main class="mx-auto max-w-2xl p-4 grid gap-6">
{% block content %}{% endblock %}
</main>

A page says "use the frame, and here is my middle part":

{% extends "base.html" %}
{% block content %}
  <h1>...</h1>
{% endblock %}

Change the frame once, and every page changes. That is the point.

Pages and Fragments

The stack has one rule about templates: a route returns a page or a fragment, never both.

A page includes its fragments, so the same piece of HTML is written once and used in both places. The note you see when the page loads and the note htmx adds after you click are the same file.

Where the Blanks Come From

In app/main.py, a route chooses a template and passes the values:

@app.get("/", response_class=HTMLResponse)
def index(request: Request) -> HTMLResponse:
    return render(request, "pages/index.html", notes=db.notes(connection), title="", problems=[])

render is a small helper in the starter. It works out the language, gives the template the t() function for words (W10), and sends back the HTML. Every name you pass, like notes=, becomes a blank you can fill with {{ notes }}.

Add a Page

Say you want an About page at /about. It takes three pieces, each in its home:

  1. The route, in app/main.py, inside create_app beside the others:
@app.get("/about", response_class=HTMLResponse)
def about(request: Request) -> HTMLResponse:
    return render(request, "pages/about.html")
  1. The page, app/templates/pages/about.html:
{% extends "base.html" %}
{% block content %}
<h1 class="text-2xl font-semibold">{{ t("about.title") }}</h1>
<p>{{ t("about.body") }}</p>
{% endblock %}
  1. The words, in both messages/en.json and messages/ja.json, with the keys about.title and about.body.

And a test, in tests/test_app.py, that asks for /about and checks the title is there.

You do not have to type any of this. Ask Pi:

"Add an About page at /about with a title and one paragraph saying what this app is for, in English and Japanese. Link to it from the home page header."

Then read what came back: the route, the page, the two message files, the test. Each is where this lesson said it would be. If Pi put words straight into the HTML, or wrote a whole <html> page without extends, ask it to follow the stack's rules.

Good HTML Habits

This Week's Exercise

  1. Open base.html, pages/index.html and fragments/note_item.html. Find each {{ }} and {% %} and say what it does.
  2. Ask Pi for the About page. Read the route, the template and the test it wrote.
  3. Try the escaping: add a note titled <b>hello</b>. What appears on the page?
  4. Make your browser window very narrow. Does the About page still read well?

Key Takeaways

  • A template is HTML with blanks: {{ }} prints, {% %} loops and includes, {# #} is a comment
  • Values are escaped automatically, so typed text is shown, never run
  • base.html is the shared frame; a page extends it and fills its content block
  • A route returns a page or a fragment, never both; pages include their fragments
  • A new page is a route in main.py, a template in pages/, its words in both message files, and a test