adamghill / django-unicorn Goto Github PK

View Code? Open in Web Editor NEW

2.3K 24.0 118.0 4.84 MB

The magical reactive component framework for Django ✨

Home Page: https://www.django-unicorn.com

License: MIT License

Python 67.41% JavaScript 26.85% HTML 5.73% CSS 0.01%

django python javascript fullstack frontend-framework

django-unicorn's Introduction

Unicorn
The magical reactive component framework for Django ✨

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):
    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. 🤩

Unicorn progressively enhances a normal Django view, so the initial render is fast and great for SEO.
Unicorn binds to the elements you specify and automatically makes AJAX calls when needed.
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} 💻 ⚠️	_{Andres Vargas} 💻	_{Eddy Ernesto del Valle Pino} 💻	_{Yaser Al-Najjar} 💻	_{Stephan Traub} ⚠️	_{Fredrik Borg} 💻 ⚠️	_mbacicc 💻
_Ron 📖	_Franziskhan 💻	_{Josh Higgins} ⚠️ 💻	_{Amayas Messara} 💻	_{Apoorva Pandey} ⚠️ 💻	_{Christian González} 💻 📖	_robwa 💻 ⚠️
_{Preston Badeer} 📖	_Sergei 📖 💻 ⚠️	_bazubii 💻 ⚠️	_{Dan Caron} 📖	_Shantanu 💻	_regoawt 💻 ⚠️	_{Lasse H. Bomholt} 💻
_{Martey Dodoo} 📖	_Pierre 💻	_{Roman Imankulov} ⚠️ 💻	_{Lemi Boyce} 💻	_{Jack Sundberg} 💻	_siliconcow 💻 ⚠️	_{Akintola Rahmat} 💻
_{Mario Munoz} 📖	_{Emily Wood} 💻	_{Jeremy Wright} 💻

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

django-unicorn's People

Contributors

Stargazers

Watchers

Forkers

zodman edelvalle mikeabrahamsen nyradr abbazs yaseralnajjar frbor weiplanet borisms55 jcirni lmyfzx alfredo-ardito barseghyanartur sbidy cleonello library-collections yosephoche poiedk diemesleno maximdeclercq joetib erteno queolda djaizz michaelpb axwalker franziskhan hauptmj nerdoc trendingtechnology joshiggins mayasmess kalebscholes viviengiraud sal-git jeffallan hrmsajith julyzergcn trolldbois robwa teury mogulh archmonger phuongnqk kennest jacopsd bitplorer nielsonsantana mdawso04 britisharmy data-gami alperbek clangley heitorlouzeiro allmanaj thangloigroup duckheada pbadeer francescocaponio agarjoshua iwalucas jalexmelendez bazubii jottenlips matthijz98 gg-big-org avi202020 dancaron johndiginee davidebianchi03 satpalsinghhere 91kingt arpitjain799 azizur77 hauntsaninja styria-digital gschurck rcoffie flipify regoawt frnidito swoldanski lassebomh ibrahimkoyuncu jade2290 vsajip martey natehouk webdevsquad bloodywing hendi imankulov siavashoutadi pa-hqt felipmartins marcogandra elya5 oisy92 recurvelabs jacksund

django-unicorn's Issues

CSRF token can't be found

If {% csrf_token %} is on the page after {% unicorn_scripts %} nothing works.

[Feature] add the posibility of move unicorn/components/<module>.py to a custom place like myapp/views.py

you can define:

# settings.py
UNICORN_COMPONENTS_PREFIX  = [
'myapp.views','unicorn.components',
]

The locations where the UnicornCompornent will import.

Handle `lazy` modifier

Add support for unicorn:model.lazy to change the event listener to be blur instead of input.

Move the Javascript code into namespace

Handle kwargs in method calls

loading delay modifier

To prevent flicker only show/remove unicorn:loading when the action takes longer than 200ms.

Validation on models

Test that `radio` buttons work

Meta.updates_querystring to provide property information in the querystring

GitHub action to run unittests on PRs

Textarea is not keeping input updates

Listen for all events, not just `click`

Handle `debounce` modifier

Add support for something like unicorn:model.debounce.1000ms to set debounce timeout.

`event` variable for use in actions

Handle multiple actions on the same element

For example:
<input unicorn:keyup.enter="add" unicorn:keyup.escape="clear"></input>

Model bind to a nested property

Either a property array, dictionary or object. Probably should use dot notation to access.

e.g. <input type="text" unicorn:model="blog.author.name">

Possible directory error in default examples

Hi. I've created an empty django project to test unicorn. But somehow the default instructions don't seem to work and cause a template not found error. Here's what I've done:

Created a new django project in pycharm
pip install django-unicorn
Added "django_unicorn", to the INSTALLED_APPS
Created an empty base.html file and made it viewable in the browser
Added path("unicorn/", include("django_unicorn.urls"))
Added {% load unicorn %} to the top of base.html
Added {% unicorn_scripts %} right underneath in base.html
Ran python manage.py startunicorn hello-world
Added {% unicorn 'hello-world' %} at the bottom of base.html

After this last step 9 it starts to break and throws a TemplateDoesNotExist error:
django.template.loaders.filesystem.Loader: /home/user/uniplayground/templates/unicorn/hello-world.html (Source does not exist)

