util.js: Generating Lists

A common task with DWR is to fill a select list with options. A common example would be providing options based on an earlier input. For details, see the documentation for addOptions and removeAllOptions.

Hints

The best way to set the selected option is to follow a call to dwr.util.addOptions() with a call to dwr.util.setValue().

If you want to have an initial "Please select..." option then you can add it in directly using:

dwr.util.addOptions(id, ["Please select ..."]);

Followed by another call to dwr.util.addOptions() to include your real options data.

If you wish to maintain the selection of a list while you update it then you need to do something like this:

var sel = dwr.util.getValue(id);
dwr.util.removeAllOptions(id);
dwr.util.addOptions(id, ...);
dwr.util.setValue(id, sel);

Examples

Simple Array Example

DWR provides the dwr.util.addOptions() function to add to a select list. At it's most simple this takes 2 parameters, the first being the id of a select element to alter, and the second being an array of strings, each of which is to be used as an option.

DWR also provides the dwr.util.removeAllOptions() function which empties the select element. Separating the 2 functions means that we can better handle default values.

dwr.util.addOptions( "demo1", )

A list with id="demo1":

Simple Object Array Example

You may wish to fill a select list from an array of beans rather than an array of strings. In this case you need to specify the property from the bean that will be used for each value.

dwr.util.addOptions( "demo2", [ { name:'Africa', population:'800m' }, { name:'America', population:'900m' }, { name:'Asia', population:'3000m' }, { name:'Australasia', population:'31m' }, { name:'Europe', population:'700m' } ], )

A list with id="demo2":

Advanced Object Array Example

Alternatively you need to specify differing values (as are submitted by a form or read by dwr.util.getValue() and display texts. There is an optional 4th parameter that allows you to specify data to be used as the text separately from the value.

dwr.util.addOptions( "demo3", [ { name:'Africa', id:'AF' }, { name:'America', id:'AM' }, { name:'Asia', id:'AS' }, { name:'Australasia', id:'AU' }, { name:'Europe', id:'EU' } ], , )

A list with id="demo3":

Map Example

Sometimes you need fill a select list using a map, filling the values from the map keys and the text from the map values.

dwr.util.addOptions( "demo4", { AF:'Africa', AM:'America', AS:'Asia', AU:'Australasia', EU:'Europe' } )

A list with id="demo3":

You may wish to do it the other way around (i.e. have text from the keys and values from the map values). In DWR v2 dwr.util.addOptions() function will handle this alternative, with the addition of an extra parameter 'false'. However this syntax should be considered 'likely to be deprecated and replaced' in the future.

`<ul>` and `<ol>` list editing

Finally dwr.util.addOptions() is also able to alter <ul> and <ol> lists by adding <li> elements. In this mode the first parameter is the id of a <ul> or <ol> list to alter and the second is an array of strings, each of which is to be used as an option.

The dwr.util.removeAllOptions() function empties the lists of this type as well.

dwr.util.addOptions( "demo5", )

A <ul> list with id="demo5":

Formatted list editing

In addition to the action above, DWR can format elements as they are added to a list using a formatting function.

function formatter(data) { return "<em>" + data + "</em&lgt;"; }

dwr.util.addOptions( "demo6", , formatter, options)

Use { escapeHtml:false }

A <ul> list with id="demo6":