type: widget

release: 0.0

status: in planning

documentation: N/A

demo: See demos folder in GitHub source download

1 - Description:

This widget provides a well-constrained way to let users build a list of items. Common applications include the Facebook-style list builder for message recipients (F6) which provides a textarea with an auto-complete function and the ability to re-order and delete recipients. The Apple Mail style builder (F7) adds an action menu next for each item that can be used to offering multiple actions. This should support re-ordering via drag and drop, plus keyboard shortcuts to select and delete items.

The autocompletion is optional, when enabled, it needs the Autocomplete as a dependency.

The default is to be disabled: .listbilder({ autocomplete: false })

A fully working widget is now available on github as a standalone repository. The source download includes a demos folder showing 3 different use cases.

https://github.com/michael-lang/jquery-ui-listbuilder

This widget is available via NuGet. Instructions for installation:

https://www.nuget.org/packages/jquery-ui-listbuilder/

Alternate reference jQuery plug-ins:

http://plugins.jquery.com/project/facelist

http://www.emposha.com/javascript/jquerymultiselect.html

http://devthought.com/wp-content/projects/jquery/textboxlist/Demo/

http://tagedit.webwork-albrecht.de/index.html

Mark Gibson's plugin, built on jQuery UI. Can be used with Jorn's autocomplete (or others):

http://test3.internal.adaptavist.net/~mgibson/tokenlist/demo.html

Filament Group has a draft of the Facebook style interaction modeled here that uses progressive enhancement techniques on a textarea to ake it easy to get and set values:

<link...>

2 - Visual Design:

3 - Functional Specifications/Requirements:

Options:

delimiter (string, default: ",")

A text delimiter used to parse the original values at creation time and then to write list items back into the original text input each time an item is added, removed, or sorted to a new position.

duplicates (boolean, default: false)

Specifies if more than one item of the same text value can be added.

sortable (boolean, default: false)

Specifies if the list of items can be sorted. Details of the sort are not customizable.

autocomplete (boolean, object, default: false)

If false then the list builder does not auto-suggest value from an autocomplete
To enable autocomplete pass in the options to be passed into the autocomplete exactly as normally supported by the autocomplete widget.
If the select event is not specified on the autocomplete options then a default implementation is added to put the selected value in the list builder and then clears the token editor
If the select event is specified on the autocomplete options, then that method must use the add method of listbuilder to put the selected value into the list.

Methods:

add (string)

Adds a new item to the list and to the underlying linked text input or textarea

remove (list item element)

Removes the specified list item from the list and then updates the underlying text input or text area from remaining items.

editItem (list item element)

Takes the text of the list item on puts it in the editable area, and then removes that list item from the list. When done editing the newly changed value becomes a new list item.

selectedItem

Getter for the currently selected list item

listblur

Removes focus from this input element. Blurs the text input or text area and removes any selected styles from list items.

Events:

select

Triggered when the user clicks on one of the items in the list (sets originalEvent to 'click')
Triggered when the user hovers of one of the items in the list (sets orginalEvent to 'mouseenter')
Triggered when the user uses arrow keys to navigate to an item in the list (sets originalEvent to ?) (not yet implemented)
ui.item refers to the selected list item

Keyboard Navigation:

up / left

navigates to previous list item
if cursor is in token editor and there is a text value do not change selected item. leave focus in the textbox
if cursor is in token editor and there is no text value, then select the last item.

right / down

navigates to next list item
if cursor is in the token editor do not navigate

delete

deletes current list item and highlights next item (or last item if last was deleted)
if cursor is in the token editor do not navigate. Instead edit text as normal.

backspace

deletes current list item and highlights previous item (or first item if first was deleted)
if cursor is in the token editor do not navigate. Instead edit text as normal.

any other character

put the typed value in the token editor and deselect any selected item. Show autocomplete if appropriate.

If autocomplete is visible disable keyboard navigation of list items since it should then navigate the autocomplete list

4 - Markup & Style:

4.1 Initial markup examples

