This tool is an object that you instantiate with the new keyword, it is not a wrapper or a plug-in for jQuery, it simply runs on that framework, using as much of the internal logic as possible. Thanks to the folks who wrote Visual jQuery 1.2, one of the best resources I found.

There is a lot to cover here, but I plan on starting simple, for those who want to just try it out and get running. When you create your first SBF, you'll get a select box that is skinnable, siftable, polymorphous, fast, browser-compatible, sortable, and resizable. They have the ability to show you counts, selections, images, numbers, urls, states in the form of a heatmap with filter buttons. They have an eraser function, a keystroke find function, spreadsheet style selection capability. They can find divs in the DOM and "absorb them" into the select box, use choices right from the JSON definition, and can easily take and allow removal of choices after the object has been returned. Using this for a "swap selection" box is a piece of cake.

It is flexible enough to go beyond the average select box and the limits are your imagination. What else can you use it for?

• You will see the same attributes for each choice (in the next section) in array form. Here, they are in DOM attribute form. The id is the only thing that you absolutely must have for uniqueness.

• Here, and throughout this tutorial, the order of the arguments does not matter, but the ordering of the attributes of the choices when specifying them in the JSON definition is absolutely critical. When you are pulling them from the DOM, its not at all critical, since the code creates choices for you.
• The 4th argument "selected" is great for applications that persist information. The list will programmatically load and run a trigger event for you. There is a tremendous amount of consideration behind these little select boxes that will be exposed to you as you read on.
• The choices each have, in order from left to right, are id, a title, a display name, whether it is selected or not by default, the number of its state (whether you are using states or not, leave it 0 if not), and an array of details that allow sift to work, if your using sift (if not, leave it as an empty array []).
• Note: how I have set the Boolean on "serval" to true, and this tells the select box to select it by default.
• Note: since I have not defined a "type", the code will assume you want a select-one.

If you click to open the dropdowns anywhere in this tutorial, you will notice it pushes everything out of its way. That is because it is relatively positioned. Later on in this tutorial, I'll show you how to make these absolutely positioned, and yes it takes a very small bit of work.

• Sift shows as input field in your toggle bar, and that's all there is to it on the surface. What's going on behind the scenes is fairly complex, but I'll boil it down for you.
• Even though sift automatically grabs 3 siftable parameters for you, you can extend this as far as you want, buy specifying an optional details array, which you will see in the code below as the array with "spots", "ears" and such. If you add these, sift will append these internally to each item and allow sifting based on those attributes.
• Try it out. In the box on the left, type J and jaguar will appear. The reason the others hid is because the character J was not found in any string in any detail associated with those choices. Now hit the clear button and try "ar". Three choices should appear.
• Now try sifting on "claws". Even by the time you've finished typing, the sift has returned. This is because "cl" matches claws.
• If for some reason, you get a result that doesn't match what you typed in, be aware: you must have a detail setting for that option that matches the search, or the id, state or display name match it.
• You can increase the sift by using the AND operator which is typed as a plus sign "+". If you typed "cla+j", then only Jaguar would appear, because only jaguar has both J and CLA in any of its details. This feature reduces results.
• The OR operator is typed as a pipe symbol "|". If you typed "cl|j" Then you would get both Jaguar and Lion, because only those two have either J or CL in any of its details. This feature expands your results.
• Keep what is in the box but then type NOT symbol, which is an exclamation point "!". Not simply reverses the search and returns "everything else".
• To keep users aware of this, I supplied a default "title" attribute on the box, which you can use, or change. It tells the user how to search.
• Thats it! Its up to you to create data arrays that are meaningful for the attributes you specify.

• The states correspond to a numbering scheme, which the code automatically finds for you. You don't have to tell it how many states there are, it will discover the true unique number in case you want to show buttons corresponding to the states.
• Color these anyway you want, its up to you to use this as you see fit.

