Writing templates
Most template languages ask you to learn a second syntax and sprinkle it through your HTML. Chameleon asks you to learn a handful of attributes. A template is always a well-formed document, and every loop and condition attaches to the element it controls. The result is markup you can read top to bottom and know exactly which element repeats, which disappears, and where the data lands. The full language reference lives at chameleon.readthedocs.io; this page covers the parts the podcast site needs.
TAL cheat sheet
<!-- Variable substitution: any Python expression inside ${ } -->
<h1>${title}</h1>
<p>${user.name.title()} has ${len(items)} item(s)</p>
<!-- Conditionals: the element is omitted entirely when the expression is falsy -->
<div tal:condition="show_banner">Special offer!</div>
<div tal:condition="not items">Nothing here yet.</div>
<!-- Loops -->
<li tal:repeat="item items">${item.name} - $${item.price}</li>
<!-- The repeat variable exposes index, number, even, odd, first and last -->
<tr tal:repeat="row data" class="${'odd' if repeat.row.odd else 'even'}">
<td>${repeat.row.number}. ${row.title}</td>
</tr>
<!-- Attributes: interpolate directly, or set several with tal:attributes -->
<a href="/items/${item.id}" class="${'active' if is_current else ''}">${item.name}</a>
<a tal:attributes="href item.url; class item.css_class">${item.name}</a>
<!-- Replace element content, or the whole element -->
<span tal:content="message">placeholder shown in a browser preview</span>
<span tal:replace="formatted_date">2024-01-01</span>
<!-- Define a local variable -->
<span tal:define="total sum(i.price for i in items)">Total: ${total}</span>Two habits pay off quickly. First, the placeholder text inside tal:content and tal:replace is what you see when you open the file in a browser without rendering it, so write something realistic there. Second, a literal $ followed by { is written $${...}, as in the price example above.
Escaping and structure
Everything inserted with ${...}, tal:content or tal:replace is HTML-escaped. A guest named <script> becomes harmless text. When you genuinely have markup that is already safe, say so with the structure keyword:
<div tal:replace="structure rich_html_content" />Treat that keyword as a promise. Only make it for HTML you generated or sanitized yourself.
File extensions
The loader does not care about the extension. .pt is the Chameleon convention, and auto-naming looks for .html first and .pt second (see the decorator guide). Any other extension works with an explicit path. The podcast’s episodes/feed.xml is a template like any other, served with content_type='application/xml'.
Alpine.js, htmx and other attribute syntaxes
Here is a surprise waiting for anyone who adds a sprinkle of Alpine.js to a Chameleon page. Chameleon runs with a restricted namespace by default, and attributes such as @click, :class, or x-on:click look to it like XML namespace prefixes it has never heard of. The template refuses to parse and you get a KeyError naming the attribute. The fix is one flag at startup:
chameleon_robyn.global_init(template_folder, restricted_namespace=False)The same flag exists on ChameleonTemplate. With the restriction off, any attribute syntax passes through to the browser untouched.
Reusable components with chameleon-partials
The episode card appears on the episode list and again on the search results page. Copying it once is fine. Copying it a third time is how layouts drift. chameleon-partials adds render_partial() for rendering a sub-template from inside a template. It keeps its own loader, so initialize both packages at startup with the same folder:
import chameleon_partials
import chameleon_robyn
chameleon_robyn.global_init(template_folder, auto_reload=dev_mode)
chameleon_partials.register_extensions(template_folder, auto_reload=dev_mode)Pass render_partial through the handler’s dict:
@app.get('/')
@chameleon_robyn.template('home/index.pt')
def index(request):
return {
'render_partial': chameleon_partials.render_partial,
'episodes': get_episodes(),
}Then insert the partial with tal:replace="structure ...":
<div tal:repeat="ep episodes">
<div tal:replace="structure render_partial('shared/episode_card.pt', ep=ep)" />
</div>structure stops Chameleon from escaping the partial’s HTML, and tal:replace swaps out the placeholder element. The example-partials/ app in the repository is the core example refactored this way. Open its episode list template next to the one in example/ and watch a block of card markup collapse into one line.