View
 

ListBuilder

Page history last edited by Todd Parker 11 mos ago

 

type: widget

release: 0.0

status: in planning

documentation: N/A

demo: N/A

 


 

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 (default), it needs the Autocomplete as a dependency.

To disable: .listbilder({ autocomplete: false })

 

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/

 

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:

 

(Detailed descrition of how the script will be structured: defaults, options, architecture, extensibility, etc.)

 


 

4 - Markup & Style:

 

     4.1 Initial markup examples

 

     (Pre-enhanced HTML markup structure that will be transformed into the final widget. There may be multiple possible HTML markup options per widget: for example, for a slider, radiobuttons, inputs or selects could all be used. )

 

     4.2 Recommended transformed HTML markup

 

     (The HTML markup structure and classes that will be used by the scripts in the enhanced version) 

 

     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

 

    (Description of the CSS classes to be used for all states, how custom theming and Themeroller support will work.) 

 


 

5 - Latest version of plugin:

 

(Link to the latest version in the jQuery UI trunk here)

 


 

6 - Open issues being discussed

 

(Use this area to place things that we're hashing out like featuresand options we're not sure we should include, questions about how this fits into UI and relates to other widgets and utilities, known problems, whether features should be broken across multiple releases, etc.)

 


 

 

 

 

Comments (27)

profile picture

Mark Gibson said

at 3:50 am on Mar 13, 2009

Ah, if I only I found this last week!
I've also developed a widget for this purpose, please find a demo here:

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

It is built as a jQuery-UI widget, and is completely autocompleter agnostic - an INPUT element is exposed to which you can attach and configure your preferred autocomplete plugin. The demo uses Jörn's jquery.autocomplete.js with a small patch to allow filtering of results.
It enhances a plain text input - as demonstrated.
Keyboard navigation is supported.
It's still in early stages so needs lots of cross-browser testing.
It should be possible to use UI sortable to add re-ordering ability if required - I'll try to add this to the demo at some point.

profile picture

Yanick said

at 11:43 am on Dec 7, 2009

Error 404

profile picture

Almog Baku said

at 11:08 am on Apr 1, 2009

Some useful feature is that "item" can be removed by clicking on "backspace" or "delete" on the keyboard(as Facebook).

profile picture

Mark Gibson said

at 12:15 pm on Dec 3, 2009

The demo link for tokenlist above is dead. At present the code lives in github: http://github.com/jollytoad/jquery.ui-tokenlist
I've updated the demo code (in the git repo) to work with the new UI autocomplete widget.
I'll probably be overhauling my tokenlist widget in the next couple of weeks, to integrate better with the new autocomplete.
Any ideas are welcome. May be it's time to turn it into the UI ListBuilder widget.

profile picture

Wichert Akkerman said

at 4:45 am on Dec 18, 2009

I tried the tokenlist plugin, but it failed to autocomplete anything but the first item. Also as Almog mentioned it should be possible to remove items again using the backspace key. It looks like a promising plugin though!

profile picture

Michael Lang said

at 2:54 pm on Jun 20, 2010

I've created a prototype specifically to address the requirements on this wiki. It is not 100% feature complete, but I am willing to work with this community to include it as part of the licensed download of jqueryUI whenever you feel it is ready. You can see it in action here:
http://nexul.com/prototypes/tokenlist/demo.html

I took the liberty of registering it in namespace "ui.listbuilder".

here is the header license:
/*
* jQuery UI Listbuilder
* - written for jQuery UI 1.8 using the widget factory
*
* Copyright (c) 2010 Michael Lang
* Dual licensed under the MIT (MIT-LICENSE.txt)
* and GPL (GPL-LICENSE.txt) licenses.
*
* nexul.com/prototypes/tokenlist/demo.html
*/

profile picture

Michael Lang said

at 3:04 pm on Jun 20, 2010

Essentially this implements design F6 in the docs above.

The html is built by creating a div placed immediately after the enhanced input (textarea or input type=text only). That div is given the width of the replaced textbox, and the min-height of the enhanced textbox. Inside it builds a list. that list contains a new input box (not textarea). upon instantiation any delimited values are used to create the starting list of items. Any addition or removal of list items updates the enhanced (and hidden) textbox. Clicking anywhere in the root div not directly on a list item highlights the item entry textbox. If autocomplete is enabled a tip div appears below the textbox telling the user to start typing to receive suggestions. The arrow keys move around between the items. delete and backspace delete an item and highlight the next appropriate item or gives focus to the input box as appropriate.

The option not yet implemented is the prevention of duplicates.

Autocomplete utilizes the ui.autocomplete in jquery ui 1.8+. The autocomplete option defaults to false meaning that one is not instantiated. Otherwise you can pass in any valid options that work for the jquery ui autocomplete, as they are passed directly to instantiate an autocomplete on the child entry textbox.

profile picture

Michael Lang said

at 3:10 pm on Jun 20, 2010

