Templating

The Templating API is responsible for providing a simple interface to define templates (e.g., HTML templates) and render them at runtime.

Basic Usage

The interface for the templating module is minimal.

>>> from canvas_core import templating

>>> template_body = "<h1>{{ message }}</h1>"
>>> render_context = {"message": "Hello, world"}

# Render a template string.
>>> templating.render_template_string(template_body, render_context)
'<h1>Hello, world</h1>'

# Create a reusable Template object (stored in the database with a unique key).
>>> template = templating.create_template("my-template", template_body)

# Render a Template object.
>>> templating.render_template(template, render_context)
'<h1>Hello, world</h1>'

# Retrieve a Template object by its key.
>>> template = templating.get_template("my-template")
<Template: my-template>

# Update a Template object by its key.
>>> updated_template = templating.update_template("my-template", '<h1 class="fancy">{{ message }}</h1>')

# Delete a Template by its key.
>>> deleted_template = templating.delete_template("my-template")
>>> templating.get_template("my-template")
LookupError: Unable to find a template with key 'my-template'. Is it correct?

API Reference

class canvas_core.templating.PostTemplateRender(**attrs: Any)

An event emitted after a template is rendered.

class canvas_core.templating.PreTemplateRender(**attrs: Any)

An event emitted immediately before a template is rendered.

canvas_core.templating.create_template(key: str, body: str) → Template

Create a template.

Parameters:

• key – The unique key used to look up the Template.

• body – The Template body.

Returns:

The newly-created Template instance.

canvas_core.templating.delete_template(key: str) → Template | None

Delete a Template by its key.

canvas_core.templating.get_template(key: str) → Template

Return the Template with the given key.

Parameters:

key – The unique key of the Template.

Returns:

The Template instance with the given key.

Raises:

LookupError when a Template with the given key cannot be not found. –

canvas_core.templating.get_template_model() → type[Template]

Return the Template model.

Useful for creating relationships between another model and a Template.

Returns:

The Template model class.

canvas_core.templating.render_template(template: str | Template, context: dict[str, Any] | None = None) → SafeString

Render the given Template instance with the given context.

Parameters:

• template – The Template model instance (or its string key) to render.

• context – A dict containing context necessary for rendering the template.

Returns:

The rendered template string.

canvas_core.templating.render_template_string(template_body: str, context: dict[str, Any] | None = None, template_name: str | None = None) → SafeString

Render the given string as a Django Template with the given context.

Parameters:

• template_body – A string containing a valid template.

• context – A dict containing context necessary for rendering the template.

Returns:

The rendered template string.

canvas_core.templating.update_template(key: str, body: str) → Template

Update an existing Template by its key.

Parameters:

• key – The unique key by which to find the Template.

• body – The new Template body.

Returns:

The updated Template instance.