Most common usage:

	<input type="text" value="one, two, four"/>

Alternate 1 defines menu for each list builder item

	<input id="test2" type="text" value="six, three, zero" class="test" style="width:200px"/>
	<ul id="test2-menu">
		<li><a href="/#">Edit item</a></li>
		<li><a href="/#">Copy</a></li>

		<li><a href="/#">Remove</a></li>
	</ul>

     Alternate 2 uses a text area instead of a text input

	<textarea>one, two</textarea>

4.2 Recommended transformed HTML markup

First, hide the orignal input. Then immediately after add a div that will appear on top of the original input location. The script should size the div to match the original size of the input.

</li>

</li>

</li>

<div class="ui-state-active" style="display: none;">Type to receive suggestions</div>

</li>

</ul>

</div>

4.3 Accessibility recommendation

(Detailed recommendations for ARIA, HTML markup, CSS and javascript that will contribute to universal access and full section 508 accessibility for screen readers, mobile devices and any other devices)

4.4 CSS & Theme

The newly created wrapping div will be given class ui-listbuilder. Each item will be given class ui-listbuilder-item. The input to which the user can enter a new list item be given class ui-listbuilder-input, and any additional classes the optional autocomplete plugin applies.

Suggested new css styles and their values as follows:

.ui-listbuilder {

background-color:White;

border:1px solid #7F9DB9;

}

.ui-listbuilder-items {

margin:0;

overflow:hidden;

padding:3px 4px 0;

}

.ui-listbuilder-item {

border:1px solid #444444;

float:left;

height:20px;

list-style-type:none;

margin:2px;

padding:1px 18px 1px 3px;

position:relative;

}

.ui-listbuilder-item-input {

border:0 none;

}

.ui-listbuilder-input {

border:0 none;

}

5 - Latest version of plugin:

(Link to the latest version in the jQuery UI trunk here - not in Git yet)

http://www.nexul.com/prototypes/tokenlist/src/jquery-ui-listbuilder.js

6 - Open issues being discussed

1) close icon needs title attribute

2) should close icon class be configurable for normal and hover state?
   icons:[normal:'ui-icon-circle-close', hover:'ui-close-icon']

3) options for localization of text
   lang:{closeText:'close', suggestText:'Type to receive suggestions'}

4) how should additional plugins be applied such as watermarks, mask input, or validators?
   a) should the input for entry of a new list item be exposed as a property so that other plugins can use that
   b) should others be applied first and then copied/moved to the new token input
   c) some plugins like validators may need to remain applied to original form input (like required input)
   d) some plugins like masked input or watermark may need to be applied to token editor input.

5) sorting some items to some locations can be difficult. Maybe larger drop targets are needed?

6) Usability study shows user want to see a list without having to type, while advanced users still want to type in a new value occasionally.
   a) should the list options (autocomplete) automatically show on focus if minLength of autocomplete is zero?
   b) should there be a way to instead add a button to show some predefined values (when minLength is zero) Is that a typical use case of extending the autocomplete (combobox example) or something common enough to build into the list builder?

7) LI's should get a tab index of -1 for easy leverage by screen readers

8) bug: If you get the autocomplete to show and then arrow down a few then back up, the selection of previously entered items starts highlighting and moving. Then if you hit delete (to remove text in the input field if you typed some, it starts deleting previous items). Probably need to only have the up/down "navigate" when there is not text in the input, or something.

9) how do we activate an attached menu using keyboard only. The current demo only shows the attached menu on click. There is currently no event for item selected via keyboard navigation. maybe adding that would solve the problem.

ListBuilder

1 - Description:

2 - Visual Design:

3 - Functional Specifications/Requirements:

Options:

Methods:

Events:

Keyboard Navigation:

4 - Markup & Style:

4.1 Initial markup examples

Most common usage:

Alternate 1 defines menu for each list builder item

4.2 Recommended transformed HTML markup

4.3 Accessibility recommendation

4.4 CSS & Theme

5 - Latest version of plugin:

6 - Open issues being discussed