Download version 2.2.1 (uncompressed*) | See below for Acknowledgements.
              

Intro

Welcome! Select Box Factory 2.2.1j is a tool written using jQuery 1.2.6 for jQuery users, and was ported over from version 1.1 for mooTools. All you need to do is drop in this js file, and you can call up a select box with much more intelligence, usability, and customization that any current select box allows.

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.

Getting Started: - Choices from memory -

For those of you who want to jump right in, the snippet at the bottom shows the least amount of code you need to create a select box. Except for the div that contains your div choices which is also shown in the formatted section below, that's all there is to it. The little thing on the left with three choices is one of the simplest possible ways to show your select box. But there are several basic decisions you need to make in terms of its configuration, regardless of how you want to use it.
  • 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.
var dropdown = new sFac({	
	id : "fromMemory",
	container : "dropdownContainer"
});	

<div id="dropdownContainer">
	<div id="lynx" title="lynx" defaultSelection="false" state="0" data="claws,stripes"> Lynx </div>
	<div id="cheetah" title="cheetah" defaultSelection="false" state="0" data="eyes,claws">Cheetah</div>
	<div id="bobcat" title="bobcat" defaultSelection="false" state="0" data="eyes,nose">Bobcat</div>
</div>

Getting Started: - Choices from the server side, or hard-coding -

When loading from the server side or even if you just want to hard code the choices without using the DOM, you can iterate by putting your server logic around the choices.
  • 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.
var dropdown = new sFac({	
	id : "fromTheServerSide",
	container : "dropdownContainer",
	choices :
		[
		// iterate here for server side grab.				
			['leopard','leopard','Leopard',false,0,["spots"," ears"]],
			['tiger','tiger','Tiger',false,0,[" tail","nose"]],
			['serval','serval','Serval',true,0,["tail","nose"]],		
		]
});

Settings: - Basic essentials -

Style 1: A Dropdown Style 2: A Select-one Box Style 3: A Select-multiple Box By the time you are done, you'll see that there is a tremendous amount of flexibility and configuration for such a small widget. That can be good, but it can also be bad, for people who feel overwhelmed. That is why I'm moving into this slowly. I'll give you what I feel would be the most popular and requested, yet still very basic settings first. Although I have described two fundamental ways to load choices into your SBF's, from here on in, I will always be showing you snippets where choices are part of the definition, not found in the DOM.

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.



The code for the dropdown is as follows, and shows the following additional settings:
var dropdownType1 = new sFac({	
	id : "dropdownType1",
	container : "dropdownContainerType1",
	coreImages : ["clear.gif","eraser.gif"],
	width: 140,
	toggleStyle : 'closed',
	eraser: true,
	type : 'dropdown',
	maxSize: 6,
	choices :
		[						
		['leopard','leopard','Leopard',false,0,["spots"," ears"]],
		['tiger','tiger','Tiger',false,0,[" tail","nose"]],
		['serval','serval','Serval',false,0,["tail","nose"]],
		['lion','lion','Lion',true,0,["mane","claws"]],					
		['jaguar','jaguar','Jaguar',false,0,["mane","claws"]],				
		['cougar','cougar','Cougar',false,0,["tail","nose"]]			
		]
});		

The code for the selectone box is as follows, and shows the following variations and settings:
var dropdownType2 = new sFac({	
	id : "dropdownType2",
	container : "dropdownContainerType2",
	width: 150,
	eraser: true,
	info: true,
	type : 'selectone',
	count : true,
	maxSize: 3,
	choices :
		[						
		['leopard','leopard','Leopard',false,0,["spots"," ears"]],
		['tiger','tiger','Tiger',false,0,[" tail","nose"]],
		['serval','serval','Serval',false,0,["tail","nose"]],
		['lion','lion','Lion',true,0,["mane","claws"]],					
		['jaguar','jaguar','Jaguar',false,0,["mane","claws"]],				
		['cougar','cougar','Cougar',false,0,["tail","nose"]]			
		]
});		

