Datalist documentation

Options

Datalist's last two arguments are for optional parameters. The third argument overall is called "options" while the last argument is called "updateStyles".

Datalist example with all arguments set.

Option	Default	Description
`IE6Shim`	false	If true then a shim will be created so the dropdown will be properly displayed over SELECT elements in IE 6.
`activityIndicator`	true	The activity indicator kicks in when the datalist button is clicked. It is on by default because in some browsers rendering the list can take a second or two or three. Gives the user immediate feedback that something is happening.
`disabledMsgDuration`	2	This value deals with a popup message stating that the button has been disabled.
`disableButtonForIE`	[]	Internet Explorer is quite slow at rendering large datasets. This goes for all versions (6,7,and 8) as of this writing. However, IE 8 is quite a bit faster than the other two and you may just want o disable the button for IE 6 and 7. To do that you would add the following the options object `{ disableButtonForIE: [6,7] }`
`noButton`	false	A button is expected by default. If you want to just use the autocomplete functionality of Datalist than you set this value to "true". You may ask why wouldn't you use the default Autocompleter.Local class in this case. Datalist uses the json where Autocompleter.Local uses a simple array; therefore, you have a richer dataset to work with on the callback.
`dropLimit`	650	Here you can set a limit to how big a dataset you want to render when the button is clicked.
`update`	autocomplete_choices	Attribute "id" of the div tag in where datalist is rendered.
`button`	img tag next to input element	By default if you include a img tag next to the input or textarea element then the img tag will be the dropdown button. Rather, you may provide your own id attribute here of a HTML element that you want to serve as the dropdown button.
`disableButton`	false	True will disable the button as give the disable warning.
`callback`	"inside" value	The callback is a function that has two arguments ret and element. The ret (short for "returned") argument is a object that has two values: ret.inside and ret.outside. The refer to the json property that gets selected. For example let's say your selected item is such { NY: "New York" } by default the input value will be set to NY. However, you may send your own custom function here. Here is an example of a classic email textarea box in where you set multiple email addresses in the box in a fashion such as jack@email.com,jill@mail.com. $('email').datalist(contacts_json, { callback: function(ret,element){ var val = element.value; var all = val.split(','); all.pop(); element.value = all.size() > 0 ? all.join(',') + ',' + ret.inside : ret.inside; }, noButton: true,tokens: [','] },{ zIndex:30 });
`choices`	10	See here.
`partialSearch`	true	See here.
`fullSearch`	true	See here.
`partialChars`	true	See here.
`ignoreCase`	true	See here.
`token`	[]	See here.
`minChars`	2	See here.

updateStyles

The updateStyles argument is a way to directly control the "update" popup or dropdown. You can pass it any valid CSS style attribute such as zIndex,width,height,etc. There is also on more key attribute called "offsetLeft"

Style Description

Style	Description
`standard CSS style attribute`	Any CSS style attribute and value using syntax compatible with Prototype's setStyle method. Example: $('states').datalist(states_json,{ }, { background: 'gainsboro',zIndex:300,width:'100px' } ); The above example will render the following.
`offsetLeft`	With offsetLeft you can control the left-right positioning. $('states').datalist(states_json,{ }, { background: 'gainsboro',zIndex:300,width:'100px',offsetLeft:200 } ); The above example will render the view 200px to the left. You may also use negative numbers here to move the view to the right.

standard CSS style attribute

Any CSS style attribute and value using syntax compatible with Prototype's setStyle method. Example:

$('states').datalist(states_json,{ },
                    { background: 'gainsboro',zIndex:300,width:'100px' } );

The above example will render the following.

Controlling the look and feel using the updateStyles argument

offsetLeft

With offsetLeft you can control the left-right positioning.

$('states').datalist(states_json,{ },
                     { background: 'gainsboro',zIndex:300,width:'100px',offsetLeft:200 } );

The above example will render the view 200px to the left. You may also use negative numbers here to move the view to the right.

Controlling the look and feel using the updateStyles offsetLeft argument

Advanced topics

Stopping the annoying scrolling behavior when using the mouse wheel.

Datalist also has a feature that I enable for every one of my projects and it deals with handling the undesirable behaviour of the main web page continuing to scroll after you have reached to bottom of the Datalist view or popup. This behavior is hard to describe in text. Please check out the demo page where this is explained using a real example.

Adding to datalist on the fly

There is going to come a time where you want to add data dynamically to Datalist. Here is how.

    /*
        Best to make a states_dl a global variable so it can easily accessed.
    */
    states_dl = $('states').datalist(states_json);
    /*
        Next, set the internal data variable with the new information.
        I know the "array" variable seems inappropriate; however, we are
        reusing this var from the Autocompleter.Local class from Scriptaculous.
    */
    states_dl.options.array.set('PR','Puerto Rico');