Oh, and re-ordering is not implemented. But that should be as easy as making the list sortable, and then on sort complete updating the enhanced textbox from the list again.

profile picture

Michael Lang said

at 8:40 pm on Jul 6, 2010

I have implemented the duplicates option (default of not allowed). I've also added and implemented the sorting option (default off). Both are boolean options only. The sorting option when enabled only allows all but the last item in the list, which contains the text imput to be sorted.

I've also fixed a bug: If you had partially entered a value but not yet hit enter to add it to the list of values, whatever was still in the edit box was not being synched with the underlying original textbox. The fix was to on listblur take any text value in the editor and make it a list item.

profile picture

Michael Lang said

at 8:53 pm on Jul 6, 2010

I just noticed on sort complete the underlying textbox item order is not updated. I'll fix that in the next few days.

profile picture

Todd Parker said

at 8:05 am on Jul 8, 2010

Hi Michael - Looks like you're making good progress on this widget and the progressive enhancement looks good. I'm hoping others on the team can weigh in on the code, API and requirements but here are a few off the cuff comments on the design:

- The text input is styled like a button with a very big message below and I think it would be cleaner if the input look pretty much invisible (no border or bg) because this whole widget is supposed to look like a big text input with each word/entity visually grouped so the input just looks like the blinking text cursor after the entities - the design mockups and typical implementations like Outlook are all good examples.
- On the sorting example, the hover state makes the text go to bold and causes re-wrapping and jumpiness. I'd leave font weight alone and just toggle ui-state-default and -hover
- Hovering over the "x" icon flips the icon and is distracting. I'd rather you just kept with a single icon for these states and if you need a shift set the normal state to 60-70% opacity then go to full opacity on hover. Icon also needs a title attribute.
- I'm not seeing an autocomplete menu at all on Chrome/Mac

profile picture

Michael Lang said

at 9:48 am on Jul 8, 2010

Your point on the text input makes sense. I'll remove the class. I'm currently using it as a marker in some places to see if it is the active item in the list, but I can work around that.

Currently whichever list item has focus gets the class ui-state-focus. Should the replacement class be ui-state-active, ui-state-hover, or ui-state-highlight for the active list item. A list item can be made the active one via hovering or via keyboard navigation. Or should I use ui-state-hover if the user hovered over the item, and ui-state-active when the use keyboard navigates to the item? I'll experiment with the different classes.

I suppose for now I'll make the title on the close icon say "remove". It may make sense to make that title an option. We should consider if the icons to use for normal and hover state should be options. Maybe similar to how the primary and secondary icon are specified for jQueryUI button. I don't think I should be setting a specific css property for opacity of the icon on hover. The class applied on hover should handle that. I think the key is in selecting the appropriate classes for each state.

Does the autocomplete standalone demo (in jQueryUI docs) work for you on Chrome/Mac? Which input are you testing? The first one with numbers in it should always show an autocomplete if you type "o" or any letter contained in the spelled out numbers "one" through "ten". The last autocomplete that contains "everyone" only shows the menu if three or more characters are entered, and those letters match a name of a user on nexul.com. Right now since it is in private beta that list is small. Try entering "lan" for my last name. "Eve" will not show "everyone" an an autocomplete value because you are not logged in to nexul and will not get back a list of group names.

profile picture

Todd Parker said

at 10:09 am on Jul 8, 2010

Using focus is the right thing to do for keyboard navigation and hover is best for mouse.

For the icons, since they are sitting inside a button that will get the hover/focus state, placing your cursor over the icon won't trigger any visual shift (you're already hovering/focusing on it's parent). It might be ok to get away with no shift, but if you need one using opacity may be a good trick because it doesn't mess with the theme colors & images. I think switching the icon is too much and the overhead of specifying that for each state adds unnecessary complexity to the plugin. Like you said, try a few things and see what feels best.

I just tried the auto-complete again and it's working on Chrome. Maybe I had a cached script.

profile picture

Michael Lang said

at 11:54 am on Jul 8, 2010

