/* // SmartStars.js // // The majority of this code came from SmartStars.js on http://scripterlative.com?smartstars // I made some enhancements and also modified the code so that the rating text can be used. - Terry Guarisco, Jr. // Graphical Star-Rating System with Form Element Interface * Multiple rating bars in one document. * Configurable for number of stars and initial setting. * Unobtrusive installation - no onmouseover/onmouseout handlers to install * Optional external function execution for easy AJAX interfacing. * Keyboard Accessible (Enter key selects) Demonstration and further details at http://scripterlative.com?smartstars The following instructions may be removed, but not the above text. Please notify any suspected errors in this text or code, however minor. Description ~~~~~~~~~~~ Generates a horizontal 'rating bar' comprised of either of two graphical images that indicate the current rating. To set a numeric rating, any image in the row may be clicked. Installation ~~~~~~~~~~~~ Save this file as 'smartstars.js' In the section of your document, include the script by adding the tags below: For each rating bar to be generated, create a containing element with a unique ID. This element may be given any suitable CSS attributes. Create a form containing a hidden type element for each rating bar. Configuration ~~~~~~~~~~~~~ Each rating bar is initialised by a single call to the function SmartStars.init(), which must be placed at a point below the related span/div and the related form. The function takes six or seven parameters as described next. Parameter 1 - The ID of the span element that will contain the rating bar. Parameter 2 - A ID of a form element (usually of type 'hidden') that will store the numeric star rating selected by the user. Parameter 3 - The ID of a form element whose innerHTML will contain the rating text Parameter 4 - The initial rating. (0 to display no 'on' stars) Parameter 5 - The number of stars in the rating bar. Parameter 6 - The file name of the 'off' graphic. (Include a relative path if necessary) Parameter 7 - The file name of the 'on' graphic. Parameter 8 - (Optional) A reference to a user function called onmouseover, onmouseout, and onclick Parameter 9 - (Optional) A reference to a user function called whenever the display changes. Internal - readOnlySmartStars : a flag indicating the readonly status of the control Internal - smartStarsRatingTextDictionary : a client-side dictionary containing the rating values and associated text (Dictionary.js must be included for this to work. The dictionary can be populated server-side if needed, i.e. ClientScript.RegisterStartupScript(...)) Example ~~~~~~~ Create a star rating display using a span with the id 'stars1'. The numeric rating set by the user will be written to the element named 't1', belonging to a form named 'form1'. The initial rating will be set to 5 out of 10 stars. The star graphics used are called 'offstar.gif' & 'onstar.gif'. At a point below the associated form and span elements, insert: Note: Parameters 1, 2, 3, 5 & 6 must be in quotes as shown, the others must not. Repeat the above for as many instances as required. Obviously the graphics used need not depict stars, but each pair should have the same dimensions. That's all there is to it. Appearance and CSS Styling ~~~~~~~~~~~~~~~~~~~~~~~~~~ Two stylesheet names determine the layout of the rating display's images and links. These are 'SmartStarsLinks' and 'SmartStarsImages' respectively. The default recommended minimal styling is shown below. This text should be placed inside tags in the section of the document. a.SmartStarsLinks{padding:0px} .SmartStarsImages{margin:0px; border:none} Setting or Cancelling A Rating ------------------------------ The SmartStars.set method can be used to set a rating after it has been initialised. To set a rating to 3 'stars', call: SmartStars.set(span id, 2); To reset a rating to 0 'stars', call: SmartStars.set(span id, -1); To facilitate its use within links, this method returns false: Cancel Rating Optional Function Interfaces ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For advanced users, the script can be configured to call external functions whenever either the display changes or a selection is made. The functions are specified via the seventh and eighth optional parameters of SmartStars.init. Seventh parameter - Function called on hover/focus. Eighth parameter - Function called on selection. The functions are passed a numeric, zero-based index corresponding to the currently displayed rating (0 = 1 'star'), and should be coded to handle a parameter value of -1. Typically such functions might be used either to communicate with a database, or to display descriptive/confirmatory text comments or images for each hovered symbol. AJAX functions can be called to submit the new rating and receive back the calculated average, which a readystate handler can update by calling the .set method. The 'hover' function is also called when SmartStars.init is called, except when the initial rating is set to 0. Example: Display different text as icons are hovered - function showText( index ) { // Write text according to the value of 'index' } SmartStars.init('pnlRatingWrapper', 'hdnRating', 'pnlRatingText', 3, 5, 'offstar.gif', 'onstar.gif', showText); ------- Example: Display confirmation text when a selection is made - function confirmText(sender, index) { // Write text according to the value of 'index' } SmartStars.init('pnlRatingWrapper', 'hdnRating', 'pnlRatingText', 3, 5, 'offstar.gif', 'onstar.gif', null, confirmText); */ var readOnlySmartStars = false; var smartStarsRatingTextDictionary = new Dictionary(); var SmartStars = { data: [], init: function(ratingId, formElemId, ratingTextElemId, rating, starCount, offStar, onStar, hFunc, cFunc) { if (document.getElementById) { var elem = this.data[ratingId] = {}; if (!!hFunc) elem.externHoverFunc = hFunc; if (!!cFunc) elem.externSetFunc = cFunc; elem.elemRef = document.getElementById(ratingId); elem.formElem = document.getElementById(formElemId); elem.ratingTextElem = document.getElementById(ratingTextElemId); elem.starCount = starCount; elem.rating = rating; elem.offStar = offStar; elem.onStar = onStar; elem.rating = Math.max(-1, elem.rating); if (elem.rating != -1) elem.rating--; elem.starTable = []; if (elem.elemRef) this.build(ratingId); // else // alert(this.elemRef + " is not a valid element ID.") } }, build: function(id) { var elem = this.data[id]; for (var i = 0, sp, lnk; i < elem.starCount; i++) { (lnk = document.createElement('a')).appendChild(sp = document.createElement('img')); lnk.href = '#'; lnk.className = 'SmartStarsLinks'; lnk.style.textDecoration = 'none'; sp.className = 'SmartStarsImages'; sp.idx = i; sp.src = elem.offStar; sp.style.border = 'none'; elem.imgBuffer = new Image(); elem.imgBuffer.src = elem.onStar; lnk.onmouseout = (function(obj, ident) { return function() { if (obj) obj.lightOff(ident, this.firstChild.idx) } })(this, id); lnk.onblur = lnk.onmouseout; if (readOnlySmartStars == false) { lnk.onmouseover = (function(obj, ident) { return function() { if (obj) obj.lightOn(ident, this.firstChild.idx) } })(this, id); lnk.onfocus = lnk.onmouseover; lnk.onmouseup = function() { if (this.blur) this.blur(); } /*lnk.onclick=new Function("if(typeof SmartStars!='undefined'){SmartStars.set('"+id+"', this.firstChild.idx);}return false");*/ lnk.onclick = (function(obj, ident) { return function() { if (obj) obj.set(ident, this.firstChild.idx); return false; } })(this, id); } else { lnk.onmouseover = null; lnk.onfocus = null; lnk.onmouseup = null; lnk.onclick = (function() { return false; }); } elem.starTable[i] = sp elem.elemRef.appendChild(lnk); elem.formElem.value = elem.rating + 1; } if (lnk) { this.addToHandler(elem.formElem, 'onchange', new Function("if(typeof SmartStars!='undefined')SmartStars.setFromForm('" + id + "',this.value);")); lnk.onmouseout(); } }, setFromForm: function(id, elemValue) { var v, dat = this.data[id], len = dat.starTable.length; if (!isNaN(v = parseInt(elemValue, 10))) { dat.rating = (elemValue > len ? (len - 1) : elemValue < -1 ? -1 : (elemValue - 1)); this.lightOff(id); if (dat.externSetFunc) dat.externSetFunc(dat.elemRef, (v - 1)); } return false; }, setFormElem: function(elem, value) { var h; if (elem) { h = elem.onchange; elem.value = value; elem.onchange = h; } }, lightOn: function(id, elemIdx) { var dat = this.data[id], table = dat.starTable; for (var i = 0, len = table.length; i < len; i++) table[i].src = (i <= elemIdx ? dat.onStar : dat.offStar); this.setFormElem(dat.formElem, elemIdx + 1); if (dat.ratingTextElem && smartStarsRatingTextDictionary && smartStarsRatingTextDictionary.Keys.length > 0) dat.ratingTextElem.innerHTML = smartStarsRatingTextDictionary.Lookup(elemIdx + 1); if (dat.externHoverFunc) dat.externHoverFunc(dat.elemRef, elemIdx); }, lightOff: function(id) { var dat = this.data[id], table = dat.starTable; for (var i = 0, len = table.length; i < len; i++) table[i].src = (i <= dat.rating ? dat.onStar : dat.offStar); this.setFormElem(dat.formElem, dat.rating + 1); if (dat.externHoverFunc) dat.externHoverFunc(dat.elemRef, dat.rating); if (dat.ratingTextElem && smartStarsRatingTextDictionary && smartStarsRatingTextDictionary.Keys.length > 0) dat.ratingTextElem.innerHTML = smartStarsRatingTextDictionary.Lookup(dat.rating + 1); }, set: function(id, idx) { this.data[id].formElem.value = (this.data[id].rating = idx) + 1; this.lightOn(id, Math.max(-1, Math.min(idx, this.data[id].starTable.length - 1))); if (this.data[id].externSetFunc) this.data[id].externSetFunc(this.data[id].elemRef, idx); return false; }, addToHandler: function(obj, evt, func) { if (obj[evt]) { obj[evt] = function(f, g) { return function() { f.apply(this, arguments); return g.apply(this, arguments); }; } (func, obj[evt]); } else obj[evt] = func; } }