Create your first component

A component in django-components can be as simple as a Django template and Python code to declare the component:

calendar.html

<div class="calendar">
  Today's date is <span>{{ date }}</span>
</div>

calendar.py

from django_components import Component

class Calendar(Component):
    template_file = "calendar.html"

Or a combination of Django template, Python, CSS, and Javascript:

calendar.html

<div class="calendar">
  Today's date is <span>{{ date }}</span>
</div>

calendar.css

.calendar {
  width: 200px;
  background: pink;
}

calendar.js

document.querySelector(".calendar").onclick = function () {
  alert("Clicked calendar!");
};

calendar.py

from django_components import Component

class Calendar(Component):
    template_file = "calendar.html"
    js_file = "calendar.js"
    css_file = "calendar.css"

Alternatively, you can "inline" HTML, JS, and CSS right into the component class:

from django_components import Component

class Calendar(Component):
    template = """
      <div class="calendar">
        Today's date is <span>{{ date }}</span>
      </div>
    """

    css = """
      .calendar {
        width: 200px;
        background: pink;
      }
    """

    js = """
      document.querySelector(".calendar").onclick = function () {
        alert("Clicked calendar!");
      };
    """

Note

If you "inline" the HTML, JS and CSS code into the Python class, you can set up syntax highlighting for better experience. However, autocompletion / intellisense does not work with syntax highlighting.

We'll start by creating a component that defines only a Django template:

1. Create project structure¤

Start by creating empty calendar.py and calendar.html files:

sampleproject/
├── calendarapp/
├── components/             🆕
│   └── calendar/           🆕
│       ├── calendar.py     🆕
│       └── calendar.html   🆕
├── sampleproject/
├── manage.py
└── requirements.txt

2. Write Django template¤

Inside calendar.html, write:

[project root]/components/calendar/calendar.html

<div class="calendar">
  Today's date is <span>{{ date }}</span>
</div>

In this example we've defined one template variable date. You can use any and as many variables as you like. These variables will be defined in the Python file in get_context_data() when creating an instance of this component.

Note

The template will be rendered with whatever template backend you've specified in your Django settings file.

Currently django-components supports only the default "django.template.backends.django.DjangoTemplates" template backend!

3. Create new Component in Python¤

In calendar.py, create a subclass of Component to create a new component.

To link the HTML template with our component, set template_file to the name of the HTML file.

[project root]/components/calendar/calendar.py

from django_components import Component

class Calendar(Component):
    template_file = "calendar.html"

Note

The path to the template file can be either:

Relative to the component's python file (as seen above),
Relative to any of the component directories as defined by COMPONENTS.dirs and/or COMPONENTS.app_dirs (e.g. [your apps]/components dir and [project root]/components)

4. Define the template variables¤

In calendar.html, we've used the variable date. So we need to define it for the template to work.

This is done using Component.get_context_data(). It's a function that returns a dictionary. The entries in this dictionary will become available within the template as variables, e.g. as {{ date }}.

[project root]/components/calendar/calendar.py

from django_components import Component

class Calendar(Component):
    template_file = "calendar.html"

    def get_context_data(self):
        return {
            "date": "1970-01-01",
        }

Now, when we render the component with Component.render() method:

Calendar.render()

It will output

<div class="calendar">
  Today's date is <span>1970-01-01</span>
</div>

And voilá!! We've created our first component.

Next, let's add JS and CSS to this component ➡️.