Commits

Mark Lavin committed 08be242

Added overview and quickstart info.

Comments (0)

Files changed (4)

 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::
+
+    .. code-block::
+
+        urlpatterns = patterns('',
+            # Other patterns go here
+            (r'^selectable/', include('selectable.urls')),
+        )
+
 .. toctree::
     :maxdepth: 2
 
+    overview
+    quick-start
     fields
     widgets
 

docs/overview.rst

+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 <http://jqueryui.com/demos/autocomplete/>`_ 
+versus the now deprecated `bassistance version <http://bassistance.de/jquery-plugins/jquery-plugin-autocomplete/>`_.
+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 <http://code.google.com/p/django-ajax-selects/>`_. To see some of the
+other Django apps for handling auto-completion see `Django-Packages <http://djangopackages.com/grids/g/auto-complete/>`_.
+

docs/quick-start.rst

+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 <http://docs.djangoproject.com/en/1.2/topics/db/models/>`_
+and `using forms <http://docs.djangoproject.com/en/1.2/topics/forms/>`_.
+
+
+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
+        :lines: 1-10
+
+In a `lookups.py` we will define our lookup:
+
+    .. literalinclude:: ../example/core/lookups.py
+        :lines: 1-10
+
+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 <http://docs.djangoproject.com/en/1.2/ref/models/querysets/#field-lookups>`_
+for making queries in Django.
+
+Below this definition we will register our lookup class.
+
+    .. literalinclude:: ../example/core/lookups.py
+        :lines: 12
+
+
+Defining Forms
+--------------------------------
+
+Now that we have a working lookup we will define a form which uses it:
+
+    .. literalinclude:: ../example/core/forms.py
+        :lines: 1-13
+
+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.