In my project folder the hello-world.html file generated by step 8 is located under:
/home/user/uniplayground/unicorn/templates/unicorn/hello-world.html

Am I doing something wrong or does the startunicorn command not generate the files into the right structure?

Edit: Moving the HTML file to the template folder that django is looking in seems to work. While leaving the python file in the generated folder structure.

Computed property

$model special action variable

It would be useful to handle the special action argument $model being passed into an action. Probably only useful for db models since normal models can just do self.whatever in the component view code.

<div>
  {% for book in books %}
  <div u:db="book" u:pk="{{ book.id }}">
    <button u:click="delete($model)`>
    <!-- <button u:click="delete({{ book.id }})`> -->
  </div>
  {% endfor %}
</div>

from django_unicorn.components import UnicornView
from books.models import Book

class DbModelView(UnicornView):
    # magically instantiate the appropriate book instance object here based on model class and pk
    def delete(book):
         book.delete()

    # normal way call action with a model requires passing around an id/pk/slug and looking it up
    # def delete(book_id):
    #    book = Book.objects.get(id=book_id)
    #    book.delete()

    class Meta:
        db_models = [DbModel("book", Book)]

Add checksum to verify that forms don't change mid-flight

The Component class generates a checksum based on the attribute names which could be used to verify that the component gets updated in the message view code.

Django model on property doesn't reset as expected

When using a Django model as a property, if a field is updated as part of unicorn:model, the model will not get reset as expected.

class HelloWorldView(UnicornView):
    book = Book(title="The Sandman")

<input unicorn:model="book.title" type="text" id="bookId">

Split up unicorn.js into separate files

When a model and action fire at the same time, the sync input can be lost

I was not seeing this on local dev with 0.6.0, but it happens when deployed. I am now able to replicate it on local by throttling network responses.

I think I need to merge the syncInput and callMethod actions that fire "at the same time" into the payload array so that the syncInput doesn't get lost.

Investigate pysimdjson instead of orjson

https://github.com/TkTech/pysimdjson

Handle basic Python types in action method calls

Ideally these types would be supported passed into a method call: string, int, decimal, uuid, datetime, dict, list, tuple, set.

Use msgpack to reduce the size of the payload

https://msgpack.org/index.html

Javascript: https://github.com/kawanet/msgpack-lite
Python: https://github.com/vsergeev/u-msgpack-python

Test that `textarea` works

Looks promising

How can I help? I’m a web designer/developer (HTML + CSS) and haven’t taken the leap into the front-end frameworks.

I like the idea of components but all of the overhead in the front-end frameworks is overwhelmingly complex and changes far too often to keep up with a small team.

We have a couple of projects which use Django with templates.

This project looks like something we would be interested in.

How can we help?

Set property shortcut

Instead of having to create set_name() methods, support something like name='World'.

Model binding to queryset doesn't propogate the change to the model as expected

Investigate using async view for message endpoint

Once Django 3.1 and async views are available, see how hard it would be to use an async view if configured.

Handle multiple of the same components when loaded on the same page

Investigate alternative Python parsers

https://github.com/pyparsing/pyparsing might be saner than the string parsing done in https://github.com/adamghill/django-unicorn/blob/master/django_unicorn/call_method_parser.py.

Fix Github actions error

`prevent` modifier on actions

Add unit tests around the javascript

Potentially use https://github.com/avajs/ava?

Interaction glitch w/ BitWarden

hello Adam, long time no talk!

I was trying out the demo on the website and something BitWarden is doing to the input box, I think added it's own attribute to the html, causes the input to be redrawn empty but if you click the button add it will still load something but not everything.

Video:
django-unicorn-glitch.mov.zip

If I disable BitWarden and reload the page, the interaction works fine.

Setting to define applications to look in for components

Instead of only looking in the unicorn app, be able to set an array of apps to check for components.

Extra examples (upvote and chat)

Not sure if it is possible yet but the ability to upvote on multiple tabs/browsers and chat.

Updating class variables from outside

HI Adam!

It would be useful to be able to update the unicorn component class variables from another Django app.
You mentioned an API call or database hookup on the page refresh.
How would this be done?

Would this also be possible via AJAX or a Javascript hook?

Thanks!

Ashirvad

Add the possibility to set django variables as action parameters.

Investigate using class-based view instead of the custom Component class

Maybe there is a way to reuse a class-based view instead of the custom Component does now.

Cast to a particular property type

Strings and booleans get cast as expected, but it'd be nice to have a mechanism to cast to a particular type inside the component. The canonical example would be a datetime coming from a HTML input and getting parsed to be a datetime` object inside the component.

class TestView(UnicornView):
    name = "hello-world"
    def __init__(self, var):
         self.var = var
    def set_var(self, var):
         self.var = var

{% unicorn 'hello-world' with var=var %}      (django {% include %} like )

Or to be able to send arguments to Unicorn.call :

{% unicorn 'hello-world' %}

<button onclick="Unicorn.call('hello-world', 'set_var', 'var_value');">Set the name from outside the component</button>

Even if it's just sending a one-shot primitives it will be very helpful to give some context to the unicorn view.

[Bug] Documentation install missing add the csrf_token templatetag

CSRF token is missing. Do you need to add {% csrf_token %}?