Template basics
A component's template turns its data into the HTML people see. Most of a template is ordinary HTML. A few additions let Python fill in values, set attributes, show or repeat content, and place other components.
This page shows those additions in one example, then lists where each one is explained.
<!-- heading = "Reading list"
books = ["Dune", "Kindred"] -->
<section c-class="['shelf', {'has-books': books}]">
<h1>
{{ heading }}
</h1>
<p c-for="book in books">
{{ book }}
</p>
<p c-empty>
No books yet.
</p>
</section>
Citry runs the Python in this template on the server, before the HTML reaches the browser. It inserts the heading, adds the has-books class, and writes one paragraph for every book.
Find the syntax
| You want to | Write | Read |
|---|---|---|
| Insert a Python value as text | {{ user.name }} | Expressions |
| Set an attribute or component input from Python | c-title="heading" | Attributes |
| Show, hide, or repeat content | c-if, c-for | Conditions and loops |
| React to clicks and typing in the browser | @click, :title, v-* | Vue in templates |
| Pass browser data to a child component | :status="current" | Props and events |
| Call a Python event handler from the page | @c-click="save" | Events |
| Keep a form field in step with server data | :c-query="refresh" | Bind events in templates |
| Place a component or a built-in tag | <c-Card>, <c-slot> | Components, Built-in tags |
| Pass a piece of markup as an input | c-body="<>...</>" | Markup in attributes |
| Leave a comment | {# ... #} | Comments |
| Show template-looking text unchanged | <c-raw> | Literal text |
Where each part runs
Two kinds of code can appear in a template:
- Python, in
{{ ... }}andc-*attributes. It runs on the server each time Citry renders the component. - JavaScript, in Vue attributes such as
@clickand:title. It runs in the browser after the page loads, without asking the server to render again.
Use Python to decide what the page contains. Use Vue when part of the page should change straight away in response to the user. Start with Vue in templates for that.
c-* attributes
An ordinary attribute holds fixed text. Put c- in front of the name to make the value a Python expression. Citry evaluates it and removes the c-:
<!-- heading = "My title" -->
<p title="Static title">
<p c-title="heading.upper()">
The browser receives:
<p title="Static title">
<p title="MY TITLE">
{{ ... }} does not work inside a tag, so title="{{ heading }}" keeps the braces as literal text. Attributes covers classes, styles, and passing values to components.
Write valid tags
Opening and closing tags must match; the match ignores case. Void elements such as <input> and <br> need no closing tag. Any other tag may close itself:
<input name="query">
<span />
<c-StatusBadge />
<span /> renders as <span></span>.
An attribute with no value, such as required, is a bare attribute. On an HTML element it stays bare. On a component tag it passes the Python value True. A written value always passes a string, even an empty one, so alt="" passes "":
<input required>
<c-Button compact />
<c-Avatar alt="" />
Attribute values may use double quotes, single quotes, or no quotes. Quote every c-* expression, so spaces and operators stay inside the value.
Use lowercase c-
Citry syntax always starts with a lowercase c-. The component name after it ignores case, so <c-StatusBadge> and <c-statusbadge> find the same component.
Built-in tags such as <c-if>, <c-for>, and <c-slot> must be written in lowercase. <c-If> is an error.
Pass text through
HTML comments, <!doctype html>, and processing instructions pass through to the output unchanged.
Citry has no Django or Jinja block tags. Text such as {% include "menu.html" %} stays in the page as written.
Nesting limits
Tags inside tags can go at most 512 levels deep. At most 256 of those levels can be Citry logic levels: every c- tag except <c-raw>, and each c-if=, c-elif=, c-else, c-for= or c-empty attribute. Each tag is one level, and each of those attributes on it adds one more, so this <div> is three levels, two of them logic:
<div c-if="visible" c-for="item in items">{{ item }}</div>
Rendering a template that goes one level past either limit raises SyntaxError, pointing at the tag that goes too deep, and citry check reports the same problem without rendering. To go deeper, move the inner part into its own component's template, which starts counting again from zero. Markup you pass to a component between its tags, or in an attribute, still counts toward the template that writes it.
A component can pass its slot content on to another component's slot by writing <c-slot /> inside its <c-fill>, and that one can pass it on again. Such a chain can be long: Citry renders it in a fixed amount of Python's stack, up to max_component_depth (2000 components by default). Content passed on through an expression instead, such as {{ content }} where template_data() returns slots["default"], or through a Python slot function that calls the fill, uses about 11 levels of Python's stack for each component, so a chain of about 80 of those can raise RecursionError.
Other components render any depth of c-if and c-for in a fixed amount of Python's stack. A simple = "vue" component uses one level of Python's stack for each level of c-if or c-for nesting in its template, written as a tag or as an attribute. A template with 256 such levels uses about 270 levels of Python's stack to render. Python's default recursion limit is 1,000, which leaves about 700 for your web framework and the code around the render. If the whole stack goes past that limit, rendering raises RecursionError, so nest fewer c-if and c-for levels in that component.
In a component that uses Vue, the server writes at most 400 levels of elements inside the component, which leaves room in Chrome for the page around it. Past that depth, the server writes a preview of the deeper part, and Vue renders that part again when it starts in the browser.