# Create a page layout

Source: https://zotonic.com/docs/1352/create-a-page-layout

URI: https://zotonic.com/id/1352

Language: en

Use an existing site base template as your starting point. Put shared document structure in the base and page-specific markup in blocks.

```django
{% extends "base.tpl" %}
{% block content %}
<main>
    <h1>{_ Our garden _}</h1>
    <p>{_ Find out what is growing this week. _}</p>
</main>
{% endblock %}
```

Check which blocks your chosen base provides before overriding one. Keep the standard head and body includes so active modules can contribute scripts, styles, metadata, and browser initialization. In a custom base, use <a href="/id/1355" class="doc-reference doc-reference-tag"><code>tag#all_include</code></a> with the standard include names instead of copying module-specific head fragments.

In a custom base, put `{% all include "_html_head.tpl" %}` inside `<head>`. Near the end of `<body>`, keep `{% all include "_html_body.tpl" %}`, the site's `_js_include.tpl`, and one final `{% script %}` in their established order. Wires collect browser code for that final script tag; without it a page can render correctly while its buttons do nothing.

Reuse markup with includes and categories
-----------------------------------------

Extract repeated markup into a partial and pass its inputs explicitly.

```django
{% include "_garden_card.tpl" id=id %}
```

Inside the partial, read the resource using `m.rsc[id]`. Keep the partial focused on one component so another page can reuse it without inheriting unrelated page behavior.

Use a category include when the representation depends on the resource's category:

```django
{% catinclude "_garden_card.tpl" id %}
```

Provide a generic fallback and add category-specific variants when their markup differs. Use the template selection tools to check which variant wins for the resource. See <a href="/id/1326" class="doc-reference doc-reference-tag"><code>tag#include</code></a>, <a href="/id/1325" class="doc-reference doc-reference-tag"><code>tag#catinclude</code></a>, and [Find the template used by a page](/id/2941).

For the example above, save the fallback as `priv/templates/_garden_card.tpl`. An event-specific version is `_garden_card.event.tpl`. A resource named `garden_open_day` can override both with `_garden_card.name.garden_open_day.tpl`. Test an event and an ordinary text resource: the latter should still use the fallback.

Display values safely
---------------------

Resource properties read through `m.rsc` follow Zotonic's content handling. Query arguments and values returned by custom models do not automatically have the same guarantees.

Escape plain text from those sources:

```django
<p>{{ q.term|escape }}</p>
```

Do not mark arbitrary user input as safe HTML. Decide at the model or content boundary whether a field contains text, sanitized HTML, a URL, or another type. Keep that decision consistent across templates and API responses.

When a value renders unexpectedly, inspect its type and translation behavior before applying more filters. See <a href="/id/1461" class="doc-reference doc-reference-filter"><code>filter#escape</code></a>, [Expose data through a model](/id/2960), and [Keep permission checks at the boundary](/id/1536).

Cache a template fragment
-------------------------

First measure the work performed by the fragment. Cache a fragment only when you know which inputs and data changes affect its output.

Check <a href="/id/1357" class="doc-reference doc-reference-tag"><code>tag#cache</code></a> for the supported duration, variation, and dependency arguments. A fragment containing a user's private information must not be shared between users through an incomplete cache key. Language and resource identity can also change the result.

Test a cache hit, then change the underlying content and check invalidation. During debugging, the Development page can disable template cache tags. Restore that setting before measuring normal page behavior. See [Distinguish stale cache data from stale code](/id/2979) and [Choose checks for a change](/id/2983).

For a public resource card, a starting point is:

```django
{% cache 60 garden_card vary=id vary=z_language if_anonymous %}
    <a href="{{ id.page_url }}">{{ id.title }}</a>
{% endcache %}
```

The resource ID varies the entry and is a cache dependency; language separates translations. This example caches only anonymous requests. If the fragment also reads connected resources, add the corresponding dependencies. Rename a shared cache block when its output contract changes.

License: 

Attribution: 

Related resources: https://zotonic.com/api/agent/related/1352?language=en


## API access

- [API help](<https://zotonic.com/api-help>)
- [OpenAPI specification](<https://zotonic.com/openapi.json>)
- [This resource as JSON](<https://zotonic.com/api/agent/resource/1352?language=en>)