The code for the selectmultiple box is as follows, and shows the following variations and settings:
var dropdownType3 = new sFac({	
	id : "dropdownType3",
	container : "dropdownContainerType3",
	coreImages : ["clear.gif","eraser.gif","sortasc.gif","sortdesc.gif"],
	width: 150,
	eraser: true,
	info: true,
	resizable: true,
	type : 'selectmultiple',
	count : true,
	sortDirection : 'descending',
	sort:true,
	maxSize: 6,
	choices :
		[						
		['leopard','leopard','Leopard',false,0,["spots"," ears"]],
		['tiger','tiger','Tiger',false,0,[" tail","nose"]],
		['serval','serval','Serval',false,0,["tail","nose"]],
		['lion','lion','Lion',true,0,["mane","claws"]],					
		['jaguar','jaguar','Jaguar',false,0,["mane","claws"]],				
		['cougar','cougar','Cougar',false,0,["tail","nose"]]			
		]
});		

Advanced Features: - Sift -

If you specify sift: true in your definition, you will get this feature, and it is only available for selectone or selectmultiple. To me, its the peanut butter to the select box chocolate. Essentially its a filter that reduces your list based what you type into the box. You don't even have to specify the optional "details" parameters I mentioned earlier, which show as an array at the end of the choices array (if your not using DOM), or as a comma separated attribute if you are using DOM. If you don't specify the details, you still automatically get to sift on the id, the displayname, and the state.
  • 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.
var dropdownType4 = new sFac({	
	id : "dropdownType4",
	container : "dropdownContainerType4",
	coreImages : ["clear.gif","eraser.gif","sortasc.gif","sortdesc.gif"],
	width: 150,
	eraser: true,
	info: true,
	type : 'selectmultiple',
	count : true,
	sort:true,
	sift: true,
	maxSize: 6,
	choices :
		[						
		['leopard','leopard','Leopard',false,0,["spots"," ears"]],
		['tiger','tiger','Tiger',false,0,[" tail","nose"]],
		['serval','serval','Serval',false,0,["tail","nose"]],
		['lion','lion','Lion',true,0,["mane","claws"]],					
		['jaguar','jaguar','Jaguar',false,0,["mane","claws"]],				
		['cougar','cougar','Cougar',false,0,["tail","nose"]]			
		]
});		

Advanced Features: - States & Graphs -

Colored States:
If you specify useStates : true and stateColors : [an array of colors, hex or by name] in your definition, you will get the ability to show states.
  • 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.
Colored State Buttons:
If you specify showStateButtons : true in your definition, you will get the ability to show states as buttons in the top "toggle" bar.
  • 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.
Colored State Graph (2.1):
In 2.1, you can now turn your states into a 5-state css graph. Click the little graph icon and watch it appear. The bars show you all the items that belong to that particular state, and the labels, if they happen to be truncated, do have title text popups as well and this shows you the entire state.
  • 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.

The code for the states box, with buttons is as follows:
var dropdownType5 = new sFac({	
	id : "dropdownType5",
	container : "dropdownContainerType5",
	coreImages : ["clear.gif","eraser.gif","sortasc.gif","sortdesc.gif","graphicon.gif"],
	width: 150,
	type : 'selectmultiple',
	count : true,
	sort: true,
	eraser: true,
	info: true,		
	maxSize: 6,		
	useStates : true,	
	states : ["red","orange","yellow","blue","green"],
	stateColors : ["#BB4446","#E6B42F","#E0DE0D","#577CCD","#77A05C"],	
	showStateButtons : true,
	showStateGraph : true,
	boxScale : 32.0,	
	choices :
		[						
		['leopard','leopard','Leopard',false,1,["spots"," ears"]],
		['tiger','tiger','Tiger',false,1,[" tail","nose"]],
		['serval','serval','Serval',false,2,["tail","nose"]],
		['lion','lion','Lion',true,3,["mane","claws"]],					
		['jaguar','jaguar','Jaguar',false,4,["mane","claws"]],				
		['cougar','cougar','Cougar',false,5,["tail","nose"]]			
		]
});		

