django-knockout-modeler 0.8.1

Quick start

0. Install django-knockout-modeler

   pip install django-knockout-modeler

1. Add ‘knockout-modeler’ to your INSTALLED_APPS setting like this:

   INSTALLED_APPS = (
     ...
     'knockout_modeler',
   )

2. Include Knockout.js in your HTML:

   <script type='text/javascript' src='https://cdnjs.cloudflare.com/ajax/libs/knockout/2.3.0/knockout-min.js'></script>

3. Knockout your QuerySet:

   {% load knockout %}
   <script>
       {{ myObjects|knockout }}
   </script>

4. Template your results:

   <script type="text/html" id="myTemplate">
       <div>
           <h2><span data-bind="text: myName"></span></h2>
           <h3><span data-bind="text: myNumber"></span></h3>
       </div>
   </script>

5. Loop over your bound data like so:

   <div id="myobjects">
       <div data-bind="template: { name: 'myTemplate', foreach: myobjects }"></div>
   </div>

Simple Usage

django-knockout-modeler can be used directly in templates to generate knockout models and knockout-ready data, or either one you choose. To put a QuerySet directly into a django template as a Knockout object, you can do this:

{{ myObjects | knockout }}

To get the data object by itself, you can do this:

{{ myObjects | knockout_data }}

Similarly, you can get just the model, if you prefer to load your data from apis, like this:

{{ myObjects | knockout_model }}

And even just the bindings:

{{ myObjects | knockout_bindings }}

Progammatic Usage

First, import it!

from knockout_modeler.ko import ko, ko_data, ko_model, ko_json, ko_data

To get the whole template, you can do this:

ko_s = ko(your_query_set)

And to get just the data string you can do this..

ko_s = ko_data(your_query_set)

or..

ko_s = ko_json(your_query_set)

And, surprisingly, you can do the same for the model string:

ko_s = ko_model(YourModel)

Custom fieldsets are also allowed:

fields = ['custom', 'fieldset', 'allowed']
ko_s= ko(entries, fields)

Access Control

If you don’t want to expose your entire model to Knockout, you can define a function in your model:

def knockout_fields(self):
    return['name', 'number']

by default, it uses the keys in the object’s to_dict() method. For computed properties, you can use python’s property function.

Sorting

django-knockout provides some convenient methods for sorting your data. By default, it will use the object’s ‘id’ field, but you can also define your own comparator like so:

@classmethod
def comparator(self):
    return 'value'

If you don’t define a comparator, ‘id’ must be in your knockout_fields.

Multi-Model Support

django-knockout is all ready set up to be used with multiple types of data at the same time, as bindings happen to specific objects:

ko.applyBindings(new MyObjectViewModel(), $('#myobjects')[0]);

which means that you somewhere in your HTML template, you will need to have an object with that id, like so:

<div id="myobjects">
    <div data-bind="foreach: myobjects">
        User <span data-bind="text: myName"></span> is number <span data-bind="text: myNumber"></span>.
    </div>
</div>

This is handy for prototyping, but more advanced applications may want to use the master ViewModel technique instead.

Multi-Data Support

If you’re using multiple QuerySets of the same type, you’ll need to define a custom name for the data variables.

{{ myObjects | knockout_data:'MyNamedObjectsData' }}

You may also pass the string “,safe” to indicate that data has been sanitized. You must also use the ‘safe’ template tag:

{{ myObjects | knockout_data:'MyNamedObjectsData,safe'|safe }}

Issues

There’s probably a lot more that can be done to improve this. Please file issues if you find them!