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.
Warning
Unicorn
requires there to be one root element surrounding the component template.
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.