Advanced Usage: - Add, swap and remove -


The buttons on the left are various ways you may want to update the select boxes. This is where you probably need to do the most custom work depending on what you want to achieve, although I have provided some decent samples that I created on my own.
  • 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.
function addChoices(){			
	dropdownType7._addChoices(		
	[
	['lynx','lynx','Lynx',false,0,["eyes","spots"]],	
	['cheetah','cheetah','Cheetah',false,0,["spots"," ears"]],
	['bobcat','bobcat','Bobcat',false,0,["spots"," ears"]]
	]	
	)
}

function addChoicesLoad(){
	var num = document.getElementById("testNum").value;
	if(num > 350){
		document.getElementById("testNum").value = 350;
		return;
	}
	var arr = [];
	document.getElementById("testNum").disabled = true;
	for(i=0;i < num;i++) arr.push(['test_choice'+i,'test_choice'+i,'test_choice sample',false,0,["data1","data2"]])
	dropdownType7._addChoices(arr);
	document.getElementById("testNum").disabled = false;
}

dropdownType7._addChoices([['liger','liger','Liger',true,2,['claws','stripes']]])
dropdownType7._removeChoices(['liger'])

dropdownType7._addChoices([['includeLowerRange','img1','img-insideincludelower.gif',true,2,[]]])

dropdownType7._addChoices([[1132,1132,1132,false,2,[]]])

Other Features: - Position : absolute -

var dropdown_abs3 = new sFac({	
	id : "dropdown_abs3",
	container : "dropdownContainerAbs",
	coreImages : ["clear.gif","eraser.gif","sortasc.gif","sortdesc.gif"],
	selectionImagePath : "images/",
	width: 160,
	resizable: true,// best for non-dropdowns. Tell uiSelectBox class to be padding:4px; to look nicer.
	toggleStyle : 'closed',
	type : 'dropdown',
	eraser : true,
	count : true,
	isAbsolute : true,
	absolutePosition : { top: 60, left : 70, z:10 },
	maxSize: 6,
	sortDirection : 'descending',
	sort: true,
	choices :
		[	
		['cat','cat','Cat',true,0,["eyes","teeth"]],	
		['leopard','leopard','Leopard',false,0,["spots"," ears"]],
		['tiger','tiger','Tiger',false,0,[" tail","nose"]],
		['serval','serval','Serval',false,0,["tail","nose"]],
		['lion','lion','Lion',true,0,["mane","claws"]],					
		['kodkod','kodkod','Kodkod',true,0,["mane","claws"]],	
		['puma','puma','Puma',false,0,["paws","stripes"]],
		['ocelot','ocelot','Ocelot',false,0,["eyes","teeth"]],
		['oncilla','oncilla','Oncilla',false,0,["eyes","teeth"]],
		['jaguar','jaguar','Jaguar',false,0,["mane","claws"]],				
		['cougar','cougar','Cougar',false,0,["tail","nose"]]			
		]
});		

Other Features: - Urls -

Adding urls is easy, and urls get sorted just as strings do. There are a couple of issues to note, but first, the settings:
  • 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.
var dropdownUrl = new sFac({	
	id : "dropdownUrl",
	container : "dropdownContainerUrl",
	coreImages : ["clear.gif","eraser.gif","sortasc.gif","sortdesc.gif"],
	width: 160,
	toggleStyle : 'open',
	type : 'dropdown',
	eraser : true,
	count : true,
	maxSize: 6,
	sortDirection : 'descending',
	sort: true,
	choices :
		[						
		['google','google','url-www.google.com',false,0,[]],
		['dzone','dzone','url-www.dzone.com',false,0,[]],
		['jQUery','jQUery','url-www.jQUery.com',false,0,[]],			
		['theuiguy','the ui guy','url-theuiguy.blogspot.com',false,0,[]]
		]
});		

Other Features: - Images -

Adding images is also fairly easy, and images get sorted just as if they were strings. The settings:
  • 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.

