README for plugin_ajaxselect, a widget plugin for the web2py web development framework
version 0.8 (beta)
Developed by Ian W. Scott (monotasker), scottianw@gmail.com
Copyright Ian W. Scott, 2012.
Licensed under the GNU General Public License v. 3 (http://www.gnu.org/copyleft/gpl.html)

##Overview

This plugin creates a select widget wrapped that can be refreshed via ajax without resetting the entire form. It also provides an "add new" button that allows users to add a new item to the table that populates the select widget via ajax. The widget is then automatically refreshed via ajax so that the new item is visible as a select option and can be chosen. All of this happens without a page or form refresh so that data entered in other fields is not lost or submitted.

##Dependencies

This plugin relies on the jquery-ui library to generate the dialog used to add new items to the select list. If you would like to use your own dialog script (or a different ui library), simply remove the offending code in static/plugin_ajaxselect/plugin_ajaxselect.js and replace it with your favorite dialog script.

##Installation
    1. download the plugin file;
    2. In the web2py online ide (design view for your app) scroll to the bottom section labeled "Plugins"; 
    3. At the bottom of that section is a widget to "upload plugin file". Click "Browse".
    4. In the file selection window that opens, navigate to the downloaded plugin file, select it, and 
        click "open". The file selection window should close.
    5. Click the "upload" button.
The plugin should now be installed and ready to use.

##Usage
In a web2py model file, import this class and then apply it as the widget-factory for one or more db fields. To do this for a field named 'author' from a table named 'notes' you would add this line somewhere in the model file:

    db.notes.author.widget = lambda field, value: AjaxSelect(field, value, 'authors', {optional argument}).widget()

Note that the third argument passed to AjaxSelect should be the name of the able *referenced by the current field*. In this example, the field 'author' references the table 'authors'. So the third argument in this case is 'authors'.

###Optional arguments:

**refresher** (True/False; defaults to True): If True, this provides a button to manually refresh the select
widget via ajax. If set to False, the widget is still refreshed via ajax (automatically), but the button to do it manually is removed.

###Future functionality (not yet implemented):

I am planning to add the following further optional arguments:

**adder** (True/False; defaults to True): If True, a button is provided to add a new record to the linked table that populates the select widget. (At present this is always provided and cannot be turned off.)

**restricted** ({fieldname}): adds a dynamic constraint on the records displayed in the select widget. When the specified form field (within the same form) has its value changed, this select will be refreshed and its displayed records filtered accordingly. Note that this is only useful if {fieldname} references values shared with the linked table.

**restrictor** ({fieldname}): makes this select widget acts as a constraint on the content of another select widget in the same table. When the value of this select is changed, the available values in the {fieldname} widget will be filtered and that widget updated via ajax.