CCombo v2.0

Hi everyone. I am glad to say I have finished the second version of ccombo. I have made some modifications and optimizations in the code and fixed many bugs. I also decided to write a better documentation. All the examples are now hosted in jsFiddle where one can experiment too. One thing i'd like to point is that i decided to change the type of ccombo from "plugin" to "component". This is because i think ccombo is a piece of code with its own features and functionality, using jQuery to achieve them.
Changelog:

• Added callbacks, where you can also control some of the functionality of the component.
• OptGroups now supported.
• Added methods, size(), setItem(item), contains(item).
• Bug fixes, optimizations.

Installation and Usage

Download v2.0 (30kb)
Tested in Explorer 8-9, Firefox 3.6, Chrome, 9+, Opera 10+
Like v1.0 you will need the jQuery library, the basic component file jquery.combo.js, the style file style.css, and Ben Alman's plugin, (outside-events) which is included in the zip.

Usage notes

There is a global storage object (Combos) for all ccombo objects in a page. It has functions for getting, adding and removing objects. Objects are stored with a unique id. Before adding an object there are three checks that are made to ensure the uniqness of its' id.

• If the selected item (input or div) has an id.
• If a parameter id is specified.
• If nothing of the above, then an id is dynamically created.

If an object with tha same id exists then the creation process fails.
Unlike usual jQuery plugins this component does not maintains chainability. It returns an array containing all the objects that were created in the last call.

[New] There seems to be a confusion about the way ccombo works. Well I agree, it is a little different from an ordinary list, and I haven't made it clear from the beggining. There are two states in the ccombo. The first is the search state, and the second the list state. In the search state which is initialized after pressing the enter inside the input area ( if editable ) or clicking the input ( if not editable), the list shows those items that contain the text we entered in the input. The list state show all of the items even if we have choosen one before. This is done by clicking the arrow icon next to the input.

Options

• max_height
  Type: numeric
  Default value: 10
  The max number of elements to be shown in the list. In a simple list if this number is less than the elements in the list then it is automatically adjusted.
  
• page_step
  Type: numeric
  Default value: 10
  How many elements to scroll down/up when you press the psageDown/pageUp.
  
• select_categories
  Type: boolean
  Default value: true
  In a tree list you can define whether parent elements can be choosable. Parent elements are thoose with subelments. If set to false the default action is to open the sublist. If data is taken from an optgroup then the default value is false.
  
• icons
  Type: object
  Default value: {collpase:"lib/CollapseTree.gif", expand:"lib/ExpandTree.gif"}
  You can define the icons for expanding/collapsing the tree nodes. It is recommended that the size is 10px * 10px.
  
• skin
  Type: string
  Default value: default
  There are three skin yet available. default, green, orange. If you want you can create you own skin based from the images in the themes folder. Just create a folder with the desired name and put in there the images you created.
  
• auto_close
  Type: boolean
  Default value: true
  If set to false, the list will close only if you click the list icon.
  
• editable
  Type: boolean
  Default value: false
  You can make your list editable to enable the user to insert his own text. In the examples it is explained how to get the values from the list.
  
• width
  Type: numeric
  Default value: 150
  The width of the list in pixels including the icon and the borders.
  
• id
  Type: string
  Default value: automatically generated
  A unique id for the list
• selectId
  Type: string
  Default value: not set
  The id of a select element from which the data will be taken. It may contain optgroups.
  
• url
  Type: boolean
  Default value: not set
  A url from where data will be taken via ajax. They can be either in xml or json format.
  
• dataType
  Type: boolean
  Default value: not set
  Define what format will the ajax request return.
  

Events

• onOpenList( combo )
  combo [object]: the combo object
  Called before opening the list.
  
• afterOpenList( combo )
  combo [object]: the combo object
  Called after opening the list
  
• onCloseList( combo )
  combo [object]: the combo object
  Called before closing the list
  
• onOpenLevel( combo, index, node )
  combo [object]: the combo object
  index [number]: the index of the item in the list
  node [dom element]: the li element
  Called before opening a sub list
  
• afterOpenLevel( combo, index, node )
  combo [object]: the combo object
  index [number]: the index of the item in the list
  node [dom element]: the li element
  Called after opening a sub list
  
• onCloseLevel( combo, level, node )
  combo [object]: the combo object
  level [number]: the level of the item
  node [dom element]: the li element
  Called after closing the list
  
• onChoose( combo, text, value )
  combo [object]: the combo object
  text [string]: the text of the selected item
  value [string]: the underlying value of the selected item
  Called before writing a value to the input.
  
• afterChoose( combo, text, value )
  combo [object]: the combo object
  text [string]: the text of the selected item
  value [string]: the underlying value of the selected item
  Called after writing the value to the input
  
• onFocus( combo )
  combo [object]: the combo object
  Called when the input has focus
  
• onBlur()
  Called when the list looses focus
  

Component methods

• size()
  Get the number of items in the list.
• contains( item )
  item [string]: the item to search for
  Check whether the item is in the list. Returns the position of the first matched item, -1 otherwise.
• setItem( item )
  item [string]: the item to set
  Sets the current selected item, if there is any that matches the parameter. Returns false if there is not any match.

Examples

Basic usage: replace select tag. Try it

Using an external select and a div as a wrapper. Try it

Tree format with data from select with optgroup. Try it

Create an editable combo. Try it

Experiment with using different ids. Try it

CCombo themes. Try it

Allow parent selection in a tree format combo. Try it

New methods added. size, contains, setItem. Try it

[New] Events in ccombo. Try it