• Up to 4 or 5 can easily fit, and beyond that, its up to you to set the width to avoid wrapping because it will be ugly if you must have the buttons. There is not a lot of real estate to show buttons in this feature, but it is very powerful for warnings, errors and info, or anything you can imagine using it for. Either hard-coding or in an iteration, set the 5th argument of the array, or "state" attribute of your DOM element to a number corresponding from 0 to any number up to your max state range, or as many colors as you want to add.
• The buttons go hand-in-hand with the sift tool, and if you click on them you will see how.

• Add 3 more cats uses the custom "addChoices" function below. Not much to it.
• Add a number shows how you can insert numbers. (but it won't sort alphanumerically).
• Add a random image will add an image, if, in your definition you specify selectionImagePath. I set this to "/" by default, which means to pull images from the root folder.
• Add and remove Liger will do just that.
• Remove lion, puma, cat will also do just what it says, and shows how you can remove with a string id.
• addChoicesLoad() "load and click" is the closest thing to emulating a server-side load. I recommend you do this: First, locate the "minimized log" at the bottom left of your screen, which should be a floating button with arrows inside it. Click it to open it, and then load some data. Put in say, 100 items and then click that load and click button. Watch the log to reveal the time it takes in different browsers. I'm not resetting the count each time, so if you add 10, then add 10 again - the code will assume those 10 are there. To get the next 10, add 20 - the code will see that 10 exist and 10 don't.
• Swap: I have nothing to show for swapping between two of these select boxes, but it wouldn't be hard to write at all. Just make a variation of the add and remove code below.

• urlTarget : (string)
  You only need to specify this if you want this to not open in a new window. Use your standard window opening choices, such as new, top, self.
• The image class I have set up is ".uiSelectBoxChoice.uiSelectBoxChoiceSelected a". This class says "what to look like when I am selected since blue is not good on blue". You'll see i made mine white. I also gave the optional "link" class if you want the url to look differently.
• You need specify the url this way (url-www.google.com), in the third argument or in the div text(), just like you for images. You must have the prepended "url-" in exactly that form and you cannot add "http://" since I assume thats where you are going, I add it for you. Aside from that, you wouldn't be able to add the "//" since it would comment out the code! See the code snippet below for everything else you'll need to know.

• There is no special option you need to set in order to get images to show, you just need to know their paths. You'd specify the image url this way (img-x.gif), in the third argument or in the div text(). You must have the prepended "img-" in exactly that form. See the code snippet below for everything you'll need to know.
• It's kind of fun to sort and use the sift tool when there are images, so give it a go.
• Note: I don't have the image appearing in the toggle, if you happen to have a dropdown or a toggle without a sift tool. Only the id of the image appears. This is due to a variety of display issues that you can image would be extremely difficult to try to manage.
• The lion is laughing at you, btw.

• Skinning may include a variety of changes on your part, and may take some experimentation. The option called "classes", not previously discussed, takes a basic set of classes from your css file. You can override this with any classes you want, but there are 4 main classes.
• ["uiSelectBox","uiSelectBoxToggle","uiSelectBoxChoice","uiSelectBoxStack"]. You probably should not specify the last one other than what's there, but that's up to you - there just isn't much it can do. For the active, graze, disabled and selected states that each option can have, there is a css subclass associated with it that you should probably also write. In general, there will most likely be the following classes:

• Resizable
  Sprinkled throughout this tutorial are examples of resizable select boxes. At the moment it must be anything other than a dropdown type, and it works fine relative or absolute, except for one case. In ie7, you must have absolute positioning for this to work.
• First-letter search
  Called "grazing", if you focus in on the box and type the letter of the item you are looking for, the SBF will focus on that item in a special way. The class for this has the word "graze" in it. At the moment, it allows you to search for one letter per word, and doesn't let you type more to get more specific words. This may improve later.
• Spreadsheet style selections
  Based essentially on how Excel works, and most select boxes, the selectmultiple boxes allows you to use the CTRL key (for windows, or command key for mac) to pick or remove individual selections. You can do this for all selections, including the very last one, to bring your count to 0. The shift key highlights a range of choices as well.
• Truncation and wrapping
  If the item in the choices is too long, it simply wraps, and this doesn't look bad at all. However, if that item is chosen, there is no way for it to fit inside the toggle, so it truncates based on how wide you've set the toggle. The title popup tells you the entire selection text.

• Disabled With the option "disabled" (Boolean), you can begin your dropdown or select box in a disabled state, which uses the disabled classes. This is most useful for applications that must show information to users but not let them touch it. It is also useful for showing required settings that can be set once. You can certainly add a button that enables the items later.

• Select box with toggle By specifying a toggleStyle of open on a selectone, or selectmultiple, you get a less popular variation of the select box which allows a toggle, but doesn't toggle when selections are made.

• CTRL + A keys highlights all and CTRL + D releases them as a special feature.
• Optgroups will be supportedin two variations: 1 is a simply delineation among the choices, that can rollup. The second variation is a mouseover hierarchical menu.
• The next release won't require images to be in the directory of the js file (which is only an issue for the graphics on the select box, not the choices).
• You will have the choice to special the css on the toggle label. Right now its hard coded.
• You will be able to invert selections.
• You will be able to remove choices.
• You will be able to sort alphanumeric o by date.
• You will be able to use the arrow buttons, end and home buttons to work, but there is a stub method in there for now.
• When collecting divs in the DOM that have been set up beforehand, you cant have whitespace between the divs because of the way different browsers render innerHTML. I believe I can fix this in the enxt version. For now, just format, then when done, remove the whitespace.

• resizable adds 2 pixels of padding to your dropdown. You may wnt to adjust your main uiSelectBox class to account for this.
• resizable not great in ie unless absolutely positioned. It sets up a box around the dropdown in an odd way, and that may have something to do with offsets. I've seen this before using jQuery, but don't know yet why this happens. It certainly could be my code, but it works great in every other browser. The absolute demo I added shows that resizable works great in ie when absolutely positioned.
• selections are different in different browsers. Opera seems to be the worst in this respect, covering the selection with a gigantic blue forcefield. If I can figure a way to avoid this, then I'll try, but it is even worse with absolutely positioned select boxes. In general, if you want this to go away, you may have to set the "typeSearch" setting off.
• In Ie, you may see a bit of flashing when you have a dropdown that has a scrollbar (and the cpu is pegged).
• It is noteworthy that if you select images, the image does not appear in the toggle as the choice, rather the id does. I expect to change this in the next version. The main reason is that you can't really truncate an image - not without hiding overflow, and do you want that?
• If you set your browser text to be larger or smaller, then things are going to change, and I am not sure exactly how to deal with this. The worst offender is the sift box (a text box) that sits in the toggle. If you change your default browser settings, or use the mousewheel to make the text larger or smaller, it will change too and may not look great.
• To report bugs and other issues, please leave a comment on my blog. Thats the best way to reach me.

• _setupDirectionals : a commented out method that allows you to tell the select box what to do when a user hits the arrows keys, home, page up or page down.
• _setTruncation : a commented out method that allows you to truncate the text within the rows. Right now it just wraps. As of yet, I haven't figure out how to do this, and if you try you'll see why its hard. It has to do with the order of events.

• first: (and you will do this at least once!) Your definitions are in JSON format, which means you can't leave commas at the end of the last item. IE Will not forgive you for this. Always check.
• Did you leave sift:true, but changed a select box to a dropdown and suddenly you see its not working? This combination is not supported, you will need to make sift:false or take it out if you want a dropdown.
• If you positioned a dropdown absolutely, but the info bar looks fairly ugly then don't use the info bar. It doesn't make sense for dropdowns anyway, since only 1 item can be selected.
• Your definition must be properly formatted - and you may leave out an apostrophe or a quote. Carefully look to see you get the patterns down, and tread slowly to ensure you get it right.
• If your keep getting an error about an object not found, or undefined, chances are you misspelled the name. Check very carefully for camel case mistakes or general spelling errors.
• If you can't get the select box to float or be positioned correctly, remember that these are relatively positioned. In the previous section I show you have to make them absolute, and in the next version, it will be easier to make this happen with a configuraton setting.
• Check your doctype if things aren't working. I don't believe this works the same in quirksmode. If your not sure, then contact me on my blog.

Copyright (c) 2008 Ari N. Karp

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.