var dropdown_img10 = new sFac({	
	id : "dropdown_img10",
	imageSelections : { 
		show: true, 
		height: 35, 
		padding: { 
			top:2, 
			left:0, 
			bottom: 2, 
			right: 0
		}
	},
	container : "dropdownContainer10",
	coreImages : ["clear.gif","eraser.gif","sortasc.gif","sortdesc.gif"],
	selectionImagePath : "images/",
	coreImagePath : "images/",
	width: 180,
	resizable: true,// best for non-dropdowns. Tell uiSelectBox class to be padding:4px; to look nicer.
	type : 'selectone',
	sift:true,
	eraser : true,
	count : true,
	maxSize: 4,
	sortDirection : 'descending',
	sort: true,
	choices :
		[
		['lion','lion','img-lion.gif',true,0,[]],	
		['leopard','leopard','img-leopard.gif',false,0,[]],
		['tiger','tiger','img-tiger.gif',false,0,[]]			
		['tiger','tiger','img-tiger.gif|Any Text I want...',false,0,[]],
		['tiger.com','tiger.com','url-www.tigers.com',false,0,[]]	
		]
});		

Other Features: - Skinning -

Here are some variations in skinning that I included. In these examples, I am using a variation not seen before, which is a select box that has its toggle open by default. You can click the title to see that it does toggle.
  • 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:
for the box and choices:
.uiSelectBox
.uiSelectBoxToggle
.uiSelectBoxToggleSift
.uiSelectBoxToggleDisabled
.uiSelectBoxDisabled
.uiSelectBoxStack
.uiSelectBoxStackDisabled
.uiSelectBoxChoice
.uiSelectBoxChoiceDisabled
.uiSelectBoxChoice.uiSelectBoxChoiceNormal
.uiSelectBoxChoice.uiSelectBoxChoiceActive
.uiSelectBoxChoice.uiSelectBoxChoiceGraze
.uiSelectBoxChoice.uiSelectBoxChoiceSelected
.uiSelectBoxChoice.uiSelectBoxChoiceSelected a
.uiSelectBoxChoice.uiSelectBoxChoiceDisabled

for the states:
.statesHeader
.statesHeaderItem
.statesHeaderItem.pushedHeaderItem
.statesHeaderItem.unPushedHeaderItem

for the other parts:
.sortFlip
.toggleText
.selectUpdate
.infoBar
.siftBox
.focusBox
.link

Other Features: - Collection of Selections, Reset, and Hooks



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

Example 1:
function gatherAllChoices(){
	var monthsSelected = monthSelect._gatherChoices(";"); // using semicolon separated list as example
	var yearsSelected = yearSelect._gatherChoices(";");
}
Example 2:
function gatherAllChoices(){
	< button onclick="$(monthSelect.dropdownStack.childNodes[0]).trigger('externalClick')"> reset month < /button >
	< button onclick="$(yearSelect.dropdownStack.childNodes[0]).trigger('externalClick')" > reset year < /button >
}
Example 3:
function selectBoxItemHook(box){ //this happens when you press a select box item, now part of the tookit. defaults to nothing (as in this demo).
	// example of what you may want to write.
	switch(box.id){
		case "example1": 
			// user clicked anything in the month sFac
			log.out("general note: i clicked something either manually or programmatically in example1")				
		break;
		case "example2":
			// user clicked anything in the year sFace
			log.out("general note: i clicked something either manually or programmatically in example2")		
		break;	
	}	
}

Other Features: - All other features -

The following features, not previously discussed come automatically with the SBF.
  • 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.
The following features, not previously discussed must be configured. For the comprehensive list of settings, see the next section.
  • 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.
The following variations are also available:
  • 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.

Shortcut Guide: - All possible settings -