ui-state-focus, ui-state-active, and ui-state-hover all increase the font size. Only ui-state-highlight does not increase the font size (I am using the redmond theme, I'm not sure if all do this). Should with stick with ui-state-focus and ui-state-hover for semantic reasons?

profile picture

Michael Lang said

at 3:19 pm on Jul 8, 2010

The outline you see on the textbox is a Chrome only issue. Chrome likes to highlight inputs in yellow. I'm not sure what to do about that issue. Apparently lots of people are mad at google for adding this style to inputs.

http://code.google.com/p/chromium/issues/detail?id=1334

If this is to fixed at all, I think the themeroller theme is the appropriate spot. Or just wait for google to come to their senses and abide by standards.

profile picture

Todd Parker said

at 8:12 am on Jul 9, 2010

Michael - when you say the ui-state- classes all increase font size, do you mean font weight? I think the issue is that in the global font settings (which are applied via the ui-widget class) we let people define whether the font weight is bold or roman. if bold is chosen it's applied selectively to buttons and other elements but not all body copy because it would look bad to have all your body text bold. So when you use a theme like Redmond that uses bold, the buttons will jump if you have an element with ui-widget (global body copy) and then add ui-state-hover because hover will flip to bold. I'd recommend adding ui-state-default to each of the button-y word entities and this will fix any jumpiness.

A big help would be if you added the theme switcher to your demo page to make it easy to test and debug your widget against all the themes. We like to include this on on dev demo pages:
http://jqueryui.com/docs/Theming/ThemeSwitcher

profile picture

Michael Lang said

at 7:44 am on Jul 10, 2010

Thanks for the link on themeswitcher. I knew about the bookmarklet, but I didn't know this was available. I've added the themeswitcher.

I did mean font-weight. I updated the classes to look better on all themes. Changes:
1) the outer div now gets class ui-state-default instead of ui-widget.
2) The outer div now gets class ui-state-selected instead of ui-state-default when it has focus.
3) The suggester (for autocomplete listbuilders) now gets class ui-state-active instead of ui-state-default
4) I defined the input class 'ui-listbuilder-input' in the page and it removes the border, outline, and makes the background color transparent. This way the background of the parent div shows through.

profile picture

Michael Lang said

at 7:54 am on Jul 10, 2010

By the way on 'focus' of the listbuilder I applied 'ui-state-selected' instead of 'ui-state-focus' because on dark color themes like 'trontastic' and 'dark hive' the editor had little to no contrast between the text being typed and the background of the textbox. With the ui-state-selected class their was enough contrast to enter text.

profile picture

Michael Lang said

at 9:01 pm on Jul 6, 2010

I still need to implement a menu for each list item (visual design F7). My current thought is just to make itemSelected an event. The event would include the relevant event and the list item in the parameter list. The relevant event could either be a keypress (left, up, right, down, delete, backspace), or a click. On backspace or delete, the event would include the item gaining focus after the previous item was deleted. That would keep the plugin design minimal, while also giving much more flexibility to the user to either show a menu relative to the list item token, or anything else they can imagine.

Does anyone else have another preference for how the F7 visual design should be supported or implemented?

profile picture

Michael Lang said

at 8:38 pm on Jul 7, 2010

fixed: sortable now updates linked textbox on sort complete

fixed: refined keyboard navigation scripts, but one quirk remains in IE7. The 'left' arrow does not work in IE 7 (and presumably IE6) when there is text in the enhanced editor. In that case the user can use the 'up' arrow key instead. This is because IE7 and older does not support the selectionStart property of a text input. This is not a problem in IE8, firefox, or chrome. backspace was also updated so that it only deletes the last list item if the cursor is on the leftmost character in the enhanced textbox when it is pressed.

Feature: I added the onSelect event. It fires when the cursor hovers over an item, or click on an item. The type of select is a parameter to the event. The demo shows a menu only when onSelect is fired from a click. It logs both the 'mouseenter' onSelect and the 'click' onSelect in a visible log area on the page.

The demo references menu version 1.9 milestone 2 only so the menu works. If you don't use the menu as on the demo page the script works fine in jQuery UI 1.8. The demo page shows all the tested browsers. If anyone tests it in other browsers, please let me know the result so I can update the demo page stats.

I believe all features mentioned on this wiki page so far have been implemented per spec (visual design F6 and F7). Please try it out and see if you have any suggestions for improvement.

profile picture

aurelien gerits said

at 2:50 pm on Jul 8, 2010

How not to add a tag if it does not exist in autocomplete?

profile picture

Michael Lang said

at 3:31 pm on Jul 8, 2010

I presume you mean, "how do you add a tag that is not defined in the autocomplete?"

Just type and hit enter or tab when done. The browsers I've tested so far do not enforce selection of a predefined value. If your experience is different, then what browser are you using and on what OS?

profile picture

aurelien gerits said

at 1:07 am on Jul 9, 2010

Hello,
is the opposite, I would not add tags is not defined in autocomplete
Sorry for my english :)

profile picture

Michael Lang said

at 10:35 am on Jul 9, 2010

The listbuilder delegates all autocomplete behavior to the autocomplete plugin. So you can restrict values if you like just by passing in the correct parameters. See here how you can specify any autocomplete supported option:
$('#test1').listbuilder({
autocomplete:{
source:data,
//... add your other autocomplete options here ...
},
sortable:false,duplicates:false
});

My example does not explicitly answer your question. Instead, look at this guide and see the note on how to implement 'mustMatch' on the new autocomplete widget.
http://learningjquery.com/2010/06/autocomplete-migration-guide

If you have any further problems specifically with the autocomplete widget you'll get better answers from the 'using jQueryUI" forum:
http://forum.jquery.com/using-jquery-ui

profile picture

aurelien gerits said

at 1:48 am on Jul 14, 2010

Thank you very much, I'll test

You don't have permission to comment on this page.