Whats new in 2.1? Aside from a few bugs fixes, check it out on the left. See the little bar graph icon? Click it! Then mouseover the bar graph and labels.

Whats new in 2.2.x? The ability to call your own code when someone touches a dropdown, the ability to grab all selections, and the ability to show images and text together in one dropdown, and images in the toggle.

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 and now a graph. 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.

• 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, it's 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.
• 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 closed dropdown, you may notice that 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, but What's going on behind the scenes is a little more complex.
• Even though sift automatically grabs 3 siftable parameters for you, you can extend this as far as you want, by 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.

• 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.

• Up to 4 or 5 can easily fit, and beyond that, it's 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.

• states: (array of names). These names show up on the chart, and they correspond to your colors. The length of this array must be as long as your stateColors array. When you tell a choice to be a state, you no longer have to use the index of the array. You just choose 1-x instead of 0-x. Although I am showing states and stateColors to be the same, they have to be separate so you can make normal labels and use hex colors.
• showStateGraph : true will give you the ability to show a little graph/chart icon that transforms your states into a 5-state graph. So, there is, for now, a limit of 5 states. The rgeat think about this graph is that as you add and remove items in this chart, the graph also updates. jQuery also provides a great transition effect. The following options are also available:
• boxScale (decimal) : tells the graph relatively speaking, how high to make each increment. I decided not to do this programmatically since the value of (1) alone would suffice. The higher you make this number, the higher the bars will get. It works inversely: if you have 15,000 items, you might want to make this (.1), but if you can put 15,000 items in this box I'll be amazed. Really, with boxes of this nature we're dealing with items on the order of under 500. At that scale, anywhere between (.5) and (1.5) would suffice. The chart doesn't get impressive unless you set the scale correctly. Just figure out how large you expect the box to be, and get the scale from that. Because this demo is static and I had only a very small handful of items, I set it to 32. I may make this programmatic in the next version, depends on what you think.
• graphPosition (absolute | relative), tells your graph where to be. I default to relative. Relative pushes content out of the way, and absolute makes it float.
• In addition, i've added a 5th icon to the coreImages definition, called "graphIcon.gif".
• Last but not least: the default image for the css graph has the colors you see. If you want different colors, I recommend you grab the included file (g_colorbar3.jpg) and simply change the colors and perhaps make yourself a variety of palettes. I also may include this in the next version. The colors in the snippet below for stateColors are the hex numbers to use to match the default graph bar colors.

• 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 : "images/". 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.

• selectionImagePath and coreImagePath settings: selectionImagePath is where the code expects to look to find images you want to use for the selectable divs inside the dropdown, but not the dropdown itself (the eraser, the graph icon, etc). coreImagePath, on the other hand is just the opposite. If you want these images in a different directory than specify coreImagePath as a setting, otherwise it will just use selectionImagePath.
• There is no special option you need to set in order to get images to show, you just need to know their paths (which is selectionImagePath). 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.
• as of 2.2.1, you can now view images in the toggle. See the area below in red that shows how images should be treated if you want them in the toggle.
• You can also view images and text options in the same dropdown (before this wasn't possible).
• You can now specify a pip delimiter "|" in the img- type options to render any text you want which will appear, like a label next to the image. Just be careful how wide you make this since it won't use truncation logic or wrap.
• You can now specify coreImagePath, if you want the aort, toggle background, eraser or chart icons to be different than your selection images. I show it in the sample below for illustration purposes, but it will default to selectionImagePath if not defined.
• Note: the maxSize does its best to figure out the average height of the dropdowns, but it takes the first one. If you decide to mix images and text and urls, as of right now, maxSize won't be as effective.

• 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:

• Consider these more advanced features, but very practical. Through a series of tests, I will show you how to collect values from the dropdown, reset them if necessary or use your own hooks to call functions of your own when a user touches a dropdown.
• These tests make use of a logger that should appear on the bottom left, or bottom center of the screen once you press a blue button below. This logger tells you exactly what the code is doing. (I took the log down, but this section explains what it needs to.)
• Example #1 shows you how to collect values. The values are returned as an array by default, but you can even specify the type as "string" or "json" if you prefer. Grabbing individual values from these sets is of course, easy if you understand coding.
• Examples #2a and #2b shows you how to reset the dropdowns. (the reset buttons)
• Example #3 shows the function selectBoxItemHook, which you do not need to write. I am giving you an example of what you may want to write, provided you want the code to do something when someone clicks a select box item. What it does is up to you.

• 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 it's 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 it's 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 it's 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 you 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 you're not sure, then contact me on my blog.

SelectboxFactory.js Copyright (c) 2008 Headcircus

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.