Commits

Mark Lavin committed a599a6a

Document updates for latest functionality. Fixes #5.

Comments (0)

Files changed (6)

 See the example project for the full template example.
 
 
+.. _admin-basic-example:
+
 Basic Example
 --------------------------------------
 
 items you'll see these steps are not necessary.
 
 
+.. _admin-inline-example:
+
 Inline Example
 --------------------------------------
 
     admin    
     fields
     widgets
+    settings
     releases
 
 
     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
+    :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.
 
 .. py:method:: LookupBase.get_item_label(item)
 
     :param item: An item from the search results.
     :return: A dictionary of information for this item to be sent back to the client.
 
+.. py:method:: LookupBase.paginate_results(request, results, limit)
+
+    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 <https://docs.djangoproject.com/en/1.3/topics/pagination/>`_
+    for more info.
+
+    :param request: The current request object.
+    :param results: The set of all matched results.
+    :param limit: The number of results per page.
+    :return: The current `Page object <https://docs.djangoproject.com/en/1.3/topics/pagination/#page-objects>`_
+        of results.
+
 
 .. _ModelLookup:
 

docs/parameters.rst

 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
 --------------------------------------
 
             self.fields['autocomplete'].widget.update_query_parameters({'foo': 'bar'})
 
 
+.. _client-side-parameters:
+
 Adding Parameters on the Client Side
 --------------------------------------
 

docs/releases.rst

 Release Notes
 ==================
 
+v0.2.0
+--------------------------------------
+
+Features
+_________________
+
+- Additional documentation
+- :ref:`Positional configuration <AutoCompleteSelectMultipleWidget>` for multiple select fields/widgets
+- :ref:`Settings/configuration <SELECTABLE_MAX_LIMIT>` for limiting/paginating result sets
+- Compatibility and examples for :ref:`Admin inlines <admin-inline-example>`
+- JS updated for jQuery 1.6 compatibility
+- :ref:`JS hooks <client-side-parameters>` for updating query parameters
+
+
 v0.1.2
 --------------------------------------
 

docs/settings.rst

+Settings
+==================
+
+
+.. _SELECTABLE_MAX_LIMIT:
+
+SELECTABLE_MAX_LIMIT
+--------------------------------------
+
+.. versionadded:: 0.2
+
+This setting is used to limit the number of results returned by the auto-complete fields.
+Each field/widget can individually lower this maximum. The result sets will be
+paginated allowing the client to ask for more results. The limit is passed as a
+query parameter and validated against this value to ensure the client cannot manipulate
+the query string to retrive more values.
+
+You may disable this global maximum by setting
+
+.. code-block:: python
+
+    SELECTABLE_MAX_LIMIT = None
+
+Default: 25
+