,
Setting Type Default if not set (or example) Description Notes
id string required N/A N/A
container string required this is the id of a container somewhere on the screen. document.body will be used if no id is specified, but its not something you want.
type string selectone the dropdown type selectone | selectmultiple | dropdown (are the choices)
choices array (with arrays) if none specified, will look in DOM for choices, or will show empty otherwise. as described above, the choices for the dropdown
toggleStyle string none used to determined if a toggle should be shown, and if so: open or closed by default. none | open | closed (are the choices)
coreImages array ["clear.gif", "eraser3.gif", "sortasc3.gif", "sortdesc3.gif", "graphIcon.gif"] list the images you required, in the directory of the js file. graphIcon is new in 2.1
classes array ["uiSelectBox", "uiSelectBoxToggle", "uiSelectBoxChoice", "uiSelectBoxStack"] the default classes used by the select box
isAbsolute boolean false sets the specified container to be absolute as well.
absolutePosition JSON object { top: 0, left : 0, z : 0 } sets the top, left, and zIndex of your select box inside the container, goes with "absolutePosition".
urlTarget string "new" where to open the url, if addding urls. options are your standard window open options, like "self", "new", "top".
width number the default is from the class first, container second.
eraser Boolean false whether or not to allow the clear selections feature.
sift Boolean false whether to allow the sift feature. sift can only be used with selectone or selectmultiple and when a toggle is present.
info Boolean false whether or not to show how many items are selected.
count Boolean false whether or not to show how many items are in the dropdown.
sort Boolean false whether or not to sort the list by default, and show a sort icon to allow sort flipping.
disabled Boolean false whether or not to show the select box as disabled by default. select box can be "enabled" later with your own function.
typeSearch Boolean true whether or not allow a user to find items by pressing a key if your using opera 9.5, you may want this turned off, so i added this setting. Its turly horrific because of the way Opera decided to do selections.
sortDirection string ascending the direction to sort the options by default. descending or ascending (are the choices)
states (2.1) string["red","orange","yellow","blue","green"] the names of your states to show on the chart. in 2.1, you call a state using 1-n, not 0-n.
useStates Boolean false whether or not to show states (0-n) in the choices.
showStateButtons Boolean false whether or not to show state filter buttons on the toggle. Useful if you include this with sift. The erase clears the selection.
stateColors array ["red" ,"orange" ,"yellow" ,"lightblue" ,"darkblue"] the colors, if needed, to specify for the states. should match the unique count of states.
maxSize number choices.length how many items to show before scrolling occurs.
selectionImagePath string "/" used to specify the path of images, if you are loading images into the dropdown instead of strings or numbers.
coreImagePath (2.2.1) string same as selectionImagePath is not defined used to specify the path of the images core to the select box and not the selections. (like the eraser, graph, dropdown bg)
resizable Boolean false whether or not to allow resizing the select box. requires a jQuery plugin, and (works in IE only when the dropdown is absolutely positioned).
toggleLabel string Select One: what to show in the toggle when nothing is selected.
toggleLabelChosen string "" (empty) what to prepend selections with. example: "item selected: x".
siftTitle string Use AND (+) plus, or OR (|) pipe to extend search. Use (!) not to flip the search. what to show as the title (alt) popup.
showStateGraph (2.1) boolean false whether to show the graph or not.
graphPosition (2.1) string relative what position to place the graph. absolute or relative
boxScale (2.1) decimal 3.0 The scaling factor for your graph. the higher the scale, the taller each segment in a bar will be.
imageSelections (2.2.1) JSON definition false When you want an image to appear in the toggle of a dropdown. { show: true, height: 35, padding: { top:2, left:0, bottom:2, right: 0}}

Appendix A: - Future features, caveats, issues -

The following are features or enhancements I expect to be in the next release (2.1)
  • 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.
The following are issues I've noticed:
  • 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.
The following functions are stubs in the code or can be turned on or extended
  • _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.

Appendix B: - Troubleshoot Guide -

The following are a few things to check, they come up time and time again.
  • 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.

About, Contact & Acknowledgements

Available under MIT style license, which in layman terms says, "go ahead and take it, mang, just at least tell people I wrote the software - the parts the I myself wrote. But if it blows up your house or makes your dog run away, you can't sue me." That's it.

SelectboxFactory.js 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.

Acknowledgements:
* I'll be adding a compressed version soon.

For bug reports, questions, or comments, or more information on the logger, please visit: theuiguy.blogspot.com