django-crowdsourced-fields 0.4
A reusable Django app that allows to mark certain fields of your models as
masterdata. Users would still be able to enter their own values but the app
will map them to unique instances. Admin staff is able to review all user
generated entriesand mark them as approved.
License: The MIT License
Keywords: django,ORM,jQuery,combobox,models,fields

Django Crowdsourced Fields
==========================

A reusable Django app that allows to mark certain fields of your models as
masterdata. Users would still be able to enter their own values but the app
will map them to unique instances. Admin staff is able to review all user
generated entries and mark them as approved.

An example could be a vehicle site, where you would like to allow users to
enter make and model for their vehicle but you want to make sure that an
entry of "bmw" and "Bmw" results in "BMW".

The app also comes with a nice jQuery combobox for such fields, where user get
auto-suggestions while they type.

Installation
------------

You need to install the following prerequisites in order to use this app::

    pip install Django
    pip install South

If you want to install the latest stable release from PyPi::

    $ pip install django-crowdsourced-fields

If you feel adventurous and want to install the latest commit from GitHub::

    $ pip install -e git://github.com/bitmazk/django-crowdsourced-fields.git#egg=crowdsourced_fields

Add ``crowdsourced_fields`` to your ``INSTALLED_APPS``::

    INSTALLED_APPS = (
        ...,
        'crowdsourced_fields',
    )

Don't forget to migrate your database::

    ./manage.py migrate crowdsourced_fields

Add jQuery and jQuery UI to your base template or at least to the template that 
should display forms with crowdsourced fields. Also include the jQuery UI
styles and special styles provided by this app::

    <link rel="stylesheet" type="text/css" href="http://ajax.googleapis.com/ajax/libs/jqueryui/1/themes/flick/jquery-ui.css">
    {{ form.media.css }}

    <script src="//ajax.googleapis.com/ajax/libs/jquery/1.7.0/jquery.min.js"></script>
    <script src="//ajax.googleapis.com/ajax/libs/jqueryui/1.8.21/jquery-ui.min.js"></script>
    {{ form.media.js }}

You might want to include the jQuery and jQuery UI parts in your base template
and the ``{{ form.media }}`` parts only in the template that uses a form with
crowdsourced fields.

Usage
-----

Prepare your models
+++++++++++++++++++

First you need to modify the model that should have crowdsourced fields::

    from crowdsourced_fields.models import CrowdSourcedModelMixin

    class YourModel(CrowdsourcedModelMixin, models.Model):
        CROWDSOURCED_FIELDS = {
            'make': {'item_type': 'makes', }
            'model': {'item_type': 'models', }
        }

        make = models.CharField(...)
        model = models.CharField(...)

``CROWDSOURCED_FIELDS`` is a dictionary of dictionaries. The main keys are the
fields that should be crowdsourced. This must be ``CharFields``.

The inner dictionary supports the following keys as settings:

1. **item_type (mandatory)**: The name of the group under which the data of
   this field should be grouped. Let's assume you have two models and both have
   a field ``country`` which should have access to the same data. By giving
   the same ``item_type`` for the field on both models, they will use the same
   set of crowdsourced data.

For each field that you selected, the mixin will dynamically add a method
called ``fieldname_crowdsourced`` to the model. Therefore we will save both,
the value that the user actually entered (in it's original field) and a link to 
the unique and approved value that we maintain through this app.

For your staff users it is save to change the values of the
``CrowdsourcedItem`` objects. Since you should use those in your templates,
any typo fixes would be reflected on your site immediately without the need
of a datamigration.

Create a model form
+++++++++++++++++++

Next you would create a ``ModelForm`` for your model with crowdsourced fields::

    from django import forms
    from crowdsourced_fields.forms import CrowdsourcedFieldsFormMixin
    from your_app.models import YourModel

    class YourModelForm(CrowdsourcedFieldsFormMixin, forms.ModelForm):
        class Meta:
            model = YourModel

The ``CrowdsourcedFieldsFormMixin`` will do the magic for you and add replace
the original form field (a text input) with a combobox that has all existing
values ready for autosuggest.

Create your template
++++++++++++++++++++

As mentioned above, first make sure that jQuery, jQuery UI and the form's media
is available in your template.

After that you can initiate the comboboxes like so::

    $(document).ready(function(){
        $('#id_country').combobox({
            source: {{ form.country_crowdsourced_values|safe }}
        });
    });

In this case ``country`` would be the name of the form field.


Contribute
----------

If you want to contribute to this project, please perform the following steps::

    # Fork this repository
    # Clone your fork
    $ mkvirtualenv -p python2.7 django-crowdsourced-fields
    $ pip install -r requirements.txt
    $ ./online_docs/tests/runtests.sh
    # You should get no failing tests

    $ git co -b feature_branch master
    # Implement your feature and tests
    $ ./crowdsourced_fields/tests/runtests.sh
    # You should still get no failing tests
    # Describe your change in the CHANGELOG.txt
    $ git add . && git commit
    $ git push origin feature_branch
    # Send us a pull request for your feature branch

Whenever you run the tests a coverage output will be generated in
``tests/coverage/index.html``. When adding new features, please make sure that
you keep the coverage at 100%.

If you are making changes that need to be tested in a browser (i.e. to the
CSS or JS files), you might want to setup a Django project, follow the
installation insttructions above, then run ``python setup.py develop``. This
will just place an egg-link to your cloned fork in your project's virtualenv.

Roadmap
-------

Check the issue tracker on github for milestones and features to come.