Mark Lavin avatar Mark Lavin committed d068ff9

Additional field/widget docs. Closes #2.

Comments (0)

Files changed (2)

 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 fields (`AutoCompleteSelectField` and
+`AutoComboboxSelectField`) allow 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
+`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
 --------------------------------------
     
-Field tied to `AutoCompleteSelectWidget` to bind the selection to the form and  create new items, if allowed.
+Field tied to `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.
 
 
 AutoComboboxSelectField
 --------------------------------------
 
-Field tied to `AutoComboboxSelectWidget` to bind the selection to the form and create new items, if allowed.
+Field tied to `AutoComboboxSelectWidget` 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.
 
 
 AutoCompleteSelectMultipleField
 --------------------------------------
 
 Field tied to `AutoCompleteSelectMultipleWidget` to bind the selection to the form.
+This field cleans to a list of items. `AutoCompleteSelectMultipleField` does not
+allow for the creation of new items.
 
 
 AutoComboboxSelectMultipleField
 --------------------------------------
 
 Field tied to `AutoComboboxSelectMultipleWidget` to bind the selection to the form.
+This field cleans to a list of items. `AutoComboboxSelectMultipleField` does not 
+allow for the creation of new items.
 Widgets
 ==========
 
+Below are the custom widgets defined by Django-Selectable. All widgets take the 
+lookup class as the first required argument.
+
 
 AutoCompleteWidget
 --------------------------------------
 
-Basic widget for auto-completing text.
+Basic widget for auto-completing text. The widget returns the item value as defined
+by the lookup `get_item_value`. If the `allow_new` keyword argument is passed as
+true it will allow the user to type any text they wish.
 
 
 AutoComboboxWidget
 --------------------------------------
 
 Widget for selecting a value/id based on input text. Optionally allows selecting new items to be created.
+This widget should be used in conjunction with the `AutoCompleteSelectField` as it will
+return both the text entered by the user and the id (if an item was selected/matched).
 
 
 AutoComboboxSelectWidget
 AutoCompleteSelectMultipleWidget
 --------------------------------------
 
-Builds a list of selected items from auto-completion.
+Builds a list of selected items from auto-completion. This widget will return a list
+of item ids as defined by the lookup `get_item_id`. Using this widget with the
+`AutoCompleteSelectMultipleField` will clean the items to the item objects. This does
+not allow for creating new items. There is another optional keyword argument `postion`
+which can take four possible values: `bottom`, `bottom-inline`, `top` or `top-inline`.
+This determine the position of the deck list of currently selected items as well as
+whether this list is stacked or inline. The default is `bottom`.
 
 
 AutoComboboxSelectMultipleWidget
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.