Templates

Templates are just normal Django HTML templates, so anything you could normally do in a Django template will still work, including template tags, filters, loops, if statements, etc.

django-unicorn requires there to be a root div element surrounding the component template.

Polling

unicorn:poll can be added to the root div element of a component to have it refresh the component automatically every 2 seconds. The polling is smart enough that it won't poll when the page is not active.

A method can also be specified if there is a specific method on the component that should called every time the polling fires. For example, unicorn:poll="get_updates" would call the get_updates method instead of the built-in refresh method.

To define a different refresh time in milliseconds, a modifier can be added as well. unicorn:poll-1000 would fire the refresh method every 1 second, instead of the default 2 seconds.

<!-- polling_every_five_seconds.html -->
<div unicorn:poll-5000="get_updates">
    <input unicorn:model="update" type="text" id="text">
    {{ update }}
</div>

Model modifiers

Lazy

To prevent updates from happening on every input, you can append a lazy modifier to the end of unicorn:model. That will only update the component when a blur event happens.

<!-- waits-for-blur.html -->
<div>
    <input unicorn:model.lazy="name" type="text" id="name">
    Hello {{ name|title }}
</div>

Debounce

The debounce modifier configures how long to wait to fire an event. The time is always specified in milliseconds, for example: unicorn:model.debounce-1000 would wait for 1000 milliseconds (1 second) before firing the message.

<!-- waits-1-second.html -->
<div>
    <input unicorn:model.debounce-1000="name" type="text" id="name">
    Hello {{ name|title }}
</div>

Defer

The defer modifier will store and save model changes until the next action gets triggered. This is useful to prevent additional network requests until an action is triggered.

<!-- defer.html -->
<div>
    <input unicorn:model.defer="task" type="text" id="task">
    <button unicorn:click="add">Add task</button>
    <ul>
        {% for task in tasks %}
        <li>{{ task }}</li>
        {% endfor %}
    </ul>
</div>

Chaining modifiers

Lazy and debounce modifiers can even be chained together.

<!-- waits-for-blur-and-then-5-seconds.html -->
<div>
    <input unicorn:model.lazy.debounce-5000="name" type="text" id="text">
    Hello {{ name|title }}
</div>

Key

Smooth updates

Setting a unique id on elements with unicorn:model will prevent changes to an input from being choppy when there are lots of updates in quick succession.

<!-- choppy-updates.html -->
<input type="text" unicorn:model="name"></input>
<!-- smooth-updates.html -->
<input type="text" id="someFancyId" unicorn:model="name"></input>

However, setting the same id on two elements with the same unicorn:model won't work. The unicorn:key attribute can be used to make sure that the elements can be synced as expected.

<!-- missing-updates.html -->
<input type="text" id="someFancyId" unicorn:model="name"></input>
<input type="text" id="someFancyId" unicorn:model="name"></input>
<!-- this-should-work.html -->
<input type="text" id="someFancyId" unicorn:model="name"></input>
<input type="text" id="someFancyId" unicorn:model="name" unicorn:key="someFancyKey"></input>

DOM merging

The Javascript library used to merge changes in the DOM, morphdom, uses an element's id to intelligently update DOM elements. If it isn't possible to have an id attribute on the element, unicorn:key will be used if it is available.