+
-selected:
+
-
+Development version
+-------------------
-[Note: screen shots are from the older version. Styling has changed slightly]
+NOTE: this is the README for the current development version.
-1. User types a few characters
-2. Ajax request sent to the server
-3. The dropdown menu shows choices
-4. User selects by clicking or using arrow keys
-5. Selected result displays in the "deck" area directly below the input field.
-6. User can click trashcan icon to remove a selected item
+The latest current stable release is visible on the master branch: https://github.com/crucialfelix/django-ajax-selects/tree/master
-Features
-========
-+ Works in any form including the Django Admin
-+ Popup to add a new item
-+ Admin inlines
-+ Compatible with widget/form media, staticfiles, asset compressors etc.
-+ Automatically Loads jQuery UI mode allows easy installation by automatic inclusion of jQueryUI from the googleapis CDN
-+ Customize HTML, CSS and JS
-+ JQuery triggers allow you to customize interface behavior to respond when items are added or removed
-+ Default (but customizable) security prevents griefers from pilfering your data via JSON requests
-+ Django 1.6+
+Documentation
+------------------
+http://django-ajax-selects.readthedocs.org/en/latest/
-Quick Installation
-==================
-Get it
- `pip install django-ajax-selects`
-or
- download or checkout the distribution
-
-
-In settings.py :
-
- # add the app
- INSTALLED_APPS = (
- ...,
- 'django.contrib.staticfiles',
- 'ajax_select'
- )
-
- # define the lookup channels in use on the site
- AJAX_LOOKUP_CHANNELS = {
- # simple: search Person.objects.filter(name__icontains=q)
- 'person' : {'model': 'example.person', 'search_field': 'name'},
- # define a custom lookup channel
- 'song' : ('example.lookups', 'SongLookup')
- }
-
-
-In your urls.py:
-
- from django.conf.urls import patterns, include
-
- from django.contrib import admin
- from ajax_select import urls as ajax_select_urls
-
- admin.autodiscover()
-
- urlpatterns = patterns('',
- # include the lookup urls
- (r'^admin/lookups/', include(ajax_select_urls)),
- (r'^admin/', include(admin.site.urls)),
- )
-
-
-In your admin.py:
-
- from django.contrib import admin
- from ajax_select import make_ajax_form
- from ajax_select.admin import AjaxSelectAdmin
- from example.models import Person, Label
-
- class PersonAdmin(admin.ModelAdmin):
- pass
- admin.site.register(Person, PersonAdmin)
-
- class LabelAdmin(AjaxSelectAdmin):
- # create an ajax form class using the factory function
- # model,fieldlist, [form superclass]
- form = make_ajax_form(Label, {'owner': 'person'})
- admin.site.register(Label, LabelAdmin)
-
-example/lookups.py:
-
- from ajax_select import LookupChannel
-
- class SongLookup(LookupChannel):
-
- model = Song
-
- def get_query(self, q, request):
- return Song.objects.filter(title__icontains=q).order_by('title')
-
-
-NOT SO QUICK INSTALLATION
-=========================
-
-Things that can be customized:
-
-+ define custom `LookupChannel` classes to customize:
- + HTML formatting for the drop down results and the item-selected display
- + custom search queries, ordering, user specific filtered results
- + custom channel security (default is staff only)
-+ each channel can define its own template to add controls or javascript
-+ JS can respond to jQuery triggers when items are selected or removed
-+ custom CSS
-+ how and from where jQuery, jQueryUI, jQueryUI theme are loaded
-
-
-Architecture
-============
-
-A single view services all of the ajax search requests, delegating the searches to named 'channels'.
-
-A simple channel can be specified in settings.py, a more complex one (with custom search, formatting, personalization or auth requirements) can be written in a lookups.py file.
-
-Each model that needs to be searched for has a channel defined for it. More than one channel may be defined for a Model to serve different needs such as public vs admin or channels that filter the query by specific categories etc. The channel also has access to the request and the user so it can personalize the query results. Those channels can be reused by any Admin that wishes to lookup that model for a ManyToMany or ForeignKey field.
-
-
-
-There are three model field types with corresponding form fields and widgets:
-
-| Database field | Form field | Form widget | -
|---|---|---|
| models.CharField | AutoCompleteField | AutoCompleteWidget |
| models.ForeignKey | AutoCompleteSelectField | AutoCompleteSelectWidget |
| models.ManyToManyField | AutoCompleteSelectMultipleField | AutoCompleteSelectMultipleWidget |
%s
" % (escape(obj.name), escape(obj.email))
-
- Note that raw strings should always be escaped with the escape() function
-
-#### Methods you can override in your `LookupChannel`
-
-
-###### model [property]
-
-The model class this channel searches
-
-###### plugin_options [property, default={}]
-
-Set any options for the jQuery plugin. This includes:
-
-+ minLength
-+ autoFocus
-+ disabled
-+ position
-+ source - setting this would overide the normal ajax URL. could be used to add URL query params
-
-See http://docs.jquery.com/UI/Autocomplete#options
-
-The field or widget may also specify plugin_options that will overwrite those specified by the channel.
-
-###### min_length [property, default=1]
-
-This is a jQuery plugin option. It is preferred to set this in the plugin_options dict, but this older style attribute will still be honored.
-
-Minimum query length to return a result. Large datasets can choke if they search too often with small queries.
-Better to demand at least 2 or 3 characters.
-This param is also used in jQuery's UI when filtering results from its own cache.
-
-###### search_field [property, optional]
-
-Name of the field for the query to search with icontains. This is used only in the default get_query implementation.
-Usually better to just implement your own get_query
-
-###### get_query(self,q,request)
-
-return a query set searching for the query string q, ordering as appropriate.
-Either implement this method yourself or set the search_field property.
-Note that you may return any iterable so you can even use yield and turn this method into a generator,
-or return an generator or list comprehension.
-
-###### get_result(self,obj):
-
-The text result of autocompleting the entered query. This is currently displayed only for a moment in the text field
-after the user has selected the item. Then the item is displayed in the item_display deck and the text field is cleared.
-Future versions may offer different handlers for how to display the selected item(s). In the current version you may
-add extra script and use triggers to customize.
-
-###### format_match(self,obj):
-
-(HTML) formatted item for displaying item in the result dropdown
-
-###### format_item_display(self,obj):
-
-(HTML) formatted item for displaying item in the selected deck area (directly below the text field).
-Note that we use jQuery .position() to correctly place the deck area below the text field regardless of
-whether the widget is in the admin, and admin inline or an outside form. ie. it does not depend on django's
-admin css to correctly place the selected display area.
-
-###### get_objects(self,ids):
-
-Get the currently selected objects when editing an existing model
-
-Note that the order of the ids supplied for ManyToMany fields is dependent on how the objects manager fetches it.
-ie. what is returned by yourmodel.fieldname_set.all()
-
-In most situations (especially postgres) this order is random, not the order that you originally added them in the interface. With a bit of hacking I have convinced it to preserve the order [see OrderedManyToMany.md for solution]
-
-###### can_add(self, user, argmodel):
-
-Check if the user has permission to add one of these models.
-This enables the green popup +
-Default is the standard django permission check
-
-###### check_auth(self,request):
-
-To ensure that nobody can get your data via json simply by knowing the URL.
-The default is to limit it to request.user.is_staff and raise a PermissionDenied exception.
-By default this is an error with a 401 response, but your middleware may intercept and choose to do other things.
-
-Public facing forms should write a custom `LookupChannel` to implement as needed.
-Also you could choose to return HttpResponseForbidden("who are you?") instead of raising PermissionDenied
-
-
-admin.py
---------
-
-#### make_ajax_form(model, fieldlist, superclass=ModelForm, show_help_text=False)
-
-If your application does not otherwise require a custom Form class then you can use the make_ajax_form helper to create the entire form directly in admin.py. See forms.py below for cases where you wish to make your own Form.
-
-+ *model*: your model
-+ *fieldlist*: a dict of {fieldname : channel_name, ... }
-+ *superclass*: [default ModelForm] Substitute a different superclass for the constructed Form class.
-+ *show_help_text*: [default False]
- Leave blank [False] if using this form in a standard Admin.
- Set it True for InlineAdmin classes or if making a form for use outside of the Admin.
-
-######Example
-
- from ajax_select import make_ajax_form
- from ajax_select.admin import AjaxSelectAdmin
- from yourapp.models import YourModel
-
- class YourModelAdmin(AjaxSelectAdmin):
- # create an ajax form class using the factory function
- # model, fieldlist, [form superclass]
- form = make_ajax_form(Label, {'owner': 'person'})
-
- admin.site.register(YourModel,YourModelAdmin)
-
-You may use AjaxSelectAdmin as a mixin class and multiple inherit if you have another Admin class that you would like to use. You may also just add the hook into your own Admin class:
-
- def get_form(self, request, obj=None, **kwargs):
- form = super(YourAdminClass, self).get_form(request, obj, **kwargs)
- autoselect_fields_check_can_add(form, self.model, request.user)
- return form
-
-Note that ajax_selects does not need to be in an admin. Popups will still use an admin view (the registered admin for the model being added), even if the form from where the popup was launched does not.
-
-
-forms.py
---------
-
-subclass ModelForm just as usual. You may add ajax fields using the helper or directly.
-
-#### make_ajax_field(model, model_fieldname, channel, show_help_text=False, **kwargs)
-
-A factory function to makes an ajax field + widget. The helper ensures things are set correctly and simplifies usage and imports thus reducing programmer error. All kwargs are passed into the Field so it is no less customizable.
-
-+ *model*: the model that this ModelForm is for
-+ *model_fieldname*: the field on the model that is being edited (ForeignKey, ManyToManyField or CharField)
-+ *channel*: the lookup channel to use for searches
-+ *show_help_text*: [default False] Whether to show the help text inside the widget itself.
- When using in AdminInline or outside of the admin then set it to True.
-+ *kwargs*: Additional kwargs are passed on to the form field.
- Of interest:
- help_text="Custom help text"
- or:
- # do not show any help at all
- help_text=None
-
- plugin_options - directly specify jQuery plugin options. see Lookup plugin_options above
-
-
-#####Example
-
- from ajax_select import make_ajax_field
-
- class ReleaseForm(ModelForm):
-
- class Meta:
- model = Release
- exclude = []
-
- group = make_ajax_field(Release, 'group', 'group', help_text=None)
-
-#### Without using the helper
-
-
- from ajax_select.fields import AutoCompleteSelectField
-
- class ReleaseForm(ModelForm):
-
- group = AutoCompleteSelectField('group', required=False, help_text=None)
-
-#### Setting plugin options
-
- from ajax_select.fields import AutoCompleteSelectField
-
- class ReleaseForm(ModelForm):
-
- group = AutoCompleteSelectField('group', required=False, help_text=None, plugin_options = {'autoFocus': True, 'minLength': 4})
-
-#### Using ajax selects in a `FormSet`
-
-There is possibly a better way to do this, but here is an initial example:
-
-`forms.py`
-
- from django.forms.models import modelformset_factory
- from django.forms.models import BaseModelFormSet
- from ajax_select.fields import AutoCompleteSelectMultipleField, AutoCompleteSelectField
-
- from models import Task
-
- # create a superclass
- class BaseTaskFormSet(BaseModelFormSet):
-
- # that adds the field in, overwriting the previous default field
- def add_fields(self, form, index):
- super(BaseTaskFormSet, self).add_fields(form, index)
- form.fields["project"] = AutoCompleteSelectField('project', required=False)
-
- # pass in the base formset class to the factory
- TaskFormSet = modelformset_factory(Task, fields=('name', 'project', 'area'), extra=0, formset=BaseTaskFormSet)
-
-
-
-templates/
-----------
-
-Each form field widget is rendered using a template. You may write a custom template per channel and extend the base template in order to implement these blocks:
-
- {% block extra_script %}{% endblock %}
- {% block help %}{% endblock %}
-
-| form Field | tries this first | default template |
|---|---|---|
| AutoCompleteField | templates/autocomplete_{{CHANNELNAME}}.html | templates/autocomplete.html |
| AutoCompleteSelectField | templates/autocompleteselect_{{CHANNELNAME}}.html | templates/autocompleteselect.html |
| AutoCompleteSelectMultipleField | templates/autocompleteselectmultiple_{{CHANNELNAME}}.html | templates/autocompleteselectmultiple.html |
' + killButton + repr + '
');
} else {
- $('#' + id+'_on_deck > div').prepend(killButton);
+ $('#' + id + '_on_deck > div').prepend(killButton);
}
- $('#' + killer_id).click(function () {
+ $('#' + killId).click(function() {
kill();
$deck.trigger('killed', [pk]);
});
@@ -45,28 +45,36 @@
options.select = receiveResult;
$text.autocomplete(options);
- if (options.initial) {
- addKiller(options.initial[0], options.initial[1]);
+ function reset() {
+ if (options.initial) {
+ addKiller(options.initial[0], options.initial[1]);
+ $this.val(options.initial[1]);
+ } else {
+ kill();
+ }
}
- $this.bind('didAddPopup', function (event, pk, repr) {
+ reset();
+ $this.closest('form').on('reset', reset);
+
+ $this.bind('didAddPopup', function(event, pk, repr) {
receiveResult(null, {item: {pk: pk, repr: repr}});
});
});
};
- $.fn.autocompleteselectmultiple = function (options) {
- return this.each(function () {
+ $.fn.autocompleteselectmultiple = function(options) {
+ return this.each(function() {
var id = this.id,
$this = $(this),
- $text = $('#' + id+'_text'),
- $deck = $('#' + id+'_on_deck');
+ $text = $('#' + id + '_text'),
+ $deck = $('#' + id + '_on_deck');
function receiveResult(event, ui) {
var pk = ui.item.pk,
prev = $this.val();
- if (prev.indexOf('|'+pk+'|') === -1) {
+ if (prev.indexOf('|' + pk + '|') === -1) {
$this.val((prev ? prev : '|') + pk + '|');
addKiller(ui.item.repr, pk);
$text.val('');
@@ -77,11 +85,11 @@
}
function addKiller(repr, pk) {
- var killer_id = 'kill_' + pk + id,
- killButton = ' ';
+ var killId = 'kill_' + pk + id,
+ killButton = ' ';
$deck.append('' + killButton + repr + '
');
- $('#' + killer_id).click(function () {
+ $('#' + killId).click(function() {
kill(pk);
$deck.trigger('killed', [pk]);
});
@@ -89,20 +97,29 @@
function kill(pk) {
$this.val($this.val().replace('|' + pk + '|', '|'));
- $('#' + id+'_on_deck_'+pk).fadeOut().remove();
+ $('#' + id + '_on_deck_' + pk).fadeOut().remove();
}
options.select = receiveResult;
$text.autocomplete(options);
- if (options.initial) {
- $.each(options.initial, function (i, its) {
- addKiller(its[0], its[1]);
- });
+ function reset() {
+ $deck.empty();
+ var query = '|';
+ if (options.initial) {
+ $.each(options.initial, function(i, its) {
+ addKiller(its[0], its[1]);
+ query += its[1] + '|';
+ });
+ }
+ $this.val(query);
}
- $this.bind('didAddPopup', function (event, pk, repr) {
- receiveResult(null, {item: {pk: pk, repr: repr }});
+ reset();
+ $this.closest('form').on('reset', reset);
+
+ $this.bind('didAddPopup', function(event, pk, repr) {
+ receiveResult(null, {item: {pk: pk, repr: repr}});
});
});
};
@@ -172,12 +189,12 @@
};
// activate any on page
- $(window).bind('init-autocomplete', function () {
+ $(window).bind('init-autocomplete', function() {
- $('input[data-ajax-select=autocomplete]').each(function (i, inp) {
- addAutoComplete(inp, function ($inp, opts) {
+ $('input[data-ajax-select=autocomplete]').each(function(i, inp) {
+ addAutoComplete(inp, function($inp, opts) {
opts.select =
- function (event, ui) {
+ function(event, ui) {
$inp.val(ui.item.value).trigger('added', [ui.item.pk, ui.item]);
return false;
};
@@ -185,27 +202,28 @@
});
});
- $('input[data-ajax-select=autocompleteselect]').each(function (i, inp) {
- addAutoComplete(inp, function ($inp, opts) {
+ $('input[data-ajax-select=autocompleteselect]').each(function(i, inp) {
+ addAutoComplete(inp, function($inp, opts) {
$inp.autocompleteselect(opts);
});
});
- $('input[data-ajax-select=autocompleteselectmultiple]').each(function (i, inp) {
- addAutoComplete(inp, function ($inp, opts) {
+ $('input[data-ajax-select=autocompleteselectmultiple]').each(function(i, inp) {
+ addAutoComplete(inp, function($inp, opts) {
$inp.autocompleteselectmultiple(opts);
});
});
});
- $(document).ready(function () {
+ $(document).ready(function() {
// if dynamically injecting forms onto a page
// you can trigger them to be ajax-selects-ified:
$(window).trigger('init-autocomplete');
- $('.inline-group ul.tools a.add, .inline-group div.add-row a, .inline-group .tabular tr.add-row td a').on('click', function() {
- $(window).trigger('init-autocomplete');
- });
+ $('.inline-group ul.tools a.add, .inline-group div.add-row a, .inline-group .tabular tr.add-row td a')
+ .on('click', function() {
+ $(window).trigger('init-autocomplete');
+ });
});
})(window.jQuery);
diff --git a/ajax_select/templates/autocomplete.html b/ajax_select/templates/ajax_select/autocomplete.html
similarity index 100%
rename from ajax_select/templates/autocomplete.html
rename to ajax_select/templates/ajax_select/autocomplete.html
diff --git a/ajax_select/templates/autocompleteselect.html b/ajax_select/templates/ajax_select/autocompleteselect.html
similarity index 100%
rename from ajax_select/templates/autocompleteselect.html
rename to ajax_select/templates/ajax_select/autocompleteselect.html
diff --git a/ajax_select/templates/autocompleteselectmultiple.html b/ajax_select/templates/ajax_select/autocompleteselectmultiple.html
similarity index 100%
rename from ajax_select/templates/autocompleteselectmultiple.html
rename to ajax_select/templates/ajax_select/autocompleteselectmultiple.html
diff --git a/ajax_select/urls.py b/ajax_select/urls.py
index 445a1354f2..048ca46ab7 100644
--- a/ajax_select/urls.py
+++ b/ajax_select/urls.py
@@ -1,16 +1,11 @@
-try:
- from django.conf.urls import patterns, url
-except:
- from django.conf.urls.defaults import patterns, url
+from django.conf.urls import url
+from ajax_select import views
-
-urlpatterns = patterns('',
+urlpatterns = [
url(r'^ajax_lookup/(?P+ You could put additional UI or help text here. +
+ {% endblock %} diff --git a/docs/source/Example-app.rst b/docs/source/Example-app.rst new file mode 100644 index 0000000000..f734d4f918 --- /dev/null +++ b/docs/source/Example-app.rst @@ -0,0 +1,11 @@ + +Example App +=========== + +Clone this repository and see the example app for a full working admin site with many variations and comments. It installs quickly using virtualenv and sqllite and comes fully configured. + +install:: + + cd example + ./install.sh 1.8.5 + ./manage.py runserver diff --git a/docs/source/Forms.rst b/docs/source/Forms.rst new file mode 100644 index 0000000000..d474056a31 --- /dev/null +++ b/docs/source/Forms.rst @@ -0,0 +1,65 @@ +Forms +===== + +Forms can be used either for an Admin or in normal Django views. + +Subclass ModelForm as usual and define fields:: + + from ajax_select.fields import AutoCompleteSelectField, AutoCompleteSelectMultipleField + + class DocumentForm(ModelForm): + + class Meta: + model = Document + + category = AutoCompleteSelectField('categories', required=False, help_text=None) + tags = AutoCompleteSelectMultipleField('tags', required=False, help_text=None) + + +make_ajax_field +--------------- + +There is also a helper method available here. + +.. automodule:: ajax_select.helpers + :members: make_ajax_field + :noindex: + + +Example:: + + from ajax_select import make_ajax_field + + class DocumentForm(ModelForm): + + class Meta: + model = Document + + category = make_ajax_field(Category, 'categories', 'category', help_text=None) + tags = make_ajax_field(Tag, 'tags', 'tags', help_text=None) + + + +FormSet +------- + +There is possibly a better way to do this, but here is an initial example: + +`forms.py`:: + + from django.forms.models import modelformset_factory + from django.forms.models import BaseModelFormSet + from ajax_select.fields import AutoCompleteSelectMultipleField, AutoCompleteSelectField + + from models import Task + + # create a superclass + class BaseTaskFormSet(BaseModelFormSet): + + # that adds the field in, overwriting the previous default field + def add_fields(self, form, index): + super(BaseTaskFormSet, self).add_fields(form, index) + form.fields["project"] = AutoCompleteSelectField('project', required=False) + + # pass in the base formset class to the factory + TaskFormSet = modelformset_factory(Task, fields=('name', 'project', 'area'), extra=0, formset=BaseTaskFormSet) diff --git a/docs/source/Install.rst b/docs/source/Install.rst new file mode 100644 index 0000000000..d18d9dd627 --- /dev/null +++ b/docs/source/Install.rst @@ -0,0 +1,90 @@ +Install +======= + +Install:: + + pip install django-ajax-selects + +Add the app:: + + # settings.py + INSTALLED_APPS = ( + ... + 'ajax_select', # <- add the app + ... + ) + +Include the urls in your project:: + + # urls.py + from django.conf.urls import url, include + from django.conf.urls.static import static + from django.contrib import admin + from django.conf import settings + from ajax_select import urls as ajax_select_urls + + admin.autodiscover() + + urlpatterns = [ + + # place it at whatever base url you like + url(r'^ajax_select/', include(ajax_select_urls)), + + url(r'^admin/', include(admin.site.urls)), + ] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT) + + +Write a LookupChannel to specify the models, search queries, formatting etc. and register it with a channel name:: + + from ajax_select import register, LookupChannel + from .models import Tag + + @register('tags') + class TagsLookup(LookupChannel): + + model = Tag + + def get_query(self, q, request): + return self.model.objects.filter(name=q) + + def format_item_display(self, item): + return u"%s" % item.name + +If you are using Django >= 1.7 then it will automatically loaded on startup. +For previous Djangos you can import them manually to your urls or views. + +Add ajax lookup fields in your admin.py:: + + from django.contrib import admin + from ajax_select import make_ajax_form + from .models import Document + + @admin.register(Document) + class DocumentAdmin(AjaxSelectAdmin): + + form = make_ajax_form(Document, { + # fieldname: channel_name + 'tags': 'tags' + }) + +Or add the fields to a ModelForm:: + + # forms.py + from ajax_select.fields import AutoCompleteSelectField, AutoCompleteSelectMultipleField + + class DocumentForm(ModelForm): + + class Meta: + model = Document + + category = AutoCompleteSelectField('categories', required=False, help_text=None) + tags = AutoCompleteSelectMultipleField('tags', required=False, help_text=None) + + # admin.py + from django.contrib import admin + from .forms import DocumentForm + from .models import Document + + @admin.register(Document) + class DocumentAdmin(AjaxSelectAdmin): + form = DocumentForm diff --git a/docs/source/LookupChannel.rst b/docs/source/LookupChannel.rst new file mode 100644 index 0000000000..97c3f12053 --- /dev/null +++ b/docs/source/LookupChannel.rst @@ -0,0 +1,77 @@ +Lookup Channels +=============== + +A LookupChannel defines how to search and how to format found objects for display in the interface. + +LookupChannels are registered with a "channel name" and fields refer to that name. + +You may have only one LookupChannel for a model, or you might define several for the same Model each with different queries, security policies and formatting styles. + +Custom templates can be created for channels. This enables adding extra javascript or custom UI. See :doc:`/Custom-Templates` + + +lookups.py +---------- + +Write your LookupChannel classes in a file name `yourapp/lookups.py` + +(note: inside your app, not your top level project) + +Use the @register decorator to register your LookupChannels by name + +`example/lookups.py`:: + + from ajax_select import register, LookupChannel + + @register('things') + class ThingsLookup(LookupChannel): + + model = Things + + def get_query(self, q, request): + return self.model.objects.filter(title__icontains=q).order_by('title') + + +If you are using Django >= 1.7 then all `lookups.py` in all of your apps will be automatically imported on startup. + +If Django < 1.7 then you can import each of your lookups in your views or urls. +Or you can register them in settings (see below). + +Customize +--------- + +.. automodule:: ajax_select.lookup_channel + :members: LookupChannel + :noindex: + + +settings.py +----------- + +Versions previous to 1.4 loaded the LookupChannels according to `settings.AJAX_LOOKUP_CHANNELS` + +This will still work. Your LookupChannels will continue to load without having to add them with the new @register decorator. + +Example:: + + # settings.py + + AJAX_LOOKUP_CHANNELS = { + # auto-create a channel named 'person' that searches by name on the model Person + # str: dict + 'person': {'model': 'example.person', 'search_field': 'name'} + + # specify a lookup to be loaded + # str: tuple + 'song': ('example.lookups', 'SongLookup'), + + # delete a lookup channel registered by an app/lookups.py + # str: None + 'users': None + } + + +One situation where it is still useful: if a resuable app defines a LookupChannel and you want to override that or turn it off. +Pass None as in the third example above. + +Anything in `settings.AJAX_LOOKUP_CHANNELS` overwrites anything previously registered by an app. diff --git a/docs/source/Media-assets.rst b/docs/source/Media-assets.rst new file mode 100644 index 0000000000..fdb2b64266 --- /dev/null +++ b/docs/source/Media-assets.rst @@ -0,0 +1,39 @@ +Media Assets +============ + +If `jQuery` or `jQuery.ui` are not already loaded on the page, then these will be loaded from CDN:: + + ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js + code.jquery.com/ui/1.10.3/jquery-ui.js + code.jquery.com/ui/1.10.3/themes/smoothness/jquery-ui.css + +If you want to prevent this and load your own then set:: + + # settings.py + AJAX_SELECT_BOOTSTRAP = False + + +Customizing the style sheet +--------------------------- + +By default `css/ajax_select.css` is included by the Widget's media. This specifies a simple basic style. + +If you would prefer not to have `css/ajax_select.css` loaded at all then you can implement your own `yourapp/static/ajax_select/css/ajax_select.css` and put your app before `ajax_select` in `INSTALLED_APPS`. + +Your version will take precedence and Django will serve your `css/ajax_select.css` + +The markup is simple and you can just add more css to override unwanted styles. + +The trashcan icon comes from the jQueryUI theme by the css classes:: + + "ui-icon ui-icon-trash" + +The following css declaration:: + + .results_on_deck .ui-icon.ui-icon-trash { } + +would be "stronger" than jQuery's style declaration and thus you could make trash look less trashy. + +The loading indicator is in `ajax_select/static/ajax_select/images/loading-indicator.gif` + +`yourapp/static/ajax_select/images/loading-indicator.gif` would override that. diff --git a/docs/source/Ordered-ManyToMany.rst b/docs/source/Ordered-ManyToMany.rst new file mode 100644 index 0000000000..e43677b4fa --- /dev/null +++ b/docs/source/Ordered-ManyToMany.rst @@ -0,0 +1,61 @@ + +Ordered ManyToMany fields +========================= + +When re-editing a previously saved model that has a ManyToMany field, the order of the recalled ids can be somewhat random. + +The user sees Arnold, Bosco, Cooly in the interface; saves; comes back later to edit it and he sees Bosco, Cooly, Arnold. So he files a bug report. + + +Problem +------- + +Given these models:: + + class Agent(models.Model): + name = models.CharField(blank=True, max_length=100) + + class Apartment(models.Model): + agents = models.ManyToManyField(Agent) + +When the AutoCompleteSelectMultipleField saves it does so by saving each relationship in the order they were added in the interface. + +But when Django ORM retrieves them, the order is not guaranteed:: + + # This query does not have a guaranteed order (especially on postgres) + # and certainly not the order that we added them. + apartment.agents.all() + + # This retrieves the joined objects in the order of the join table pk + # and thus gets them in the order they were added. + apartment.agents.through.objects.filter(apt=self).select_related('agent').order_by('id') + + +Solution +-------- + +A proper solution would be to use a separate Through model, an order field and the ability to drag the items in the interface to rearrange. But a proper Through model would also introduce extra fields and that would be out of the scope of ajax_selects. + +However this method will also work. + +Make a custom ManyToManyField:: + + from django.db import models + + class AgentOrderedManyToManyField(models.ManyToManyField): + + """This fetches from the join table, then fetches the Agents in the fixed id order.""" + + def value_from_object(self, object): + rel = getattr(object, self.attname) + qry = {self.related.var_name: object} + qs = rel.through.objects.filter(**qry).order_by('id') + aids = qs.values_list('agent_id', flat=True) + agents = dict((a.pk, a) for a in Agent.objects.filter(pk__in=aids)) + return [agents[aid] for aid in aids if aid in agents] + + class Agent(models.Model): + name = models.CharField(blank=True, max_length=100) + + class Apartment(models.Model): + agents = AgentOrderedManyToManyField() diff --git a/docs/source/Outside-of-Admin.rst b/docs/source/Outside-of-Admin.rst new file mode 100644 index 0000000000..04b78c3a97 --- /dev/null +++ b/docs/source/Outside-of-Admin.rst @@ -0,0 +1,12 @@ +Outside of the Admin +==================== + +ajax_selects does not need to be in a Django admin. + +Popups will still use an admin view (the registered admin for the model being added), even if the form from where the popup was launched does not. + +In your view, after creating your ModelForm object:: + + autoselect_fields_check_can_add(form, model, request.user) + +This will check each widget and enable the green + for them iff the User has permission. diff --git a/docs/source/Upgrading.rst b/docs/source/Upgrading.rst new file mode 100644 index 0000000000..59ee6ed810 --- /dev/null +++ b/docs/source/Upgrading.rst @@ -0,0 +1,41 @@ +Upgrading from previous versions +================================ + +1.4 + +Custom Templates +---------------- + +Move your custom templates from:: + + yourapp/templates/channel_autocomplete.html + yourapp/templates/channel_autocompleteselect.html + yourapp/templates/channel_autocompleteselectmultiple.html + +to:: + + yourapp/templates/ajax_select/channel_autocomplete.html + yourapp/templates/ajax_select/channel_autocompleteselect.html + yourapp/templates/ajax_select/channel_autocompleteselectmultiple.html + +And change your extends from:: + + {% extends "autocompleteselect.html" %} + +to:: + + {% extends "ajax_select/autocompleteselect.html" %} + + +Removed options +--------------- + +make_ajax_field: + show_m2m_help -> show_help_text + +settings +-------- + +LookupChannels are still loaded from `settings.AJAX_LOOKUP_CHANNELS` as previously. + +If you are on Django >= 1.7 you may switch to using the @register decorator and you can remove that setting. diff --git a/docs/source/_static/add-song.png b/docs/source/_static/add-song.png new file mode 100644 index 0000000000..f533dfe969 Binary files /dev/null and b/docs/source/_static/add-song.png differ diff --git a/docs/source/_static/add.png b/docs/source/_static/add.png new file mode 100644 index 0000000000..d80c259c76 Binary files /dev/null and b/docs/source/_static/add.png differ diff --git a/docs/source/_static/kiss-all.png b/docs/source/_static/kiss-all.png new file mode 100644 index 0000000000..b9522c8cc4 Binary files /dev/null and b/docs/source/_static/kiss-all.png differ diff --git a/docs/source/_static/kiss.png b/docs/source/_static/kiss.png new file mode 100644 index 0000000000..cddc02f2f8 Binary files /dev/null and b/docs/source/_static/kiss.png differ diff --git a/docs/source/ajax_select.rst b/docs/source/ajax_select.rst new file mode 100644 index 0000000000..5ee8a103ad --- /dev/null +++ b/docs/source/ajax_select.rst @@ -0,0 +1,86 @@ +ajax_select package +=================== + +Submodules +---------- + +ajax_select.admin module +------------------------ + +.. automodule:: ajax_select.admin + :members: + :undoc-members: + :show-inheritance: + +ajax_select.apps module +----------------------- + +.. automodule:: ajax_select.apps + :members: + :undoc-members: + :show-inheritance: + +ajax_select.fields module +------------------------- + +.. automodule:: ajax_select.fields + :members: + :undoc-members: + :show-inheritance: + +ajax_select.helpers module +-------------------------- + +.. automodule:: ajax_select.helpers + :members: + :undoc-members: + :show-inheritance: + +ajax_select.lookup_channel module +--------------------------------- + +.. automodule:: ajax_select.lookup_channel + :members: + :undoc-members: + :show-inheritance: + +ajax_select.models module +------------------------- + +.. automodule:: ajax_select.models + :members: + :undoc-members: + :show-inheritance: + +ajax_select.registry module +--------------------------- + +.. automodule:: ajax_select.registry + :members: + :undoc-members: + :show-inheritance: + +ajax_select.urls module +----------------------- + +.. automodule:: ajax_select.urls + :members: + :undoc-members: + :show-inheritance: + +ajax_select.views module +------------------------ + +.. automodule:: ajax_select.views + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: ajax_select + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000000..75b55a1934 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,271 @@ +# -*- coding: utf-8 -*- +# +# django-ajax-selects documentation build configuration file, created by +# sphinx-quickstart on Tue Nov 3 15:23:14 2015. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('../../')) +os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'example.example.settings') + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.coverage', + 'sphinx.ext.napoleon' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'django-ajax-selects' +copyright = u'2015, Chris Sattinger' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.4.0' +# The full version, including alpha/beta/rc tags. +release = '1.4.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# today = '' +# Else, today_fmt is used as the format for a strftime call. +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. + +try: + import sphinx_rtd_theme +except ImportError: + html_theme = 'default' +else: + html_theme = "sphinx_rtd_theme" + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +# html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "%s
" % (escape(obj.name), escape(obj.email))
+ return "%s%s
" % (escape(obj.name), escape(obj.email))
# return self.format_item_display(obj)
def format_item_display(self, obj):
""" (HTML) formatted item for displaying item in the selected deck area """
- return u"%s%s
" % (escape(obj.name), escape(obj.email))
+ return "%s%s
" % (escape(obj.name), escape(obj.email))
class GroupLookup(LookupChannel):
@@ -34,13 +36,13 @@ def get_query(self, q, request):
return Group.objects.filter(name__icontains=q).order_by('name')
def get_result(self, obj):
- return unicode(obj)
+ return text_type(obj)
def format_match(self, obj):
return self.format_item_display(obj)
def format_item_display(self, obj):
- return u"%s%s
" % (escape(obj.name), escape(obj.url))
+ return "%s%s
" % (escape(obj.name), escape(obj.url))
def can_add(self, user, model):
""" customize can_add by allowing anybody to add a Group.
@@ -58,7 +60,7 @@ def get_query(self, q, request):
return Song.objects.filter(title__icontains=q).select_related('group').order_by('title')
def get_result(self, obj):
- return unicode(obj.title)
+ return text_type(obj.title)
def format_match(self, obj):
return self.format_item_display(obj)
@@ -67,6 +69,8 @@ def format_item_display(self, obj):
return "%sby %s
" % (escape(obj.title), escape(obj.group.name))
+# Here using decorator syntax rather than settings.AJAX_LOOKUP_CHANNELS
+@ajax_select.register('cliche')
class ClicheLookup(LookupChannel):
""" an autocomplete lookup does not need to search models
@@ -75,13 +79,13 @@ class ClicheLookup(LookupChannel):
"""
words = [
- u"rain cats and dogs",
- u"quick as a cat",
- u"there's more than one way to skin a cat",
- u"let the cat out of the bag",
- u"fat cat",
- u"the early bird catches the worm",
- u"catch as catch can as catch as catch can as catch as catch can as catch as catch "
+ "rain cats and dogs",
+ "quick as a cat",
+ "there's more than one way to skin a cat",
+ "let the cat out of the bag",
+ "fat cat",
+ "the early bird catches the worm",
+ "catch as catch can as catch as catch can as catch as catch can as catch as catch "
"can as catch as catch can as catch as catch can as catch as catch can as catch as "
"catch can as catch as catch can as catch as catch can as catch as catch can as catch "
"as catch can as catch as catch can as catch as catch can as catch as catch can as "
@@ -94,52 +98,52 @@ class ClicheLookup(LookupChannel):
"can as catch as catch can as catch as catch can as catch as catch can as catch "
"as catch can as catch as catch can as catch as catch can as catch as catch can "
"as catch as catch can as catch as catch can as can",
- u"you can catch more flies with honey than with vinegar",
- u"catbird seat",
- u"cat's paw",
- u"cat's meow",
- u"has the cat got your tongue?",
- u"busy as a cat on a hot tin roof",
- u"who'll bell the cat",
- u"cat's ass",
- u"more nervous than a long tailed cat in a room full of rocking chairs",
- u"all cats are grey in the dark",
- u"nervous as a cat in a room full of rocking chairs",
- u"can't a cat look at a queen?",
- u"curiosity killed the cat",
- u"cat's pajamas",
- u"look what the cat dragged in",
- u"while the cat's away the mice will play",
- u"Nervous as a cat in a room full of rocking chairs",
- u"Slicker than cat shit on a linoleum floor",
- u"there's more than one way to kill a cat than choking it with butter.",
- u"you can't swing a dead cat without hitting one",
- u"The cat's whisker",
- u"looking like the cat who swallowed the canary",
- u"not enough room to swing a cat",
- u"It's raining cats and dogs",
- u"He was on that like a pack of dogs on a three-legged cat.",
- u"like two tomcats in a gunny sack",
- u"I don't know your from adam's house cat!",
- u"nervous as a long tailed cat in a living room full of rockers",
- u"Busier than a three legged cat in a dry sand box.",
- u"Busier than a one-eyed cat watching two mouse holes.",
- u"kick the dog and cat",
- u"there's more than one way to kill a cat than to drown it in cream",
- u"how many ways can you skin a cat?",
- u"Looks like a black cat with a red bird in its mouth",
- u"Morals of an alley cat and scruples of a snake.",
- u"hotter than a six peckered alley cat",
- u"when the cats are away the mice will play",
- u"you can catch more flies with honey than vinegar",
- u"when the cat's away, the mice will play",
- u"Who opened the cattleguard?",
- u"your past might catch up with you",
- u"ain't that just the cats pyjamas",
- u"A Cat has nine lives",
- u"a cheshire-cat smile",
- u"cat's pajamas",
- u"cat got your tongue?"]
+ "you can catch more flies with honey than with vinegar",
+ "catbird seat",
+ "cat's paw",
+ "cat's meow",
+ "has the cat got your tongue?",
+ "busy as a cat on a hot tin roof",
+ "who'll bell the cat",
+ "cat's ass",
+ "more nervous than a long tailed cat in a room full of rocking chairs",
+ "all cats are grey in the dark",
+ "nervous as a cat in a room full of rocking chairs",
+ "can't a cat look at a queen?",
+ "curiosity killed the cat",
+ "cat's pajamas",
+ "look what the cat dragged in",
+ "while the cat's away the mice will play",
+ "Nervous as a cat in a room full of rocking chairs",
+ "Slicker than cat shit on a linoleum floor",
+ "there's more than one way to kill a cat than choking it with butter.",
+ "you can't swing a dead cat without hitting one",
+ "The cat's whisker",
+ "looking like the cat who swallowed the canary",
+ "not enough room to swing a cat",
+ "It's raining cats and dogs",
+ "He was on that like a pack of dogs on a three-legged cat.",
+ "like two tomcats in a gunny sack",
+ "I don't know your from adam's house cat!",
+ "nervous as a long tailed cat in a living room full of rockers",
+ "Busier than a three legged cat in a dry sand box.",
+ "Busier than a one-eyed cat watching two mouse holes.",
+ "kick the dog and cat",
+ "there's more than one way to kill a cat than to drown it in cream",
+ "how many ways can you skin a cat?",
+ "Looks like a black cat with a red bird in its mouth",
+ "Morals of an alley cat and scruples of a snake.",
+ "hotter than a six peckered alley cat",
+ "when the cats are away the mice will play",
+ "you can catch more flies with honey than vinegar",
+ "when the cat's away, the mice will play",
+ "Who opened the cattleguard?",
+ "your past might catch up with yo",
+ "ain't that just the cats pyjamas",
+ "A Cat has nine lives",
+ "a cheshire-cat smile",
+ "cat's pajamas",
+ "cat got your tongue?"]
def get_query(self, q, request):
return sorted([w for w in self.words if q in w])
diff --git a/example/example/models.py b/example/example/models.py
index 6a523c74ac..7bac73bc2c 100644
--- a/example/example/models.py
+++ b/example/example/models.py
@@ -1,5 +1,6 @@
# -*- coding: utf8 -*-
+from __future__ import unicode_literals
from django.db import models
@@ -57,7 +58,7 @@ class Release(models.Model):
title = models.CharField(max_length=100)
catalog = models.CharField(blank=True, max_length=100)
- group = models.ForeignKey(Group, blank=True, null=True, verbose_name=u"Русский текст (group)")
+ group = models.ForeignKey(Group, blank=True, null=True, verbose_name="Русский текст (group)")
label = models.ForeignKey(Label, blank=False, null=False)
songs = models.ManyToManyField(Song, blank=True)
diff --git a/example/example/settings.py b/example/example/settings.py
index 3a51a14caf..13ec5d1c10 100644
--- a/example/example/settings.py
+++ b/example/example/settings.py
@@ -35,7 +35,6 @@
'person': ('example.lookups', 'PersonLookup'),
'group': ('example.lookups', 'GroupLookup'),
'song': ('example.lookups', 'SongLookup'),
- 'cliche': ('example.lookups', 'ClicheLookup')
}
diff --git a/example/example/urls.py b/example/example/urls.py
index 980fbfad9d..c20d58f2b4 100644
--- a/example/example/urls.py
+++ b/example/example/urls.py
@@ -1,19 +1,17 @@
-try:
- from django.conf.urls import patterns, url, include
-except:
- from django.conf.urls.defaults import patterns, url, include
+from django.conf.urls import url, include
from django.conf.urls.static import static
from django.contrib import admin
from django.conf import settings
from ajax_select import urls as ajax_select_urls
+from example import views
admin.autodiscover()
-urlpatterns = patterns('',
+urlpatterns = [
url(r'^search_form',
- view='example.views.search_form',
+ view=views.search_form,
name='search_form'),
- (r'^admin/lookups/', include(ajax_select_urls)),
- (r'^admin/', include(admin.site.urls)),
-) + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
+ url(r'^admin/lookups/', include(ajax_select_urls)),
+ url(r'^admin/', include(admin.site.urls)),
+] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
diff --git a/example/example/views.py b/example/example/views.py
index 84a832ba9b..127eb774cb 100644
--- a/example/example/views.py
+++ b/example/example/views.py
@@ -1,5 +1,6 @@
# -*- coding: utf-8 -*-
+from __future__ import unicode_literals
from django import forms
from django.shortcuts import render_to_response
from django.template import RequestContext
@@ -8,13 +9,11 @@
class SearchForm(forms.Form):
- q = AutoCompleteField(
- 'cliche',
- required=True,
- help_text="Autocomplete will suggest clichés about cats, but you can enter anything you like.",
- label="Favorite Cliché",
- attrs={'size': 100}
- )
+ q = AutoCompleteField('cliche',
+ required=True,
+ help_text="Autocomplete will suggest clichés about cats, but you can enter anything you like.",
+ label="Favorite Cliché",
+ attrs={'size': 100})
def search_form(request):
diff --git a/requirements-test.txt b/requirements-test.txt
new file mode 100644
index 0000000000..9a61c7bb13
--- /dev/null
+++ b/requirements-test.txt
@@ -0,0 +1,5 @@
+coverage
+coveralls
+flake8>=2.1.0
+tox>=1.7.0
+sphinx_rtd_theme
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000000..7530d6e951
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,2 @@
+django>=1.5.1, <1.9
+wheel==0.24.0
diff --git a/setup.py b/setup.py
index db063c2ac7..a313429022 100644
--- a/setup.py
+++ b/setup.py
@@ -9,9 +9,9 @@
setup(
name='django-ajax-selects',
- version='1.3.6',
- description='jQuery-UI powered auto-complete fields for editing ForeignKey, ManyToManyField and CharField',
- author='crucialfelix',
+ version='1.4.0',
+ description='Edit ForeignKey, ManyToManyField and CharField in Django Admin using jQuery UI AutoComplete.',
+ author='Chris Sattinger',
author_email='crucialfelix@gmail.com',
url='https://github.com/crucialfelix/django-ajax-selects/',
packages=['ajax_select'],
@@ -28,6 +28,7 @@
},
include_package_data=True,
zip_safe=False,
+ license="MIT",
classifiers=[
"Programming Language :: Python",
"Programming Language :: Python :: 2",
@@ -42,26 +43,18 @@
"Framework :: Django",
],
long_description="""\
-Enables editing of `ForeignKey`, `ManyToManyField` and `CharField` using jQuery UI AutoComplete.
+Edit ForeignKey, ManyToManyField and CharField in Django Admin using jQuery UI AutoComplete.
-1. The user types a search term into the text field
-2. An ajax request is sent to the server.
-3. The dropdown menu is populated with results.
-4. User selects by clicking or using arrow keys
-5. Selected result displays in the "deck" area directly below the input field.
-6. User can click trashcan icon to remove a selected item
-
-+ Django 1.6+
-+ Optional boostrap mode allows easy installation by automatic inclusion of jQueryUI from the googleapis CDN
-+ Compatible with staticfiles, appmedia, django-compressor etc
-+ Popup to add a new item is supported
-+ Admin inlines now supported
-+ Ajax Selects works in the admin and also in public facing forms.
-+ Rich formatting can be easily defined for the dropdown display and the selected "deck" display.
-+ Templates and CSS are fully customizable
-+ JQuery triggers enable you to add javascript to respond when items are added or removed,
- so other interface elements on the page can react
-+ Default (but customizable) security prevents griefers from pilfering your data via JSON requests
+- Customize search query
+- Query other resources besides Django ORM
+- Format results with HTML
+- Customize styling
+- Customize security policy
+- Add additional custom UI alongside widget
+- Integrate with other UI elements elsewhere on the page using the javascript API
+- Works in Admin as well as in normal views
+- Django >=1.5, <=1.9
+- Python >=2.7, <=3.4
"""
)
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/tests/admin.py b/tests/admin.py
new file mode 100644
index 0000000000..5b5b1ae0b7
--- /dev/null
+++ b/tests/admin.py
@@ -0,0 +1,9 @@
+
+from django.contrib import admin
+from tests.models import Author
+
+
+class AuthorAdmin(admin.ModelAdmin):
+ pass
+
+admin.site.register(Author, AuthorAdmin)
diff --git a/tests/lookups.py b/tests/lookups.py
new file mode 100644
index 0000000000..2b4b7418d1
--- /dev/null
+++ b/tests/lookups.py
@@ -0,0 +1,40 @@
+from django.utils.html import escape
+from django.contrib.auth.models import User
+from tests.models import Person
+import ajax_select
+
+
+@ajax_select.register('person')
+class PersonLookup(ajax_select.LookupChannel):
+
+ model = Person
+
+ def get_query(self, q, request):
+ return self.model.objects.filter(name__icontains=q)
+
+ def get_result(self, obj):
+ return obj.name
+
+ def format_match(self, obj):
+ return "%s%s
" % (escape(obj.name), escape(obj.email))
+
+ def format_item_display(self, obj):
+ return "%s%s
" % (escape(obj.name), escape(obj.email))
+
+
+@ajax_select.register('user')
+class UserLookup(ajax_select.LookupChannel):
+
+ """
+ Test if you can unset a lookup provided by a third-party application.
+ In this case it exposes User without any auth checking
+ and somebody could manually check the ajax URL and find out
+ if a user email exists.
+ So you might want to turn this channel off
+ by settings.AJAX_LOOKUP_CHANNELS['user'] = None
+ """
+
+ model = User
+
+ def get_query(self, q, request):
+ return self.model.objects.filter(email=q)
diff --git a/tests/models.py b/tests/models.py
new file mode 100644
index 0000000000..ae3b8f49f1
--- /dev/null
+++ b/tests/models.py
@@ -0,0 +1,30 @@
+
+from django.db import models
+
+
+class Person(models.Model):
+
+ name = models.CharField(max_length=50)
+
+ class Meta:
+ app_label = 'tests'
+
+
+class Author(models.Model):
+
+ name = models.CharField(max_length=50)
+
+ class Meta:
+ app_label = 'tests'
+
+
+class Book(models.Model):
+
+ """ Book has no admin, its an inline in the Author admin"""
+
+ author = models.ForeignKey(Author)
+ name = models.CharField(max_length=50)
+ mentions_persons = models.ManyToManyField(Person, help_text="MENTIONS PERSONS HELP TEXT")
+
+ class Meta:
+ app_label = 'tests'
diff --git a/tests/other_lookups.py b/tests/other_lookups.py
new file mode 100644
index 0000000000..5ccd740c50
--- /dev/null
+++ b/tests/other_lookups.py
@@ -0,0 +1,9 @@
+"""Testing if lookups that are not in a file named lookups.py can be loaded correctly."""
+
+import ajax_select
+from tests.models import Book
+
+
+class BookLookup(ajax_select.LookupChannel):
+
+ model = Book
diff --git a/tests/settings.py b/tests/settings.py
new file mode 100644
index 0000000000..96d4a4654a
--- /dev/null
+++ b/tests/settings.py
@@ -0,0 +1,61 @@
+DEBUG = True
+USE_TZ = True
+DATABASES = {
+ "default": {
+ "ENGINE": "django.db.backends.sqlite3",
+ }
+}
+ROOT_URLCONF = "tests.urls"
+INSTALLED_APPS = [
+ "django.contrib.auth",
+ "django.contrib.contenttypes",
+ "django.contrib.sites",
+ 'django.contrib.messages',
+ 'django.contrib.sessions',
+ 'django.contrib.admin',
+ 'django.contrib.staticfiles',
+ "ajax_select",
+ "tests"
+]
+SITE_ID = 1
+MIDDLEWARE_CLASSES = (
+ 'django.contrib.sessions.middleware.SessionMiddleware',
+ 'django.contrib.auth.middleware.AuthenticationMiddleware',
+ 'django.contrib.messages.middleware.MessageMiddleware'
+)
+STATIC_URL = '/static/'
+SECRET_KEY = 'inyd5fc5pymlsv@hwoc5+3_6*cm0erlxzv6i-wl0jm_kt-6rp9'
+
+AJAX_LOOKUP_CHANNELS = {
+ # tuple points to a module and class to load
+ 'book': ('tests.other_lookups', 'BookLookup'),
+ # dict specifies an automatically constructed LookupChannel
+ 'author': {'model': 'tests.Author', 'search_field': 'name'},
+ # unset a channel that a third-party app specified
+ 'user': None,
+ 'was-never-a-channel': None
+ # LookupChannels in lookups.py are auto-loaded
+}
+
+TEMPLATES = [
+ {
+ 'BACKEND': 'django.template.backends.django.DjangoTemplates',
+ 'DIRS': [
+ # insert your TEMPLATE_DIRS here
+ ],
+ 'APP_DIRS': True,
+ 'OPTIONS': {
+ 'context_processors': [
+ # Insert your TEMPLATE_CONTEXT_PROCESSORS here or use this
+ # list if you haven't customized them:
+ 'django.contrib.auth.context_processors.auth',
+ 'django.template.context_processors.debug',
+ 'django.template.context_processors.i18n',
+ 'django.template.context_processors.media',
+ 'django.template.context_processors.static',
+ 'django.template.context_processors.tz',
+ 'django.contrib.messages.context_processors.messages',
+ ],
+ },
+ },
+]
diff --git a/tests/test_fields.py b/tests/test_fields.py
new file mode 100644
index 0000000000..f6ad676e76
--- /dev/null
+++ b/tests/test_fields.py
@@ -0,0 +1,47 @@
+from django.test import TestCase
+from ajax_select import fields
+
+
+class TestAutoCompleteSelectWidget(TestCase):
+
+ def test_render(self):
+ channel = 'book'
+ widget = fields.AutoCompleteSelectWidget(channel)
+ out = widget.render('book', None)
+ self.assertTrue('autocompleteselect' in out)
+
+
+class TestAutoCompleteSelectMultipleWidget(TestCase):
+
+ def test_render(self):
+ channel = 'book'
+ widget = fields.AutoCompleteSelectMultipleWidget(channel)
+ out = widget.render('book', None)
+ self.assertTrue('autocompleteselectmultiple' in out)
+
+
+class TestAutoCompleteWidget(TestCase):
+
+ def test_render(self):
+ channel = 'book'
+ widget = fields.AutoCompleteWidget(channel)
+ out = widget.render('book', None)
+ self.assertTrue('autocomplete' in out)
+
+
+class TestAutoCompleteSelectField(TestCase):
+
+ def test_has_changed(self):
+ field = fields.AutoCompleteSelectField('book')
+ self.assertFalse(field.has_changed(1, '1'))
+ self.assertFalse(field.has_changed('abc', 'abc'))
+ self.assertTrue(field.has_changed(1, '2'))
+
+
+class TestAutoCompleteSelectMultipleField(TestCase):
+
+ def test_has_changed(self):
+ field = fields.AutoCompleteSelectMultipleField('book')
+ self.assertFalse(field.has_changed([1], ['1']))
+ self.assertFalse(field.has_changed(['abc'], ['abc']))
+ self.assertTrue(field.has_changed([1], ['2']))
diff --git a/tests/test_registry.py b/tests/test_registry.py
new file mode 100644
index 0000000000..a1f2d908eb
--- /dev/null
+++ b/tests/test_registry.py
@@ -0,0 +1,39 @@
+
+from django.test import TestCase
+import ajax_select
+from ajax_select.registry import can_autodiscover
+
+
+class TestRegistry(TestCase):
+
+ def test_lookup_py_is_autoloaded(self):
+ """Django >= 1.7 autoloads tests/lookups.py"""
+ is_registered = ajax_select.registry.is_registered('person')
+ if can_autodiscover():
+ self.assertTrue(is_registered)
+ else:
+ # person is not in settings and this django will not autoload lookups.py
+ self.assertFalse(is_registered)
+
+ def test_back_compatible_loads_by_settings(self):
+ """a module and class specified in settings"""
+ self.assertTrue(ajax_select.registry.is_registered('book'))
+
+ def test_autoconstruct_from_spec(self):
+ """a dict in settings specifying model and lookup fields"""
+ self.assertTrue(ajax_select.registry.is_registered('author'))
+
+ def test_unsetting_a_channel(self):
+ """settings can unset a channel that was specified in a lookups.py"""
+ self.assertFalse(ajax_select.registry.is_registered('user'))
+ self.assertFalse(ajax_select.registry.is_registered('was-never-a-channel'))
+
+ # def test_reimporting_lookup(self):
+ # """
+ # Importing a lookup should not re-register it after app launch is completed.
+ # """
+ # # importing this file will cause the @register to be called
+ # from tests import lookups # noqa
+ # # should not have over-ridden what is in settings
+ # # registry is already frozen
+ # self.assertFalse(ajax_select.registry.is_registered('user'))
diff --git a/tests/test_views.py b/tests/test_views.py
new file mode 100644
index 0000000000..4ac6799940
--- /dev/null
+++ b/tests/test_views.py
@@ -0,0 +1,42 @@
+
+from django.test import TestCase
+from django.contrib.auth.models import User
+from django.test import Client
+from django.core import urlresolvers
+
+
+class TestViews(TestCase):
+
+ def setUp(self):
+ self.user = User.objects.create_superuser(username='admin',
+ email='email@example.com',
+ password='password')
+ self.client = Client()
+ self.client.login(username='admin', password='password')
+
+ def test_add_popup_get(self):
+ app_label = 'tests'
+ model = 'author'
+ url = urlresolvers.reverse('add_popup', kwargs={
+ 'app_label': app_label,
+ 'model': model
+ })
+ response = self.client.get(url)
+ self.assertEqual(response.status_code, 200)
+
+ def test_add_popup_post(self):
+ app_label = 'tests'
+ model = 'author'
+ url = urlresolvers.reverse('add_popup', kwargs={
+ 'app_label': app_label,
+ 'model': model
+ })
+ data = dict(name='Name')
+ response = self.client.post(url, data)
+
+ self.assertEqual(response.status_code, 200)
+ content = response.content.decode('UTF-8')
+
+ self.assertFalse('dismissAddRelatedObjectPopup' in content)
+ self.assertFalse('dismissAddAnotherPopup' in content)
+ self.assertTrue('didAddPopup' in content)
diff --git a/tests/urls.py b/tests/urls.py
new file mode 100644
index 0000000000..9b70099602
--- /dev/null
+++ b/tests/urls.py
@@ -0,0 +1,14 @@
+
+from django.conf.urls import url, include
+from django.conf.urls.static import static
+from django.contrib import admin
+from django.conf import settings
+from ajax_select import urls as ajax_select_urls
+
+
+admin.autodiscover()
+
+urlpatterns = [
+ url(r'^ajax_lookups/', include(ajax_select_urls)),
+ url(r'^admin/', include(admin.site.urls)),
+] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
diff --git a/tox.ini b/tox.ini
new file mode 100644
index 0000000000..98e0f5cd66
--- /dev/null
+++ b/tox.ini
@@ -0,0 +1,46 @@
+[tox]
+envlist =
+ {py27,py34}-flake8,
+ {py27,py32,py33}-dj{15,16},
+ {py27,py34,py35}-dj{17,18,19}
+skip_missing_interpreters = true
+
+
+[testenv]
+setenv =
+ DJANGO_SETTINGS_MODULE=tests.settings
+ PYTHONPATH = {toxinidir}:{toxinidir}/ajax_select:{toxinidir}/tests
+commands = django-admin.py test tests
+deps =
+ dj14: Django>=1.4,<1.5
+ dj15: Django>=1.5,<1.6
+ dj16: Django>=1.6,<1.7
+ dj17: Django>=1.7,<1.8
+ dj18: Django>=1.8,<1.9
+ dj19: Django==1.9b1
+ ; djmaster: https://github.com/django/django/zipball/master
+
+[testenv:py27-flake8]
+deps =
+ flake8
+commands = flake8 ajax_select tests example
+
+[testenv:py32-flake8]
+deps =
+ flake8
+commands = flake8 ajax_select tests example
+
+[testenv:py33-flake8]
+deps =
+ flake8
+commands = flake8 ajax_select tests example
+
+[testenv:py34-flake8]
+deps =
+ flake8
+commands = flake8 ajax_select tests example
+
+[testenv:py35-flake8]
+deps =
+ flake8
+commands = flake8 ajax_select tests example