Commits

Mark Lavin  committed 08be242

Added overview and quickstart info.

  • Participants
  • Parent commits d48622c

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')),
+        )
+

File docs/index.rst

 .. toctree::
     :maxdepth: 2
 
+    overview
+    quick-start
     fields
     widgets
 

File 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/>`_.
+

File 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.