Skip to main content

A magical full-stack framework for Django.

Project description

django-unicorn logo

Unicorn

The magical reactive component framework for Django ✨

PyPI PyPI - Downloads coverage GitHub Sponsors All Contributors

Unicorn adds modern reactive component functionality to your Django templates without having to learn a new templating language or fight with complicated JavaScript frameworks. It seamlessly extends Django past its server-side framework roots without giving up all of its niceties or forcing you to rebuild your application. With Django Unicorn, you can quickly and easily add rich front-end interactions to your templates, all while using the power of Django.

https://www.django-unicorn.com has extensive documentation, code examples, and more!

⚡ Getting started

1. Install the package

pip install django-unicorn OR poetry add django-unicorn

2. Add django_unicorn to INSTALLED_APPS

# settings.py
INSTALLED_APPS = (
    # other apps
    "django_unicorn",
)

3. Update urls.py

# urls.py
import django_unicorn

urlpatterns = (
    # other urls
    path("unicorn/", include("django_unicorn.urls")),
)

4. Add Unicorn to the HTML template

<!-- template.html -->
{% load unicorn %}

<html>
  <head>
    {% unicorn_scripts %}
  </head>
  <body>
    {% csrf_token %}
  </body>
</html>

5. Create a component

python manage.py startunicorn myapp COMPONENT_NAME

Unicorn uses the term "component" to refer to a set of interactive functionality that can be put into templates. A component consists of a Django HTML template and a Python view class which contains the backend code. After running the management command, two new files will be created:

  • myapp/templates/unicorn/COMPONENT_NAME.html (component template)
  • myapp/components/COMPONENT_NAME.py (component view)

6. Add the component to your template

<!-- template.html -->
{% load unicorn %}

<html>
  <head>
    {% unicorn_scripts %}
  </head>
  <body>
    {% csrf_token %}

    {% unicorn 'COMPONENT_NAME' %}
  </body>
</html>

Example todo component

The unicorn: attributes bind the element to data and can also trigger methods by listening for events, e.g. click, input, keydown, etc.

<!-- todo.html -->

<div>
  <form unicorn:submit.prevent="add">
    <input type="text"
      unicorn:model.defer="task"
      unicorn:keyup.escape="task=''"
      placeholder="New task" id="task"></input>
  </form>
  <button unicorn:click="add">Add</button>
  <button unicorn:click="$reset">Clear all tasks</button>

  <p>
    {% if tasks %}
      <ul>
        {% for task in tasks %}
          <li>{{ task }}</li>
        {% endfor %}
      </ul>
    {% else %}
      No tasks 🎉
    {% endif %}
  </p>
</div>
# todo.py

from django_unicorn.components import UnicornView
from django import forms

class TodoForm(forms.Form):
    task = forms.CharField(min_length=2, max_length=20, required=True)

class TodoView(UnicornView):
    form_class = TodoForm

    task = ""
    tasks = []

    def add(self):
        if self.is_valid():
            self.tasks.append(self.task)
            self.task = ""

✨ Wait, is this magic?

Sort of! At least it might feel like it. 🤩

  1. Unicorn progressively enhances a normal Django view, so the initial render is fast and great for SEO.
  2. Unicorn binds to the elements you specify and automatically makes AJAX calls when needed.
  3. Unicorn seamlessly updates the DOM when the HTML changes.

Focus on building regular Django templates and Python classes without needing to switch to another language or use unnecessary infrastructure.

🤯 But wait, there's more!

As if that wasn't enough, other features include:

📖 Dig In

❤️ Support

This project is supported by GitHub Sponsors and Digital Ocean.

🔧 Contributors

Check out this guide for more details on how to contribute.

Thanks to the following wonderful people (emoji key) who have helped build Unicorn.

Adam Hill
Adam Hill

💻 ⚠️
Andres Vargas
Andres Vargas

💻
Eddy Ernesto del Valle Pino
Eddy Ernesto del Valle Pino

💻
Yaser Al-Najjar
Yaser Al-Najjar

💻
Stephan Traub
Stephan Traub

⚠️
Fredrik Borg
Fredrik Borg

💻 ⚠️
mbacicc
mbacicc

💻
Ron
Ron

📖
Franziskhan
Franziskhan

💻
Josh Higgins
Josh Higgins

⚠️ 💻
Amayas Messara
Amayas Messara

💻
Apoorva Pandey
Apoorva Pandey

⚠️ 💻
Christian González
Christian González

💻 📖
robwa
robwa

💻 ⚠️
Preston Badeer
Preston Badeer

📖
Sergei
Sergei

📖 💻 ⚠️
bazubii
bazubii

💻 ⚠️
Dan Caron
Dan Caron

📖
Shantanu
Shantanu

💻
regoawt
regoawt

💻 ⚠️
Lasse H. Bomholt
Lasse H. Bomholt

💻
Martey Dodoo
Martey Dodoo

📖
Pierre
Pierre

💻
Roman Imankulov
Roman Imankulov

⚠️ 💻
Lemi Boyce
Lemi Boyce

💻
Jack Sundberg
Jack Sundberg

💻
siliconcow
siliconcow

💻 ⚠️
Akintola Rahmat
Akintola Rahmat

💻
Mario Munoz
Mario Munoz

📖
Emily Wood
Emily Wood

💻
Jeremy Wright
Jeremy Wright

💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_unicorn-0.62.0.tar.gz (85.3 kB view details)

Uploaded Source

Built Distribution

django_unicorn-0.62.0-py3-none-any.whl (96.4 kB view details)

Uploaded Python 3

File details

Details for the file django_unicorn-0.62.0.tar.gz.

File metadata

  • Download URL: django_unicorn-0.62.0.tar.gz
  • Upload date:
  • Size: 85.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.6.1 CPython/3.10.8 Darwin/23.2.0

File hashes

Hashes for django_unicorn-0.62.0.tar.gz
Algorithm Hash digest
SHA256 dedf97e4c59e288537911c995a6d0c08615bd3274bb77b43e8031f4c2d365082
MD5 2410e080ee73f984c113cf6485556e52
BLAKE2b-256 cc4b767fde742ce6d17f6a55886bcbcb19ba6dfe5698e6c80f304f7887c58a36

See more details on using hashes here.

File details

Details for the file django_unicorn-0.62.0-py3-none-any.whl.

File metadata

  • Download URL: django_unicorn-0.62.0-py3-none-any.whl
  • Upload date:
  • Size: 96.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.6.1 CPython/3.10.8 Darwin/23.2.0

File hashes

Hashes for django_unicorn-0.62.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f728b0ad030334cf2602f2d076e464984f683fb031a22afa794a0d2fe1468ecf
MD5 f97fb77da5e50b15fdd7b4ddcd17f2d7
BLAKE2b-256 19db490c1ae999278101a99f90e21a7863fa3679092784209e95dcdd62fb8061

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page