From a6d3b44038885386a705e58d7c9bed9fdf2abe82 Mon Sep 17 00:00:00 2001 From: Magnus Hagander Date: Thu, 23 Jun 2016 17:56:42 +0200 Subject: [PATCH] Import django-selectable This will also be used to do /admin/ autocompletes. --- dep/django-selectable/.coveragerc | 3 + dep/django-selectable/.tx/config | 8 + dep/django-selectable/AUTHORS.txt | 27 + dep/django-selectable/LICENSE.txt | 23 + dep/django-selectable/MANIFEST.in | 6 + dep/django-selectable/PKG-INFO | 92 + dep/django-selectable/README.rst | 69 + dep/django-selectable/docs/Makefile | 130 + dep/django-selectable/docs/admin.rst | 99 + dep/django-selectable/docs/advanced.rst | 334 ++ dep/django-selectable/docs/conf.py | 216 + dep/django-selectable/docs/contribute.rst | 88 + dep/django-selectable/docs/fields.rst | 48 + dep/django-selectable/docs/index.rst | 27 + dep/django-selectable/docs/lookups.rst | 287 ++ dep/django-selectable/docs/make.bat | 170 + dep/django-selectable/docs/overview.rst | 29 + dep/django-selectable/docs/quick-start.rst | 141 + dep/django-selectable/docs/releases.rst | 268 ++ dep/django-selectable/docs/settings.rst | 109 + dep/django-selectable/docs/testing.rst | 149 + dep/django-selectable/docs/widgets.rst | 120 + dep/django-selectable/grunt.js | 61 + dep/django-selectable/runtests.py | 38 + dep/django-selectable/selectable/__init__.py | 6 + dep/django-selectable/selectable/apps.py | 14 + dep/django-selectable/selectable/base.py | 175 + dep/django-selectable/selectable/compat.py | 36 + .../selectable/decorators.py | 64 + .../selectable/exceptions.py | 10 + .../selectable/forms/__init__.py | 3 + .../selectable/forms/base.py | 44 + .../selectable/forms/fields.py | 118 + .../selectable/forms/widgets.py | 253 + .../locale/en/LC_MESSAGES/django.mo | Bin 0 -> 378 bytes .../locale/en/LC_MESSAGES/django.po | 26 + .../locale/es/LC_MESSAGES/django.mo | Bin 0 -> 721 bytes .../locale/es/LC_MESSAGES/django.po | 27 + .../locale/fr/LC_MESSAGES/django.mo | Bin 0 -> 725 bytes .../locale/fr/LC_MESSAGES/django.po | 28 + .../locale/pl/LC_MESSAGES/django.mo | Bin 0 -> 761 bytes .../locale/pl/LC_MESSAGES/django.po | 28 + .../locale/pt_BR/LC_MESSAGES/django.mo | Bin 0 -> 733 bytes .../locale/pt_BR/LC_MESSAGES/django.po | 27 + .../locale/zh_CN/LC_MESSAGES/django.mo | Bin 0 -> 709 bytes .../locale/zh_CN/LC_MESSAGES/django.po | 28 + dep/django-selectable/selectable/models.py | 10 + dep/django-selectable/selectable/registry.py | 62 + .../static/selectable/css/dj.selectable.css | 47 + .../selectable/js/jquery.dj.selectable.js | 390 ++ .../templates/selectable/jquery-css.html | 1 + .../templates/selectable/jquery-js.html | 2 + .../selectable/templatetags/__init__.py | 0 .../templatetags/selectable_tags.py | 17 + .../selectable/tests/__init__.py | 50 + .../selectable/tests/base.py | 63 + .../selectable/tests/decorators.py | 91 + .../selectable/tests/fields.py | 134 + .../selectable/tests/forms.py | 86 + .../selectable/tests/functests.py | 502 ++ .../selectable/tests/qunit/helpers.js | 108 + .../selectable/tests/qunit/index.html | 22 + .../selectable/tests/qunit/jquery-loader.js | 13 + .../selectable/tests/qunit/main.js | 19 + .../selectable/tests/qunit/sinon-1.5.2.js | 4153 +++++++++++++++++ .../selectable/tests/qunit/test-events.js | 221 + .../selectable/tests/qunit/test-methods.js | 239 + .../selectable/tests/qunit/test-options.js | 174 + .../selectable/tests/templatetags.py | 115 + .../selectable/tests/test_base.py | 131 + .../selectable/tests/test_decorators.py | 94 + .../selectable/tests/test_fields.py | 134 + .../selectable/tests/test_forms.py | 86 + .../selectable/tests/test_functional.py | 538 +++ .../selectable/tests/test_templatetags.py | 115 + .../selectable/tests/test_views.py | 91 + .../selectable/tests/test_widgets.py | 477 ++ .../selectable/tests/urls.py | 9 + .../selectable/tests/views.py | 8 + .../selectable/tests/widgets.py | 470 ++ dep/django-selectable/selectable/urls.py | 15 + dep/django-selectable/selectable/views.py | 16 + dep/django-selectable/setup.cfg | 8 + dep/django-selectable/setup.py | 44 + media/selectable/css/dj.selectable.css | 47 + media/selectable/js/jquery.dj.selectable.js | 390 ++ pgweb/selectable | 1 + selectable | 1 + 88 files changed, 12623 insertions(+) create mode 100644 dep/django-selectable/.coveragerc create mode 100644 dep/django-selectable/.tx/config create mode 100644 dep/django-selectable/AUTHORS.txt create mode 100644 dep/django-selectable/LICENSE.txt create mode 100644 dep/django-selectable/MANIFEST.in create mode 100644 dep/django-selectable/PKG-INFO create mode 100644 dep/django-selectable/README.rst create mode 100644 dep/django-selectable/docs/Makefile create mode 100644 dep/django-selectable/docs/admin.rst create mode 100644 dep/django-selectable/docs/advanced.rst create mode 100644 dep/django-selectable/docs/conf.py create mode 100644 dep/django-selectable/docs/contribute.rst create mode 100644 dep/django-selectable/docs/fields.rst create mode 100644 dep/django-selectable/docs/index.rst create mode 100644 dep/django-selectable/docs/lookups.rst create mode 100644 dep/django-selectable/docs/make.bat create mode 100644 dep/django-selectable/docs/overview.rst create mode 100644 dep/django-selectable/docs/quick-start.rst create mode 100644 dep/django-selectable/docs/releases.rst create mode 100644 dep/django-selectable/docs/settings.rst create mode 100644 dep/django-selectable/docs/testing.rst create mode 100644 dep/django-selectable/docs/widgets.rst create mode 100644 dep/django-selectable/grunt.js create mode 100644 dep/django-selectable/runtests.py create mode 100644 dep/django-selectable/selectable/__init__.py create mode 100644 dep/django-selectable/selectable/apps.py create mode 100644 dep/django-selectable/selectable/base.py create mode 100644 dep/django-selectable/selectable/compat.py create mode 100644 dep/django-selectable/selectable/decorators.py create mode 100644 dep/django-selectable/selectable/exceptions.py create mode 100644 dep/django-selectable/selectable/forms/__init__.py create mode 100644 dep/django-selectable/selectable/forms/base.py create mode 100644 dep/django-selectable/selectable/forms/fields.py create mode 100644 dep/django-selectable/selectable/forms/widgets.py create mode 100644 dep/django-selectable/selectable/locale/en/LC_MESSAGES/django.mo create mode 100644 dep/django-selectable/selectable/locale/en/LC_MESSAGES/django.po create mode 100644 dep/django-selectable/selectable/locale/es/LC_MESSAGES/django.mo create mode 100644 dep/django-selectable/selectable/locale/es/LC_MESSAGES/django.po create mode 100644 dep/django-selectable/selectable/locale/fr/LC_MESSAGES/django.mo create mode 100644 dep/django-selectable/selectable/locale/fr/LC_MESSAGES/django.po create mode 100644 dep/django-selectable/selectable/locale/pl/LC_MESSAGES/django.mo create mode 100644 dep/django-selectable/selectable/locale/pl/LC_MESSAGES/django.po create mode 100644 dep/django-selectable/selectable/locale/pt_BR/LC_MESSAGES/django.mo create mode 100644 dep/django-selectable/selectable/locale/pt_BR/LC_MESSAGES/django.po create mode 100644 dep/django-selectable/selectable/locale/zh_CN/LC_MESSAGES/django.mo create mode 100644 dep/django-selectable/selectable/locale/zh_CN/LC_MESSAGES/django.po create mode 100644 dep/django-selectable/selectable/models.py create mode 100644 dep/django-selectable/selectable/registry.py create mode 100644 dep/django-selectable/selectable/static/selectable/css/dj.selectable.css create mode 100644 dep/django-selectable/selectable/static/selectable/js/jquery.dj.selectable.js create mode 100644 dep/django-selectable/selectable/templates/selectable/jquery-css.html create mode 100644 dep/django-selectable/selectable/templates/selectable/jquery-js.html create mode 100755 dep/django-selectable/selectable/templatetags/__init__.py create mode 100755 dep/django-selectable/selectable/templatetags/selectable_tags.py create mode 100644 dep/django-selectable/selectable/tests/__init__.py create mode 100644 dep/django-selectable/selectable/tests/base.py create mode 100644 dep/django-selectable/selectable/tests/decorators.py create mode 100644 dep/django-selectable/selectable/tests/fields.py create mode 100644 dep/django-selectable/selectable/tests/forms.py create mode 100644 dep/django-selectable/selectable/tests/functests.py create mode 100644 dep/django-selectable/selectable/tests/qunit/helpers.js create mode 100644 dep/django-selectable/selectable/tests/qunit/index.html create mode 100644 dep/django-selectable/selectable/tests/qunit/jquery-loader.js create mode 100644 dep/django-selectable/selectable/tests/qunit/main.js create mode 100644 dep/django-selectable/selectable/tests/qunit/sinon-1.5.2.js create mode 100644 dep/django-selectable/selectable/tests/qunit/test-events.js create mode 100644 dep/django-selectable/selectable/tests/qunit/test-methods.js create mode 100644 dep/django-selectable/selectable/tests/qunit/test-options.js create mode 100644 dep/django-selectable/selectable/tests/templatetags.py create mode 100644 dep/django-selectable/selectable/tests/test_base.py create mode 100644 dep/django-selectable/selectable/tests/test_decorators.py create mode 100644 dep/django-selectable/selectable/tests/test_fields.py create mode 100644 dep/django-selectable/selectable/tests/test_forms.py create mode 100644 dep/django-selectable/selectable/tests/test_functional.py create mode 100644 dep/django-selectable/selectable/tests/test_templatetags.py create mode 100644 dep/django-selectable/selectable/tests/test_views.py create mode 100644 dep/django-selectable/selectable/tests/test_widgets.py create mode 100644 dep/django-selectable/selectable/tests/urls.py create mode 100644 dep/django-selectable/selectable/tests/views.py create mode 100644 dep/django-selectable/selectable/tests/widgets.py create mode 100644 dep/django-selectable/selectable/urls.py create mode 100644 dep/django-selectable/selectable/views.py create mode 100644 dep/django-selectable/setup.cfg create mode 100644 dep/django-selectable/setup.py create mode 100644 media/selectable/css/dj.selectable.css create mode 100644 media/selectable/js/jquery.dj.selectable.js create mode 120000 pgweb/selectable create mode 120000 selectable diff --git a/dep/django-selectable/.coveragerc b/dep/django-selectable/.coveragerc new file mode 100644 index 00000000..085d7310 --- /dev/null +++ b/dep/django-selectable/.coveragerc @@ -0,0 +1,3 @@ +[run] +source = selectable +omit = */tests*,*/urls.py diff --git a/dep/django-selectable/.tx/config b/dep/django-selectable/.tx/config new file mode 100644 index 00000000..abd60100 --- /dev/null +++ b/dep/django-selectable/.tx/config @@ -0,0 +1,8 @@ +[main] +host = https://www.transifex.com + +[django-selectable.txo] +file_filter = selectable/locale//LC_MESSAGES/django.po +source_file = selectable/locale/en/LC_MESSAGES/django.po +source_lang = en +type = PO diff --git a/dep/django-selectable/AUTHORS.txt b/dep/django-selectable/AUTHORS.txt new file mode 100644 index 00000000..1c0422f2 --- /dev/null +++ b/dep/django-selectable/AUTHORS.txt @@ -0,0 +1,27 @@ +Primary author: + +Mark Lavin + +The following people who have contributed to django-selectable: + +Michael Manfre +Luke Plant +Augusto Men +@dc +Colin Copeland +Sławomir Ehlert +Dan Poirier +Felipe Prenholato +David Ray +Rick Testore +Karen Tracey +Manuel Alvarez +Ustun Ozgur +@leo-the-manic +Calvin Spealman +Rebecca Lovewell +Thomas Güttler +Yuri Khrustalev +@SaeX + +Thanks for all of your work! diff --git a/dep/django-selectable/LICENSE.txt b/dep/django-selectable/LICENSE.txt new file mode 100644 index 00000000..c50fbf06 --- /dev/null +++ b/dep/django-selectable/LICENSE.txt @@ -0,0 +1,23 @@ +Copyright (c) 2010-2014, Mark Lavin +All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, +this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, +this list of conditions and the following disclaimer in the documentation +and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR +ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON +ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/dep/django-selectable/MANIFEST.in b/dep/django-selectable/MANIFEST.in new file mode 100644 index 00000000..ce396ae2 --- /dev/null +++ b/dep/django-selectable/MANIFEST.in @@ -0,0 +1,6 @@ +include AUTHORS.txt +include README.rst +include LICENSE.txt +recursive-include selectable/locale * +recursive-include selectable/static * +recursive-include selectable/templates * diff --git a/dep/django-selectable/PKG-INFO b/dep/django-selectable/PKG-INFO new file mode 100644 index 00000000..4a7072da --- /dev/null +++ b/dep/django-selectable/PKG-INFO @@ -0,0 +1,92 @@ +Metadata-Version: 1.1 +Name: django-selectable +Version: 0.9.0 +Summary: Auto-complete selection widgets using Django and jQuery UI. +Home-page: https://github.com/mlavin/django-selectable +Author: Mark Lavin +Author-email: markdlavin@gmail.com +License: BSD +Description: django-selectable + =================== + + Tools and widgets for using/creating auto-complete selection widgets using Django and jQuery UI. + + .. image:: https://travis-ci.org/mlavin/django-selectable.svg?branch=master + :target: https://travis-ci.org/mlavin/django-selectable + + + Features + ----------------------------------- + + - Works with the latest jQuery UI Autocomplete library + - Auto-discovery/registration pattern for defining lookups + + + Installation Requirements + ----------------------------------- + + - Python 2.6-2.7, 3.2+ + - `Django `_ >= 1.5 + - `jQuery `_ >= 1.7 + - `jQuery UI `_ >= 1.8 + + To install:: + + pip install django-selectable + + Next add `selectable` to your `INSTALLED_APPS` to include the related css/js:: + + INSTALLED_APPS = ( + 'contrib.staticfiles', + # Other apps here + 'selectable', + ) + + The jQuery and jQuery UI libraries are not included in the distribution but must be included + in your templates. See the example project for an example using these libraries from the + Google CDN. + + Once installed you should add the urls to your root url patterns:: + + urlpatterns = patterns('', + # Other patterns go here + (r'^selectable/', include('selectable.urls')), + ) + + + Documentation + ----------------------------------- + + Documentation for django-selectable is available on `Read The Docs `_. + + + Additional Help/Support + ----------------------------------- + + You can find additional help or support on the mailing list: http://groups.google.com/group/django-selectable + + + Contributing + -------------------------------------- + + If you think you've found a bug or are interested in contributing to this project + check out our `contributing guide `_. + + If you are interested in translating django-selectable into your native language + you can join the `Transifex project `_. + + +Platform: UNKNOWN +Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content +Classifier: Intended Audience :: Developers +Classifier: License :: OSI Approved :: BSD License +Classifier: Programming Language :: Python +Classifier: Programming Language :: Python :: 2.6 +Classifier: Programming Language :: Python :: 2.7 +Classifier: Programming Language :: Python :: 3 +Classifier: Programming Language :: Python :: 3.2 +Classifier: Programming Language :: Python :: 3.3 +Classifier: Programming Language :: Python :: 3.4 +Classifier: Framework :: Django +Classifier: Development Status :: 5 - Production/Stable +Classifier: Operating System :: OS Independent diff --git a/dep/django-selectable/README.rst b/dep/django-selectable/README.rst new file mode 100644 index 00000000..0219c2cb --- /dev/null +++ b/dep/django-selectable/README.rst @@ -0,0 +1,69 @@ +django-selectable +=================== + +Tools and widgets for using/creating auto-complete selection widgets using Django and jQuery UI. + +.. image:: https://travis-ci.org/mlavin/django-selectable.svg?branch=master + :target: https://travis-ci.org/mlavin/django-selectable + + +Features +----------------------------------- + +- Works with the latest jQuery UI Autocomplete library +- Auto-discovery/registration pattern for defining lookups + + +Installation Requirements +----------------------------------- + +- Python 2.6-2.7, 3.2+ +- `Django `_ >= 1.5 +- `jQuery `_ >= 1.7 +- `jQuery UI `_ >= 1.8 + +To install:: + + pip install django-selectable + +Next add `selectable` to your `INSTALLED_APPS` to include the related css/js:: + + INSTALLED_APPS = ( + 'contrib.staticfiles', + # Other apps here + 'selectable', + ) + +The jQuery and jQuery UI libraries are not included in the distribution but must be included +in your templates. See the example project for an example using these libraries from the +Google CDN. + +Once installed you should add the urls to your root url patterns:: + + urlpatterns = patterns('', + # Other patterns go here + (r'^selectable/', include('selectable.urls')), + ) + + +Documentation +----------------------------------- + +Documentation for django-selectable is available on `Read The Docs `_. + + +Additional Help/Support +----------------------------------- + +You can find additional help or support on the mailing list: http://groups.google.com/group/django-selectable + + +Contributing +-------------------------------------- + +If you think you've found a bug or are interested in contributing to this project +check out our `contributing guide `_. + +If you are interested in translating django-selectable into your native language +you can join the `Transifex project `_. + diff --git a/dep/django-selectable/docs/Makefile b/dep/django-selectable/docs/Makefile new file mode 100644 index 00000000..87770d95 --- /dev/null +++ b/dep/django-selectable/docs/Makefile @@ -0,0 +1,130 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Django-Selectable.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Django-Selectable.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Django-Selectable" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Django-Selectable" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + make -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/dep/django-selectable/docs/admin.rst b/dep/django-selectable/docs/admin.rst new file mode 100644 index 00000000..07cba698 --- /dev/null +++ b/dep/django-selectable/docs/admin.rst @@ -0,0 +1,99 @@ +Admin Integration +==================== + +Overview +-------------------------------------- + +Django-Selectables will work in the admin. To get started on integrated the +fields and widgets in the admin make sure you are familiar with the Django +documentation on the `ModelAdmin.form `_ +and `ModelForms `_ particularly +on `overriding the default widgets `_. +As you will see integrating django-selectable in the adminis the same as working with regular forms. + + +.. _admin-jquery-include: + +Including jQuery & jQuery UI +-------------------------------------- + +As noted :ref:`in the quick start guide `, the jQuery and jQuery UI libraries +are not included in the distribution but must be included in your templates. For the +Django admin that means overriding +`admin/base_site.html `_. +You can include this media in the block name `extrahead` which is defined in +`admin/base.html `_. + + .. literalinclude:: ../example/example/templates/admin/base_site.html + :start-after: {% endblock title %} + :end-before: {% block branding %} + +See the Django documentation on +`overriding admin templates `_. +See the example project for the full template example. + + +.. _admin-grappelli: + +Using Grappelli +-------------------------------------- + +.. versionadded:: 0.7 + +`Grappelli `_ is a popular customization of the Django +admin interface. It includes a number of interface improvements which are also built on top of +jQuery UI. When using Grappelli you do not need to make any changes to the ``admin/base_site.html`` +template. django-selectable will detect jQuery and jQuery UI versions included by Grappelli +and make use of them. + + +.. _admin-basic-example: + +Basic Example +-------------------------------------- + +In our sample project we have a ``Farm`` model with a foreign key to ``auth.User`` and +a many to many relation to our ``Fruit`` model. + + .. literalinclude:: ../example/core/models.py + :pyobject: Farm + +In `admin.py` we will define the form and associate it with the `FarmAdmin`. + + .. literalinclude:: ../example/core/admin.py + :pyobject: FarmAdminForm + + .. literalinclude:: ../example/core/admin.py + :pyobject: FarmAdmin + +You'll note this form also allows new users to be created and associated with the +farm, if no user is found matching the given name. To make use of this feature we +need to add ``owner`` to the exclude so that it will pass model validation. Unfortunately +that means we must set the owner manual in the save and in the initial data because +the ``ModelForm`` will no longer do this for you. Since ``fruit`` does not allow new +items you'll see these steps are not necessary. + +The django-selectable widgets are compatitible with the add another popup in the +admin. It's that little green plus sign that appears next to ``ForeignKey`` or +``ManyToManyField`` items. This makes django-selectable a user friendly replacement +for the `ModelAdmin.raw_id_fields `_ +when the default select box grows too long. + + +.. _admin-inline-example: + +Inline Example +-------------------------------------- + +With our ``Farm`` model we can also associate the ``UserAdmin`` with a ``Farm`` +by making use of the `InlineModelAdmin +`_. +We can even make use of the same ``FarmAdminForm``. + + .. literalinclude:: ../example/core/admin.py + :pyobject: FarmInline + .. literalinclude:: ../example/core/admin.py + :pyobject: NewUserAdmin + +The auto-complete functions will be bound as new forms are added dynamically. + diff --git a/dep/django-selectable/docs/advanced.rst b/dep/django-selectable/docs/advanced.rst new file mode 100644 index 00000000..bbaa3df4 --- /dev/null +++ b/dep/django-selectable/docs/advanced.rst @@ -0,0 +1,334 @@ +Advanced Usage +========================== + +We've gone through the most command and simple use cases for django-selectable. Now +we'll take a lot at some of the more advanced features of this project. This assumes +that you are comfortable reading and writing a little bit of Javascript making +use of jQuery. + + +.. _additional-parameters: + +Additional Parameters +-------------------------------------- + +The basic lookup is based on handling a search based on a single term string. +If additional filtering is needed it can be inside the lookup ``get_query`` but +you would need to define this when the lookup is defined. While this fits a fair +number of use cases there are times when you need to define additional query +parameters that won't be know until the either the form is bound or until selections +are made on the client side. This section will detail how to handle both of these +cases. + + +How Parameters are Passed +_______________________________________ + +As with the search term the additional parameters you define will be passed in +``request.GET``. Since ``get_query`` gets the current request so you will have access to +them. Since they can be manipulated on the client side, these parameters should be +treated like all user input. It should be properly validated and sanitized. + + +Limiting the Result Set +_______________________________________ + +The number of results are globally limited/paginated by the :ref:`SELECTABLE_MAX_LIMIT` +but you can also lower this limit on the field or widget level. Each field and widget +takes a ``limit`` argument in the ``__init__`` that will be passed back to the lookup +through the ``limit`` query parameter. The result set will be automatically paginated +for you if you use either this parameter or the global setting. + + +.. _server-side-parameters: + +Adding Parameters on the Server Side +_______________________________________ + +Each of the widgets define ``update_query_parameters`` which takes a dictionary. The +most common way to use this would be in the form ``__init__``. + + .. code-block:: python + + class FruitForm(forms.Form): + autocomplete = forms.CharField( + label='Type the name of a fruit (AutoCompleteWidget)', + widget=selectable.AutoCompleteWidget(FruitLookup), + required=False, + ) + + def __init__(self, *args, **kwargs): + super(FruitForm, self).__init__(*args, **kwargs) + self.fields['autocomplete'].widget.update_query_parameters({'foo': 'bar'}) + +You can also pass the query parameters into the widget using the ``query_params`` +keyword argument. It depends on your use case as to whether the parameters are +know when the form is defined or when an instance of the form is created. + + +.. _client-side-parameters: + +Adding Parameters on the Client Side +_______________________________________ + +There are times where you want to filter the result set based other selections +by the user such as a filtering cities by a previously selected state. In this +case you will need to bind a ``prepareQuery`` to the field. This function should accept the query dictionary. +You are free to make adjustments to the query dictionary as needed. + + .. code-block:: html + + + +.. note:: + + In v0.7 the scope of ``prepareQuery`` was updated so that ``this`` refers to the + current ``djselectable`` plugin instance. Previously ``this`` refered to the + plugin ``options`` instance. + + +.. _chain-select-example: + +Chained Selection +-------------------------------------- + +It's a fairly common pattern to have two or more inputs depend one another such City/State/Zip. +In fact there are other Django apps dedicated to this purpose such as +`django-smart-selects `_ or +`django-ajax-filtered-fields `_. +It's possible to handle this kind of selection with django-selectable if you are willing +to write a little javascript. + +Suppose we have city model + + .. literalinclude:: ../example/core/models.py + :pyobject: City + +and a simple form + + .. literalinclude:: ../example/core/forms.py + :pyobject: ChainedForm + +We want our users to select a city and if they choose a state then we will only +show them cities in that state. To do this we will pass back chosen state as +addition parameter with the following javascript: + + .. literalinclude:: ../example/core/templates/advanced.html + :language: html + :start-after: {% block extra-js %} + :end-before: {% endblock %} + + +Then in our lookup we will grab the state value and filter our results on it: + + .. literalinclude:: ../example/core/lookups.py + :pyobject: CityLookup + +And that's it! We now have a working chained selection example. The full source +is included in the example project. + +.. _client-side-changes: + +Detecting Client Side Changes +____________________________________________ + +The previous example detected selection changes on the client side to allow passing +parameters to the lookup. Since django-selectable is built on top of the jQuery UI +`Autocomplete plug-in `_, the widgets +expose the events defined by the plugin. + + - djselectablecreate + - djselectablesearch + - djselectableopen + - djselectablefocus + - djselectableselect + - djselectableclose + - djselectablechange + +.. note:: + + Prior to v0.7 these event names were under the ``autocomplete`` namespace. If you + are upgrading from a previous version and had customizations using these events + you should be sure to update the names. + +For the most part these event names should be self-explanatory. If you need additional +detail you should refer to the `jQuery UI docs on these events `_. + +The multiple select widgets include additional events which indicate when a new item is added +or removed from the current list. These events are ``djselectableadd`` and ``djselectableremove``. +These events pass a dictionary of data with the following keys + + - element: The original text input + - input: The hidden input to be added for the new item + - wrapper: The ``
  • `` element to be added to the deck + - deck: The outer ``
      `` deck element + +You can use these events to prevent items from being added or removed from the deck by +returning ``false`` in the handling function. A simple example is given below: + + .. code-block:: html + + + + +Submit On Selection +-------------------------------------- + +You might want to help your users by submitting the form once they have selected a valid +item. To do this you simply need to listen for the ``djselectableselect`` event. This +event is fired by the text input which has an index of 0. If your field is named ``my_field`` +then input to watch would be ``my_field_0`` such as: + + .. code-block:: html + + + + +Dynamically Added Forms +-------------------------------------- + +django-selectable can work with dynamically added forms such as inlines in the admin. +To make django-selectable work in the admin there is nothing more to do than include +the necessary static media as described in the +:ref:`Admin Integration ` section. + +If you are making use of the popular `django-dynamic-formset `_ +then you can make django-selectable work by passing ``bindSelectables`` to the +`added `_ option: + + .. code-block:: html + + + +Currently you must include the django-selectable javascript below this formset initialization +code for this to work. See django-selectable `issue #31 `_ +for some additional detail on this problem. + + +.. _advanced-label-formats: + +Label Formats on the Client Side +-------------------------------------- + +The lookup label is the text which is shown in the list before it is selected. +You can use the :ref:`get_item_label ` method in your lookup +to do this on the server side. This works for most applications. However if you don't +want to write your HTML in Python or need to adapt the format on the client side you +can use the :ref:`formatLabel ` option. + +``formatLabel`` takes two paramaters the current label and the current selected item. +The item is a dictionary object matching what is returned by the lookup's +:ref:`format_item `. ``formatLabel`` should return the string +which should be used for the label. + +.. note:: + + In v0.7 the scope of ``formatLabel`` was updated so that ``this`` refers to the + current ``djselectable`` plugin instance. Previously ``this`` refered to the + plugin ``options`` instance. + +Going back to the ``CityLookup`` we can adjust the label to wrap the city and state +portions with their own classes for additional styling: + + .. literalinclude:: ../example/core/lookups.py + :pyobject: CityLookup + + .. code-block:: html + + + +This is a rather simple example but you could also pass additional information in ``format_item`` +such as a flag of whether the city is the capital and render the state captials differently. + +.. _advanced-bootstrap: + +Using with Twitter Bootstrap +-------------------------------------- + +django-selectable can work along side with Twitter Bootstrap but there are a few things to +take into consideration. Both jQuery UI and Bootstrap define a ``$.button`` plugin. This +plugin is used by default by django-selectable and expects the UI version. If the jQuery UI +JS is included after the Bootstrap JS then this will work just fine but the Bootstrap +button JS will not be available. This is the strategy taken by the `jQuery UI Bootstrap +`_ theme. + +Another option is to rename the Bootstrap plugin using the ``noConflict`` option. + + .. code-block:: html + + + + + +Even with this some might complain that it's too resource heavy to include all of +jQuery UI when you just want the autocomplete to work with django-selectable. For +this you can use the `Download Builder `_ to build +a minimal set of jQuery UI widgets. django-selectable requires the UI core, autocomplete, +menu and button widgets. None of the effects or interactions are needed. Minified +this totals around 100 kb of JS, CSS and images (based on jQuery UI 1.10). + +.. note:: + + For a comparison this is smaller than the minified Bootstrap 2.3.0 CSS + which is 105 kb not including the responsive CSS or the icon graphics. + +It is possible to remove the dependency on the UI button plugin and instead +use the Bootstrap button styles. This is done by overriding +the ``_comboButtonTemplate`` and ``_removeButtonTemplate`` functions used to +create the buttons. An example is given below. + + .. code-block:: html + + \ No newline at end of file diff --git a/dep/django-selectable/docs/conf.py b/dep/django-selectable/docs/conf.py new file mode 100644 index 00000000..19349e43 --- /dev/null +++ b/dep/django-selectable/docs/conf.py @@ -0,0 +1,216 @@ +# -*- coding: utf-8 -*- +# +# Django-Selectable documentation build configuration file, created by +# sphinx-quickstart on Sat Mar 12 14:14:16 2011. +# +# 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, 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('.')) + +# -- 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 = [] + +# 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-Selectable' +copyright = u'2011-2013, Mark Lavin' + +# 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 = '0.7' +# The full version, including alpha/beta/rc tags. +release = '0.7.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 = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# 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 +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Django-Selectabledoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'Django-Selectable.tex', u'Django-Selectable Documentation', + u'Mark Lavin', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'django-selectable', u'Django-Selectable Documentation', + [u'Mark Lavin'], 1) +] diff --git a/dep/django-selectable/docs/contribute.rst b/dep/django-selectable/docs/contribute.rst new file mode 100644 index 00000000..513b981f --- /dev/null +++ b/dep/django-selectable/docs/contribute.rst @@ -0,0 +1,88 @@ +.. _contributing-guide: + +Contributing +================== + +There are plenty of ways to contribute to this project. If you think you've found +a bug please submit an issue. If there is a feature you'd like to see then please +open an ticket proposal for it. If you've come up with some helpful examples then +you can add to our example project. + + +Getting the Source +-------------------------------------- + +The source code is hosted on `Bitbucket `_. +You can download the full source by cloning the hg repo:: + + hg clone https://bitbucket.org/mlavin/django-selectable + +Feel free to fork the project and make your own changes. If you think that it would +be helpful for other then please submit a pull request to have it merged in. + + +Submit an Issue +-------------------------------------- + +The issues are also managed on `Bitbucket issue page `_. +If you think you've found a bug it's helpful if you indicate the version of django-selectable +you are using the ticket version flag. If you think your bug is javascript related it is +also helpful to know the version of jQuery, jQuery UI, and the browser you are using. + +Issues are also used to track new features. If you have a feature you would like to see +you can submit a proposal ticket. You can also see features which are planned here. + + +Submit a Translation +-------------------------------------- + +We are working towards translating django-selectable into different languages. There +are not many strings to be translated so it is a reasonably easy task and a great way +to be involved with the project. The translations are managed through +`Transifex `_. + +Running the Test Suite +-------------------------------------- + +There are a number of tests in place to test the server side code for this +project. To run the tests you need Django and `mock `_ +installed and run:: + + python runtests.py + +`tox `_ is used to test django-selectable +against multiple versions of Django/Python. With tox installed you can run:: + + tox + +to run all the version combinations. You can also run tox against a subset of supported +environments:: + + tox -e py26-1.4.X + +This example will run the test against the latest 1.5.X, 1.4.X, and 1.3.X releases +using Python 2.6 and 3.2 for 1.5+. For more information on running/installing tox please see the +tox documentation: http://tox.readthedocs.org/en/latest/index.html + +Client side tests are written using `QUnit `_. They +can be found in ``selectable/tests/qunit/index.html``. The test suite also uses +`Grunt `_ and `PhantomJS `_ to +run the tests. You can install Grunt and PhantomJS from NPM:: + + # Install grunt requirements + npm install -g grunt phantomjs jshint + # Execute default grunt tasks + grunt + + +Building the Documentation +-------------------------------------- + +The documentation is built using `Sphinx `_ +and available on `Read the Docs `_. With +Sphinx installed you can build the documentation by running:: + + make html + +inside the docs directory. Documentation fixes and improvements are always welcome. + diff --git a/dep/django-selectable/docs/fields.rst b/dep/django-selectable/docs/fields.rst new file mode 100644 index 00000000..3b5ad438 --- /dev/null +++ b/dep/django-selectable/docs/fields.rst @@ -0,0 +1,48 @@ +Fields +========== + +Django-Selectable defines a number of fields for selecting either single or mutliple +lookup items. Item in this context corresponds to the object return by the underlying +lookup ``get_item``. The single select select field :ref:`AutoCompleteSelectField` +allows for the creation of new items. To use this feature the field's +lookup class must define ``create_item``. In the case of lookups extending from +:ref:`ModelLookup` newly created items have not yet been saved into the database and saving +should be handled by the form. All fields take the lookup class as the first required +argument. + + +.. _AutoCompleteSelectField: + +AutoCompleteSelectField +-------------------------------------- + +Field tied to :ref:`AutoCompleteSelectWidget` to bind the selection to the form and +create new items, if allowed. The ``allow_new`` keyword argument (default: ``False``) +which determines if the field allows new items. This field cleans to a single item. + + .. literalinclude:: ../example/core/forms.py + :start-after: # AutoCompleteSelectField (no new items) + :end-before: # AutoCompleteSelectField (allows new items) + + +.. versionadded:: 0.7 + +`lookup_class`` may also be a dotted path. + + .. code-block:: python + + selectable.AutoCompleteSelectField(lookup_class='core.lookups.FruitLookup') + + +.. _AutoCompleteSelectMultipleField: + +AutoCompleteSelectMultipleField +-------------------------------------- + +Field tied to :ref:`AutoCompleteSelectMultipleWidget` to bind the selection to the form. +This field cleans to a list of items. :ref:`AutoCompleteSelectMultipleField` does not +allow for the creation of new items. + + .. literalinclude:: ../example/core/forms.py + :start-after: # AutoCompleteSelectMultipleField + :end-before: # AutoComboboxSelectMultipleField diff --git a/dep/django-selectable/docs/index.rst b/dep/django-selectable/docs/index.rst new file mode 100644 index 00000000..65703109 --- /dev/null +++ b/dep/django-selectable/docs/index.rst @@ -0,0 +1,27 @@ +.. include:: ../README.rst + +Contents: + +.. toctree:: + :maxdepth: 2 + + overview + quick-start + lookups + advanced + admin + testing + fields + widgets + settings + contribute + releases + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/dep/django-selectable/docs/lookups.rst b/dep/django-selectable/docs/lookups.rst new file mode 100644 index 00000000..20ba1c0d --- /dev/null +++ b/dep/django-selectable/docs/lookups.rst @@ -0,0 +1,287 @@ +Defining Lookups +================== + +What are Lookups? +-------------------------------------- + +Lookups define the corresponding ajax views used by the auto-completion +fields and widgets. They take in the current request and return the JSON +needed by the jQuery auto-complete plugin. + + +Defining a Lookup +-------------------------------------- + +django-selectable uses a registration pattern similar to the Django admin. +Lookups should be defined in a `lookups.py` in your application's module. Once defined +you must register in with django-selectable. All lookups must extend from +``selectable.base.LookupBase`` which defines the API for every lookup. + + .. code-block:: python + + from selectable.base import LookupBase + from selectable.registry import registry + + class MyLookup(LookupBase): + def get_query(self, request, term): + data = ['Foo', 'Bar'] + return filter(lambda x: x.startswith(term), data) + + registry.register(MyLookup) + + +Lookup API +-------------------------------------- + +.. py:method:: LookupBase.get_query(request, term) + + This is the main method which takes the current request + from the user and returns the data which matches their search. + + :param request: The current request object. + :param term: The search term from the widget input. + :return: An iterable set of data of items matching the search term. + +.. _lookup-get-item-label: + +.. py:method:: LookupBase.get_item_label(item) + + This is first of three formatting methods. The label is shown in the + drop down menu of search results. This defaults to ``item.__unicode__``. + + :param item: An item from the search results. + :return: A string representation of the item to be shown in the search results. + The label can include HTML. For changing the label format on the client side + see :ref:`Advanced Label Formats `. + + +.. py:method:: LookupBase.get_item_id(item) + + This is second of three formatting methods. The id is the value that will eventually + be returned by the field/widget. This defaults to ``item.__unicode__``. + + :param item: An item from the search results. + :return: A string representation of the item to be returned by the field/widget. + +.. py:method:: LookupBase.get_item_value(item) + + This is last of three formatting methods. The value is shown in the + input once the item has been selected. This defaults to ``item.__unicode__``. + + :param item: An item from the search results. + :return: A string representation of the item to be shown in the input. + +.. py:method:: LookupBase.get_item(value) + + ``get_item`` is the reverse of ``get_item_id``. This should take the value + from the form initial values and return the current item. This defaults + to simply return the value. + + :param value: Value from the form inital value. + :return: The item corresponding to the initial value. + +.. py:method:: LookupBase.create_item(value) + + If you plan to use a lookup with a field or widget which allows the user + to input new values then you must define what it means to create a new item + for your lookup. By default this raises a ``NotImplemented`` error. + + :param value: The user given value. + :return: The new item created from the item. + +.. _lookup-format-item: + +.. py:method:: LookupBase.format_item(item) + + By default ``format_item`` creates a dictionary with the three keys used by + the UI plugin: id, value, label. These are generated from the calls to + ``get_item_id``, ``get_item_value`` and ``get_item_label``. If you want to + add additional keys you should add them here. + + The results of ``get_item_label`` is conditionally escaped to prevent + Cross Site Scripting (XSS) similar to the templating language. + If you know that the content is safe and you want to use these methods + to include HTML should mark the content as safe with ``django.utils.safestring.mark_safe`` + inside the ``get_item_label`` method. + + ``get_item_id`` and ``get_item_value`` are not escapted by default. These are + not a XSS vector with the built-in JS. If you are doing additional formating using + these values you should be conscience of this fake and be sure to escape these + values. + + :param item: An item from the search results. + :return: A dictionary of information for this item to be sent back to the client. + +There are also some additional methods that you could want to use/override. These +are for more advanced use cases such as using the lookups with JS libraries other +than jQuery UI. Most users will not need to override these methods. + +.. _lookup-format-results: + +.. py:method:: LookupBase.format_results(self, raw_data, options) + + Returns a python structure that later gets serialized. This makes a call to + :ref:`paginate_results` prior to calling + :ref:`format_item` on each item in the current page. + + :param raw_data: The set of all matched results. + :param options: Dictionary of ``cleaned_data`` from the lookup form class. + :return: A dictionary with two keys ``meta`` and ``data``. + The value of ``data`` is an iterable extracted from page_data. + The value of ``meta`` is a dictionary. This is a copy of options with one additional element + ``more`` which is a translatable "Show more" string + (useful for indicating more results on the javascript side). + +.. _lookup-paginate-results: + +.. py:method:: LookupBase.paginate_results(results, options) + + If :ref:`SELECTABLE_MAX_LIMIT` is defined or ``limit`` is passed in request.GET + then ``paginate_results`` will return the current page using Django's + built in pagination. See the Django docs on + `pagination `_ + for more info. + + :param results: The set of all matched results. + :param options: Dictionary of ``cleaned_data`` from the lookup form class. + :return: The current `Page object `_ + of results. + +.. _lookup-serialize-results: + +.. py:method:: LookupBase.serialize_results(self, results) + + Returns serialized results for sending via http. You may choose to override + this if you are making use of + + :param results: a python structure to be serialized e.g. the one returned by :ref:`format_results` + :returns: JSON string. + + +.. _ModelLookup: + +Lookups Based on Models +-------------------------------------- + +Perhaps the most common use case is to define a lookup based on a given Django model. +For this you can extend ``selectable.base.ModelLookup``. To extend ``ModelLookup`` you +should set two class attributes: ``model`` and ``search_fields``. + + .. literalinclude:: ../example/core/lookups.py + :pyobject: FruitLookup + +The syntax for ``search_fields`` is the same as the Django +`field lookup syntax `_. +Each of these lookups are combined as OR so any one of them matching will return a +result. You may optionally define a third class attribute ``filters`` which is a dictionary of +filters to be applied to the model queryset. The keys should be a string defining a field lookup +and the value should be the value for the field lookup. Filters on the other hand are +combined with AND. + + +User Lookup Example +-------------------------------------- + +Below is a larger model lookup example using multiple search fields, filters +and display options for the `auth.User `_ +model. + + .. code-block:: python + + from django.contrib.auth.models import User + from selectable.base import ModelLookup + from selectable.registry import registry + + + class UserLookup(ModelLookup): + model = User + search_fields = ( + 'username__icontains', + 'first_name__icontains', + 'last_name__icontains', + ) + filters = {'is_active': True, } + + def get_item_value(self, item): + # Display for currently selected item + return item.username + + def get_item_label(self, item): + # Display for choice listings + return u"%s (%s)" % (item.username, item.get_full_name()) + + registry.register(UserLookup) + + +.. _lookup-decorators: + +Lookup Decorators +-------------------------------------- + +.. versionadded:: 0.5 + +Registering lookups with django-selectable creates a small API for searching the +lookup data. While the amount of visible data is small there are times when you want +to restrict the set of requests which can view the data. For this purpose there are +lookup decorators. To use them you simply decorate your lookup class. + + .. code-block:: python + + from django.contrib.auth.models import User + from selectable.base import ModelLookup + from selectable.decorators import login_required + from selectable.registry import registry + + + @login_required + class UserLookup(ModelLookup): + model = User + search_fields = ('username__icontains', ) + filters = {'is_active': True, } + + registry.register(UserLookup) + +.. note:: + + The class decorator syntax was introduced in Python 2.6. If you are using + django-selectable with Python 2.5 you can still make use of these decorators + by applying the without the decorator syntax. + + .. code-block:: python + + class UserLookup(ModelLookup): + model = User + search_fields = ('username__icontains', ) + filters = {'is_active': True, } + + UserLookup = login_required(UserLookup) + + registry.register(UserLookup) + +Below are the descriptions of the available lookup decorators. + + +ajax_required +______________________________________ + +The django-selectable javascript will always request the lookup data via +XMLHttpRequest (AJAX) request. This decorator enforces that the lookup can only +be accessed in this way. If the request is not an AJAX request then it will return +a 400 Bad Request response. + + +login_required +______________________________________ + +This decorator requires the user to be authenticated via ``request.user.is_authenticated``. +If the user is not authenticated this will return a 401 Unauthorized response. +``request.user`` is set by the ``django.contrib.auth.middleware.AuthenticationMiddleware`` +which is required for this decorator to work. This middleware is enabled by default. + +staff_member_required +______________________________________ + +This decorator builds from ``login_required`` and in addition requires that +``request.user.is_staff`` is ``True``. If the user is not authenticatated this will +continue to return at 401 response. If the user is authenticated but not a staff member +then this will return a 403 Forbidden response. diff --git a/dep/django-selectable/docs/make.bat b/dep/django-selectable/docs/make.bat new file mode 100644 index 00000000..253570f4 --- /dev/null +++ b/dep/django-selectable/docs/make.bat @@ -0,0 +1,170 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. changes to make an overview over all changed/added/deprecated items + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Django-Selectable.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Django-Selectable.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +:end diff --git a/dep/django-selectable/docs/overview.rst b/dep/django-selectable/docs/overview.rst new file mode 100644 index 00000000..6a097a6e --- /dev/null +++ b/dep/django-selectable/docs/overview.rst @@ -0,0 +1,29 @@ +Overview +================== + +Motivation +-------------------------------------- + +There are many Django apps related to auto-completion why create another? One problem +was varying support for the `jQuery UI auto-complete plugin `_ +versus the now deprecated `bassistance version `_. +Another was support for combo-boxes and multiple selects. And lastly was a simple syntax for +defining the related backend views for the auto-completion. + +This library aims to meet all of these goals: + - Built on jQuery UI auto-complete + - Fields and widgets for a variety of use-cases: + - Text inputs and combo-boxes + - Text selection + - Value/ID/Foreign key selection + - Multiple object selection + - Allowing new values + - Simple and extendable syntax for defining backend views + + +Related Projects +-------------------------------------- + +Much of the work here was inspired by things that I like (and things I don't like) about +`django-ajax-selects `_. To see some of the +other Django apps for handling auto-completion see `Django-Packages `_. diff --git a/dep/django-selectable/docs/quick-start.rst b/dep/django-selectable/docs/quick-start.rst new file mode 100644 index 00000000..7d14927c --- /dev/null +++ b/dep/django-selectable/docs/quick-start.rst @@ -0,0 +1,141 @@ +Getting Started +================== + +The workflow for using `django-selectable` involves two main parts: + - Defining your lookups + - Defining your forms + +This guide assumes that you have a basic knowledge of creating Django models and +forms. If not you should first read through the documentation on +`defining models `_ +and `using forms `_. + +.. _start-include-jquery: + +Including jQuery & jQuery UI +-------------------------------------- + +The widgets in django-selectable define the media they need as described in the +Django documentation on `Form Media `_. +That means to include the javascript and css you need to make the widgets work you +can include ``{{ form.media.css }}`` and ``{{ form.media.js }}`` in your template. This is +assuming your form is called `form` in the template context. For more information +please check out the `Django documentation `_. + +The jQuery and jQuery UI libraries are not included in the distribution but must be included +in your templates. However there is a template tag to easily add these libraries from +the from the `Google CDN `_. + + .. code-block:: html + + {% load selectable_tags %} + {% include_jquery_libs %} + +By default these will use jQuery v1.7.2 and jQuery UI v1.8.23. You can customize the versions +used by pass them to the tag. The first version is the jQuery version and the second is the +jQuery UI version. + + .. code-block:: html + + {% load selectable_tags %} + {% include_jquery_libs '1.4.4' '1.8.13' %} + +Django-Selectable should work with `jQuery `_ >= 1.4.4 and +`jQuery UI `_ >= 1.8.13. + +You must also include a `jQuery UI theme `_ stylesheet. There +is also a template tag to easily add this style sheet from the Google CDN. + + .. code-block:: html + + {% load selectable_tags %} + {% include_ui_theme %} + +By default this will use the `base `_ theme for jQuery UI v1.8.23. +You can configure the theme and version by passing them in the tag. + + .. code-block:: html + + {% load selectable_tags %} + {% include_ui_theme 'ui-lightness' '1.8.13' %} + +Or only change the theme. + + .. code-block:: html + + {% load selectable_tags %} + {% include_ui_theme 'ui-lightness' %} + +See the the jQuery UI documentation for a full list of available stable themes: http://jqueryui.com/download#stable-themes + +Of course you can choose to include these rescources manually:: + + .. code-block:: html + + + + + + + +.. note:: + + jQuery UI shares a few plugin names with the popular Twitter Bootstrap framework. There + are notes on using Bootstrap along with django-selectable in the :ref:`advanced usage + section `. + + +Defining a Lookup +-------------------------------- + +The lookup classes define the backend views. The most common case is defining a +lookup which searchs models based on a particular field. Let's define a simple model: + + .. literalinclude:: ../example/core/models.py + :pyobject: Fruit + +In a `lookups.py` we will define our lookup: + + .. literalinclude:: ../example/core/lookups.py + :pyobject: FruitLookup + +This lookups extends ``selectable.base.ModelLookup`` and defines two things: one is +the model on which we will be searching and the other is the field which we are searching. +This syntax should look familiar as it is the same as the `field lookup syntax `_ +for making queries in Django. + +Below this definition we will register our lookup class. + + .. code-block:: python + + registry.register(FruitLookup) + +.. note:: + + You should only register your lookup once. Attempting to register the same lookup class + more than once will lead to ``LookupAlreadyRegistered`` errors. A common problem related to the + ``LookupAlreadyRegistered`` error is related to inconsistant import paths in your project. + Prior to Django 1.4 the default ``manage.py`` allows for importing both with and without + the project name (i.e. ``from myproject.myapp import lookups`` or ``from myapp import lookups``). + This leads to the ``lookup.py`` file being imported twice and the registration code + executing twice. Thankfully this is no longer the default in Django 1.4. Keeping + your import consistant to include the project name (when your app is included inside the + project directory) will avoid these errors. + + +Defining Forms +-------------------------------- + +Now that we have a working lookup we will define a form which uses it: + + .. literalinclude:: ../example/core/forms.py + :pyobject: FruitForm + :end-before: newautocomplete + +This replaces the default widget for the ``CharField`` with the ``AutoCompleteWidget``. +This will allow the user to fill this field with values taken from the names of +existing ``Fruit`` models. + +And that's pretty much it. Keep on reading if you want to learn about the other +types of fields and widgets that are available as well as defining more complicated +lookups. diff --git a/dep/django-selectable/docs/releases.rst b/dep/django-selectable/docs/releases.rst new file mode 100644 index 00000000..925ebd66 --- /dev/null +++ b/dep/django-selectable/docs/releases.rst @@ -0,0 +1,268 @@ +Release Notes +================== + +v0.7.1 (Released TBD) +-------------------------------------- + +- Widget media references now include a version string for cache-busting when upgrading django-selectable. Thanks to Ustun Ozgur. + + +v0.7.0 (Released 2013-03-01) +-------------------------------------- + +This release features a large refactor of the JS plugin used by the widgets. While this +over makes the plugin more maintainable and allowed for some of the new features in this +release, it does introduce a few incompatible changes. For the most part places where you +might have previously used the ``autocomplete`` namespace/plugin, those references should +be updated to reference the ``djselectable`` plugin. + +This release also adds experimental support for Python 3.2+ to go along with Django's support in 1.5. +To use Python 3 with django-selectable you will need to use Django 1.5+. + +- Experimental Python 3.2+ support +- Improved the scope of ``prepareQuery`` and ``formatLabel`` options. Not fully backwards compatible. Thanks to Augusto Men. +- Allow passing the Python path string in place of the lookup class to the fields and widgets. Thanks to Michael Manfre. +- Allow passing JS plugin options through the widget ``attrs`` option. Thanks to Felipe Prenholato. +- Tests for compatibility with jQuery 1.6 through 1.9 and jQuery UI 1.8 through 1.10. +- Added notes on Bootstrap compatibility. +- Added compatibility with Grappelli in the admin. +- Added Spanish translation thanks to Manuel Alvarez. +- Added documentation notes on testing. + +Bug Fixes +_________________ + +- Fixed bug with matching hidden input when the name contains '_1'. Thanks to Augusto Men for the report and fix. +- Fixed bug where the enter button would open the combobox options rather than submit the form. Thanks to Felipe Prenholato for the report. +- Fixed bug with using ``allow_new=True`` creating items when no data was submitted. See #91. +- Fixed bug with widget ``has_changed`` when there is no initial data. See #92. + + +Backwards Incompatible Changes +________________________________ + +- The JS event namespace has changed from ``autocomplete`` to ``djselectable``. +- ``data('autocomplete')`` is no longer available on the widgets on the client-side. Use ``data('djselectable')`` instead. +- Combobox button was changed from a ``