Relaxtemplates is a simplified, educational template engine designed to help developers understand the inner workings of template rendering. This project is not production-ready but instead serves as a hands-on exploration of template rendering with fundamental features commonly found in templating systems, such as variable substitution, control flow with conditionals, loops, callable functions, template inheritance, and includes.
Download from PyPI: PyPI - Relaxtemplates
Relaxtemplates was created to provide a playground for experimenting with templating features and to gain insight into template engine design. It showcases key templating principles and techniques while allowing flexibility for customizations and feature expansions.
Relaxtemplates supports the following features:
- Variable Substitution: Dynamically replace variables with values from the context.
- Control Flow (Conditionals): Use
ifconditions to control the flow of template content. - Loops: Use
eachto iterate over lists and collections. - Callable Functions: Pass and invoke callable functions within templates.
- Template Inheritance: Extend base templates with
extendandblockto achieve layout inheritance. - Includes: Insert reusable template snippets with
include.
To use Relaxtemplates, include the files in your project and create a simple template. Templates are HTML files with special syntax for variables, blocks, and includes.
Relaxtemplates uses three main syntaxes: {{ variable }}, {% block %}...{% endblock %}, and {% include %}. These enable flexible, structured templates.
Variables are enclosed in {{ }} and are replaced by corresponding values in the provided context.
<div>Hello, {{ user_name }}!</div>Blocks are enclosed in {% %} tags, allowing for control structures like conditionals and loops.
Relaxtemplates supports conditionals for control flow with operators such as >, <, >=, <=, ==, and !=. For instance:
{% if user_age > 18 %}
<p>Welcome, adult user!</p>
{% else %}
<p>Welcome, young user!</p>
{% end %}The {% each %} block allows you to iterate over a collection. The it variable represents each item in the iteration, and .. accesses attributes from the outer scope.
{% each items %}
<p>{{ it }}</p>
{% end %}Example of referencing the outer context within a loop:
{% each items %}
<p>Outer name: {{ ..name }}</p>
<p>Item: {{ it }}</p>
{% end %}The {% call %} block allows for invoking functions with both positional and keyword arguments:
<p>{% call format_date date_created %}</p>
<p>{% call log 'Event logged' level='debug' %}</p>Templates can extend a base template, providing a layout structure that child templates can override within defined blocks.
Base template (base.html):
<!DOCTYPE html>
<html>
<head>
<title>{% block title %}Default Title{% endblock %}</title>
</head>
<body>
<div id="content">
{% block content %}Default content.{% endblock %}
</div>
</body>
</html>Child template (child.html):
{% extend 'base' %}
{% block title %}Custom Page Title{% endblock %}
{% block content %}
<p>This is custom content for the child template.</p>
{% endblock %}Relaxtemplates supports includes for inserting reusable template snippets, such as headers and footers, using {% include 'template_name' %}.
{% include 'header' %}
<p>Welcome to the page!</p>
{% include 'footer' %}-
Define Template and Context: Create a template file, e.g.,
my_template.htmlwith variables, loops, and conditionals.<h1>Welcome, {{ user_name }}!</h1> {% if is_member %} <p>Thanks for being a member!</p> {% else %} <p>Please sign up to become a member.</p> {% end %}
-
Rendering: Use the
Templateclass to load, compile, and render the template with a given context.template = Template('my_template', {'user_name': 'Alice', 'is_member': True}) print(template.render())
While Relaxtemplates is a simple engine, benchmarks indicate it performs efficiently. However, it lacks the optimization layers present in more mature engines like Django or Jinja2, so it is best suited for educational use and smaller projects.
| Template | Runs | Time Taken (ms) |
|---|---|---|
| relaxtemplates | 10,000 | 0.19 |
| django | 10,000 | 0.39 |
| django_default_loader | 10,000 | 0.22 |
| jinja2 | 10,000 | 3.28 |
| jinja2_env | 10,000 | 0.10 |
Feel free to fork and explore the code. Improvements and experiments are welcome, as this project is meant for exploration and learning in template engine design.
Happy templating with Relaxtemplates!