📝 Update template docs with more info about `url_for` (#5937)

Co-authored-by: Sebastián Ramírez <[email protected]>
1 year ago · 0c796747a3
3 changed files with 49 additions and 6 deletions
--- a/docs/en/docs/advanced/templates.md
+++ b/docs/en/docs/advanced/templates.md
@ -46,21 +46,61 @@ $ pip install jinja2

 ## Writing templates

-Then you can write a template at `templates/item.html` with:
+Then you can write a template at `templates/item.html` with, for example:

 ```jinja hl_lines="7"
 {!../../../docs_src/templates/templates/item.html!}
 ```

-It will show the `id` taken from the "context" `dict` you passed:
+### Template Context Values
+
+In the HTML that contains:
+
+{% raw %}
+
+```jinja
+Item ID: {{ id }}
+```
+
+{% endraw %}
+
+...it will show the `id` taken from the "context" `dict` you passed:

 ```Python
-{"request": request, "id": id}
+{"id": id}
+```
+
+For example, with an ID of `42`, this would render:
+
+```html
+Item ID: 42
+```
+
+### Template `url_for` Arguments
+
+You can also use `url_for()` inside of the template, it takes as arguments the same arguments that would be used by your *path operation function*.
+
+So, the section with:
+
+{% raw %}
+
+```jinja
+<a href="{{ url_for('read_item', id=id) }}">
+```
+
+{% endraw %}
+
+...will generate a link to the same URL that would be handled by the *path operation function* `read_item(id=id)`.
+
+For example, with an ID of `42`, this would render:
+
+```html
+<a href="/items/42">
 ```

 ## Templates and static files

-You can also use `url_for()` inside of the template, and use it, for example, with the `StaticFiles` you mounted.
+You can also use `url_for()` inside of the template, and use it, for example, with the `StaticFiles` you mounted with the `name="static"`.

 ```jinja hl_lines="4"
 {!../../../docs_src/templates/templates/item.html!}
--- a/docs_src/templates/templates/item.html
+++ b/docs_src/templates/templates/item.html
@ -4,6 +4,6 @@
    <link href="{{ url_for('static', path='/styles.css') }}" rel="stylesheet">
 </head>
 <body>
-    <h1>Item ID: {{ id }}</h1>
+    <h1><a href="{{ url_for('read_item', id=id) }}">Item ID: {{ id }}</a></h1>
 </body>
 </html>
--- a/tests/test_tutorial/test_templates/test_tutorial001.py
+++ b/tests/test_tutorial/test_templates/test_tutorial001.py
@ -16,7 +16,10 @@ def test_main():
    client = TestClient(app)
    response = client.get("/items/foo")
    assert response.status_code == 200, response.text
-    assert b"<h1>Item ID: foo</h1>" in response.content
+    assert (
+        b'<h1><a href="http://testserver/items/foo">Item ID: foo</a></h1>'
+        in response.content
+    )
    response = client.get("/static/styles.css")
    assert response.status_code == 200, response.text
    assert b"color: green;" in response.content