Sunday, May 22, 2011

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


8 comments:

  1. Hello, thanks for releasing this plugin! I've been using it since v1.0, and have fixed some bugs. Now that v2.0 is out, I see you've addressed some of the same problems I have. Have you considered putting the code up on github? It'd be easy for me to share my changes with you, so we could reduce any duplicated effort.

    ReplyDelete
  2. Very nice Ombox box,

    one option I seem to mis is to have some grayed out value shown that states something like ' Please select ....' instead of just a white box.

    ReplyDelete
  3. Chris,

    do you happen to have a example how to respond to events? I am relativly new to jQuery, but I know how to bind to events and such, non of the events currently seem to work. I also looked at how jsFiddle does things, ands when applied to the combo's created there was no event fired.

    ReplyDelete
  4. Yes rvt. Sorry about the delay, I have been quite bussy the last weeks. I will put some examples today.

    Micah, I was thinking about github. I will do it when I find the time.

    ReplyDelete
  5. Chris,

    I fiddled this already:
    created = jQuery('#year${currentNode.UUID}').combo({
    'skin' : 'orange',
    'callbacks' : {
    'onChoose' : function(combo, text, value) {
    return true;
    }
    }
    });

    ReplyDelete
  6. rvt, your code seems to be fine. Make sure the jQuery object is a select element, or else you should use a 'selectId'

    ReplyDelete
  7. Chris hello,

    thanks for the release, i am using your plugin inside an enterprise GWT project, and came across the need for a feature - setSelected(index). for now i'm extending the lib myself, if it's simple and good enough i'll post it here. would be great for the next release though..

    thanks, Eliran

    ReplyDelete
  8. PS

    your choice to use private access modifiers (by setting them to local variables) for various fields (list, data) in the Combo object, really makes it hard to extend and / or modify your code (assuming we don't want to touch the original files, just extend for new API and the like).
    please consider a revision in that manner in the next release, it would be highly appreciated.

    thanks again, Eliran

    ReplyDelete