DEV Community

Cover image for Building the RelaxTemplates Project: A Beginner-Friendly Python Template Engine
Ravi Kishan
Ravi Kishan

Posted on

Building the RelaxTemplates Project: A Beginner-Friendly Python Template Engine

Creating templating engines helps developers understand the foundation of web rendering systems. RelaxTemplates is a lightweight, Python-based template engine that simplifies the process of template rendering. Designed to be educational and beginner-friendly, RelaxTemplates illustrates core concepts like variable substitution, loops, conditionals, inheritance, and reusable snippets, making it an ideal choice for developers wanting to dive into template engine architecture.


RelaxTemplates PyPI

Why Choose RelaxTemplates?

RelaxTemplates was born out of a need to demystify template engines, allowing developers to explore templating features and build on them. Unlike production-ready engines like Django or Jinja2, RelaxTemplates emphasizes simplicity, giving users more control to experiment with adding customizations or extending functionality.


Key Features of RelaxTemplates

RelaxTemplates provides the essential features expected in modern template engines:

  1. Variable Substitution: Easily inject dynamic content into templates.
  2. Control Flow (Conditionals): Render sections based on conditions.
  3. Loops: Iterate over lists and collections with the {% each %} syntax.
  4. Callable Functions: Invoke Python functions within templates.
  5. Template Inheritance: Achieve layout inheritance with extendable blocks.
  6. Includes: Embed reusable template snippets.

Let’s explore each of these features and how to use them!


Getting Started

To start using RelaxTemplates, simply install it from PyPI:

pip install relaxtemplates
Enter fullscreen mode Exit fullscreen mode

Then, import the package and define a template file. RelaxTemplates templates are standard HTML files with special syntax to incorporate variables, blocks, and other template logic.

Basic Syntax Overview

RelaxTemplates employs a straightforward syntax using curly braces and tags to define variables, conditionals, loops, and other template elements:

  • Variables are enclosed in {{ }} for dynamic replacement.
  • Blocks like conditionals and loops are enclosed in {% %} for structure and control.

Template Syntax and Features

Variable Substitution

Variables are wrapped in {{ }} to be dynamically replaced with values from the provided context. For instance, the variable user_name in the following template is replaced by the user’s name.

<div>Hello, {{ user_name }}!</div>
Enter fullscreen mode Exit fullscreen mode

When rendered with a context like {'user_name': 'Alice'}, this outputs:

<div>Hello, Alice!</div>
Enter fullscreen mode Exit fullscreen mode

Control Flow with Conditionals

Conditionals in RelaxTemplates let you render content based on specific conditions. Supported operators include >, <, >=, <=, ==, and !=. Here’s an example:

{% if user_age > 18 %}
    <p>Welcome, adult user!</p>
{% else %}
    <p>Welcome, young user!</p>
{% end %}
Enter fullscreen mode Exit fullscreen mode

If user_age is above 18, the template outputs the first message; otherwise, it displays the alternative message.

Loops

The {% each %} block iterates over collections, providing an easy way to list items or display repeating sections.

{% each items %}
    <p>{{ it }}</p>
{% end %}
Enter fullscreen mode Exit fullscreen mode

For added flexibility, use .. within the loop to reference values from an outer scope. This is particularly useful when needing context data outside the current item:

{% each items %}
    <p>Outer name: {{ ..name }}</p>
    <p>Item: {{ it }}</p>
{% end %}
Enter fullscreen mode Exit fullscreen mode

Callable Functions

RelaxTemplates allows you to call functions directly from your templates. Functions can accept both positional and keyword arguments.

<p>{% call format_date date_created %}</p>
<p>{% call log 'Event logged' level='debug' %}</p>
Enter fullscreen mode Exit fullscreen mode

In this example, format_date and log are called within the template, enabling date formatting or logging as needed.

Template Inheritance

One of the most powerful features of RelaxTemplates is its support for template inheritance. This allows you to define a base template (e.g., a standard layout) and extend it in child templates.

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>
Enter fullscreen mode Exit fullscreen mode

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 %}
Enter fullscreen mode Exit fullscreen mode

This setup enables the child template to override specific blocks, like title and content, without redefining the entire layout.

Includes

Use {% include 'template_name' %} to insert reusable template snippets, such as a header or footer, within your templates.

{% include 'header' %}
<p>Welcome to the page!</p>
{% include 'footer' %}
Enter fullscreen mode Exit fullscreen mode

This feature helps modularize templates by separating common sections into individual files, reducing duplication and enhancing readability.


Rendering a Template: Example Workflow

  1. Define a Template and Context:

    • First, create a template file with the desired variables, loops, and conditions. Here’s an example template:
     <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 %}
    
  2. Render the Template:

    • Use RelaxTemplates to compile and render the template with context data.
     from relaxtemplates import Template
    
     context = {'user_name': 'Alice', 'is_member': True}
     template = Template('my_template.html', context)
     rendered_output = template.render()
     print(rendered_output)
    

Performance Overview

RelaxTemplates may not match the optimization of robust engines like Django or Jinja2 but performs efficiently for smaller applications and experimentation. Here’s a comparison of RelaxTemplates with other engines:

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

These results showcase that while RelaxTemplates isn’t intended for production, it’s an efficient option for testing, learning, and small-scale applications.


Contributing to RelaxTemplates

RelaxTemplates is open to contributions, and new ideas are always welcome! Whether you’re interested in adding features, optimizing code, or enhancing documentation, feel free to explore and experiment with this project.

Happy templating with RelaxTemplates!

Top comments (0)