Save Developer Time with django CMS Frontend 2 and Its Component-First Principle

March 28, 2025

In modern web development, efficiency is key. Developers are constantly looking for ways to reduce redundancy, improve maintainability, and speed up project delivery. Djangocms-frontend version 2 introduces the component-first principle and makes it easier than ever to build consistent, reusable frontend elements while integrating seamlessly with django CMS.

The Problem: Repetitive Frontend Development

In traditional Django projects, developers often find themselves writing similar frontend code repeatedly across templates. Whether it's buttons, alerts, grids, or complex UI elements, maintaining consistency becomes a challenge. Without a structured approach, styling and functionality can become fragmented, leading to longer development cycles and difficult maintenance.

The Solution: Component-First Approach in django CMS Frontend 2

django CMS Frontend 2 introduces a component-first approach, meaning that UI elements are treated as reusable, configurable components rather than static HTML snippets. These components can be used both as django CMS plugins and within regular Django templates using the new {% plugin %} template tag, allowing for flexible and efficient development.

Benefits of a component-first approach

Simplicity – Define UI components once as you need them. Content editors do not have to click together a component from its parts.
Consistency – Ensure a unified design across the entire project.
Faster Development – Reduce the need to write repetitive code.
Easy Customization – Modify component properties without altering core templates.
Works with Any CSS Framework – Fully compatible with Bootstrap 5 and other frontend frameworks.

Example Hero Component

Setting Up the Template Structure

Begin by organizing your Django app's template directory to include a cms_components folder. This is where your custom components will reside. The directory structure should look like this:

your_app/
 ├── admin.py
 ├── migrations/
 ├── models.py
 ├── templates/
 │ └── your_app/
 │   └── cms_components/
 │     └──hero.html
 └── views.py

This setup ensures that Django CMS can locate and register your custom components automatically.

Creating the Hero Component Template

Within the cms_components directory, create a file named hero.html with the following content:

{% load frontend cms_component %}

{# Declare component - template tags are evaluated at project startup and will render empty #}
{% cms_component "Hero" name="My Hero Component" %}
{% field "title" forms.CharField required=True name="Title" %}
{% field "slogan" forms.CharField required=True name="Slogan" widget=forms.Textarea %}
{% field "hero_image" ImageFormField required=True name="Image" help_text="At least 1024px wide image" %}

{# Actual template - when rendering, declared fields are available in the context #}
<section class="hero-section">
  <h1>{% inline_field "title" %}</h1>
  <p>{% inline_field "slogan" %}</p>
  <img alt="{{ title }}" src="{{ hero_image.url }}" /> 
  {% childplugins %} {% endchildplugins %} 
</section>

I did not add styling here. Add styling for your project's CSS framework and you're done!

Congratulations, you have just created your first django CMS plugin based on a template component.

It allows for inline editing of the title and slogan fields.
It has an image and link.
It renders child plugins.

Still: No Python code, no Django models, no registration decorators – just an extended template.

What you can do

Creating custom components is at the core of utility-class-based CSS frameworks like Tailwind CSS.

It can also be a great benefit for sites using pre-built components, as offered by Bootstrap, for example: You could define, say, a custom pricing card component which includes styling for the card, card-title, the card's inner content, buy buttons etc without editors having to pull together the corresponding card, button, and text plugins manually. The resulting plugin tree is less nested and offers a clearer layout.

Understanding the Process

When djangocms-frontend initializes, it processes the {% cms_component %} and {% field %} tags of all templates found in an app's templates folder under <app_name>/cms_components. It dynamically creates the corresponding plugin classes. This means that without writing additional Python code, you can define complex, reusable components solely through template declarations.

This approach significantly accelerates development time and reduces the potential for errors.

For more, see djangocms-frontend's documentation!