lib/yui/autocomplete/autocomplete-debug.js

   1 /*
   2 Copyright (c) 2008, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.net/yui/license.txt
   5 version: 2.5.2
   6 */
   7  /**
   8  * The AutoComplete control provides the front-end logic for text-entry suggestion and
   9  * completion functionality.
  10  *
  11  * @module autocomplete
  12  * @requires yahoo, dom, event, datasource
  13  * @optional animation, connection, get
  14  * @namespace YAHOO.widget
  15  * @title AutoComplete Widget
  16  */
  17
  18 /****************************************************************************/
  19 /****************************************************************************/
  20 /****************************************************************************/
  21
  22 /**
  23  * The AutoComplete class provides the customizable functionality of a plug-and-play DHTML
  24  * auto completion widget.  Some key features:
  25  * <ul>
  26  * <li>Navigate with up/down arrow keys and/or mouse to pick a selection</li>
  27  * <li>The drop down container can "roll down" or "fly out" via configurable
  28  * animation</li>
  29  * <li>UI look-and-feel customizable through CSS, including container
  30  * attributes, borders, position, fonts, etc</li>
  31  * </ul>
  32  *
  33  * @class AutoComplete
  34  * @constructor
  35  * @param elInput {HTMLElement} DOM element reference of an input field.
  36  * @param elInput {String} String ID of an input field.
  37  * @param elContainer {HTMLElement} DOM element reference of an existing DIV.
  38  * @param elContainer {String} String ID of an existing DIV.
  39  * @param oDataSource {YAHOO.widget.DataSource} DataSource instance.
  40  * @param oConfigs {Object} (optional) Object literal of configuration params.
  41  */
  42 YAHOO.widget.AutoComplete = function(elInput,elContainer,oDataSource,oConfigs) {
  43     if(elInput && elContainer && oDataSource) {
  44         // Validate DataSource
  45         if(oDataSource instanceof YAHOO.widget.DataSource) {
  46             this.dataSource = oDataSource;
  47         }
  48         else {
  49             YAHOO.log("Could not instantiate AutoComplete due to an invalid DataSource", "error", this.toString());
  50             return;
  51         }
  52
  53         // Validate input element
  54         if(YAHOO.util.Dom.inDocument(elInput)) {
  55             if(YAHOO.lang.isString(elInput)) {
  56                     this._sName = "instance" + YAHOO.widget.AutoComplete._nIndex + " " + elInput;
  57                     this._elTextbox = document.getElementById(elInput);
  58             }
  59             else {
  60                 this._sName = (elInput.id) ?
  61                     "instance" + YAHOO.widget.AutoComplete._nIndex + " " + elInput.id:
  62                     "instance" + YAHOO.widget.AutoComplete._nIndex;
  63                 this._elTextbox = elInput;
  64             }
  65             YAHOO.util.Dom.addClass(this._elTextbox, "yui-ac-input");
  66         }
  67         else {
  68             YAHOO.log("Could not instantiate AutoComplete due to an invalid input element", "error", this.toString());
  69             return;
  70         }
  71
  72         // Validate container element
  73         if(YAHOO.util.Dom.inDocument(elContainer)) {
  74             if(YAHOO.lang.isString(elContainer)) {
  75                     this._elContainer = document.getElementById(elContainer);
  76             }
  77             else {
  78                 this._elContainer = elContainer;
  79             }
  80             if(this._elContainer.style.display == "none") {
  81                 YAHOO.log("The container may not display properly if display is set to \"none\" in CSS", "warn", this.toString());
  82             }
  83
  84             // For skinning
  85             var elParent = this._elContainer.parentNode;
  86             var elTag = elParent.tagName.toLowerCase();
  87             if(elTag == "div") {
  88                 YAHOO.util.Dom.addClass(elParent, "yui-ac");
  89             }
  90             else {
  91                 YAHOO.log("Could not find the wrapper element for skinning", "warn", this.toString());
  92             }
  93         }
  94         else {
  95             YAHOO.log("Could not instantiate AutoComplete due to an invalid container element", "error", this.toString());
  96             return;
  97         }
  98
  99         // Set any config params passed in to override defaults
 100         if(oConfigs && (oConfigs.constructor == Object)) {
 101             for(var sConfig in oConfigs) {
 102                 if(sConfig) {
 103                     this[sConfig] = oConfigs[sConfig];
 104                 }
 105             }
 106         }
 107
 108         // Initialization sequence
 109         this._initContainer();
 110         this._initProps();
 111         this._initList();
 112         this._initContainerHelpers();
 113
 114         // Set up events
 115         var oSelf = this;
 116         var elTextbox = this._elTextbox;
 117         // Events are actually for the content module within the container
 118         var elContent = this._elContent;
 119
 120         // Dom events
 121         YAHOO.util.Event.addListener(elTextbox,"keyup",oSelf._onTextboxKeyUp,oSelf);
 122         YAHOO.util.Event.addListener(elTextbox,"keydown",oSelf._onTextboxKeyDown,oSelf);
 123         YAHOO.util.Event.addListener(elTextbox,"focus",oSelf._onTextboxFocus,oSelf);
 124         YAHOO.util.Event.addListener(elTextbox,"blur",oSelf._onTextboxBlur,oSelf);
 125         YAHOO.util.Event.addListener(elContent,"mouseover",oSelf._onContainerMouseover,oSelf);
 126         YAHOO.util.Event.addListener(elContent,"mouseout",oSelf._onContainerMouseout,oSelf);
 127         YAHOO.util.Event.addListener(elContent,"scroll",oSelf._onContainerScroll,oSelf);
 128         YAHOO.util.Event.addListener(elContent,"resize",oSelf._onContainerResize,oSelf);
 129         YAHOO.util.Event.addListener(elTextbox,"keypress",oSelf._onTextboxKeyPress,oSelf);
 130         YAHOO.util.Event.addListener(window,"unload",oSelf._onWindowUnload,oSelf);
 131
 132         // Custom events
 133         this.textboxFocusEvent = new YAHOO.util.CustomEvent("textboxFocus", this);
 134         this.textboxKeyEvent = new YAHOO.util.CustomEvent("textboxKey", this);
 135         this.dataRequestEvent = new YAHOO.util.CustomEvent("dataRequest", this);
 136         this.dataReturnEvent = new YAHOO.util.CustomEvent("dataReturn", this);
 137         this.dataErrorEvent = new YAHOO.util.CustomEvent("dataError", this);
 138         this.containerExpandEvent = new YAHOO.util.CustomEvent("containerExpand", this);
 139         this.typeAheadEvent = new YAHOO.util.CustomEvent("typeAhead", this);
 140         this.itemMouseOverEvent = new YAHOO.util.CustomEvent("itemMouseOver", this);
 141         this.itemMouseOutEvent = new YAHOO.util.CustomEvent("itemMouseOut", this);
 142         this.itemArrowToEvent = new YAHOO.util.CustomEvent("itemArrowTo", this);
 143         this.itemArrowFromEvent = new YAHOO.util.CustomEvent("itemArrowFrom", this);
 144         this.itemSelectEvent = new YAHOO.util.CustomEvent("itemSelect", this);
 145         this.unmatchedItemSelectEvent = new YAHOO.util.CustomEvent("unmatchedItemSelect", this);
 146         this.selectionEnforceEvent = new YAHOO.util.CustomEvent("selectionEnforce", this);
 147         this.containerCollapseEvent = new YAHOO.util.CustomEvent("containerCollapse", this);
 148         this.textboxBlurEvent = new YAHOO.util.CustomEvent("textboxBlur", this);
 149
 150         // Finish up
 151         elTextbox.setAttribute("autocomplete","off");
 152         YAHOO.widget.AutoComplete._nIndex++;
 153         YAHOO.log("AutoComplete initialized","info",this.toString());
 154     }
 155     // Required arguments were not found
 156     else {
 157         YAHOO.log("Could not instantiate AutoComplete due invalid arguments", "error", this.toString());
 158     }
 159 };
 160
 161 /////////////////////////////////////////////////////////////////////////////
 162 //
 163 // Public member variables
 164 //
 165 /////////////////////////////////////////////////////////////////////////////
 166
 167 /**
 168  * The DataSource object that encapsulates the data used for auto completion.
 169  * This object should be an inherited object from YAHOO.widget.DataSource.
 170  *
 171  * @property dataSource
 172  * @type YAHOO.widget.DataSource
 173  */
 174 YAHOO.widget.AutoComplete.prototype.dataSource = null;
 175
 176 /**
 177  * Number of characters that must be entered before querying for results. A negative value
 178  * effectively turns off the widget. A value of 0 allows queries of null or empty string
 179  * values.
 180  *
 181  * @property minQueryLength
 182  * @type Number
 183  * @default 1
 184  */
 185 YAHOO.widget.AutoComplete.prototype.minQueryLength = 1;
 186
 187 /**
 188  * Maximum number of results to display in results container.
 189  *
 190  * @property maxResultsDisplayed
 191  * @type Number
 192  * @default 10
 193  */
 194 YAHOO.widget.AutoComplete.prototype.maxResultsDisplayed = 10;
 195
 196 /**
 197  * Number of seconds to delay before submitting a query request.  If a query
 198  * request is received before a previous one has completed its delay, the
 199  * previous request is cancelled and the new request is set to the delay.
 200  * Implementers should take care when setting this value very low (i.e., less
 201  * than 0.2) with low latency DataSources and the typeAhead feature enabled, as
 202  * fast typers may see unexpected behavior.
 203  *
 204  * @property queryDelay
 205  * @type Number
 206  * @default 0.2
 207  */
 208 YAHOO.widget.AutoComplete.prototype.queryDelay = 0.2;
 209
 210 /**
 211  * Class name of a highlighted item within results container.
 212  *
 213  * @property highlightClassName
 214  * @type String
 215  * @default "yui-ac-highlight"
 216  */
 217 YAHOO.widget.AutoComplete.prototype.highlightClassName = "yui-ac-highlight";
 218
 219 /**
 220  * Class name of a pre-highlighted item within results container.
 221  *
 222  * @property prehighlightClassName
 223  * @type String
 224  */
 225 YAHOO.widget.AutoComplete.prototype.prehighlightClassName = null;
 226
 227 /**
 228  * Query delimiter. A single character separator for multiple delimited
 229  * selections. Multiple delimiter characteres may be defined as an array of
 230  * strings. A null value or empty string indicates that query results cannot
 231  * be delimited. This feature is not recommended if you need forceSelection to
 232  * be true.
 233  *
 234  * @property delimChar
 235  * @type String | String[]
 236  */
 237 YAHOO.widget.AutoComplete.prototype.delimChar = null;
 238
 239 /**
 240  * Whether or not the first item in results container should be automatically highlighted
 241  * on expand.
 242  *
 243  * @property autoHighlight
 244  * @type Boolean
 245  * @default true
 246  */
 247 YAHOO.widget.AutoComplete.prototype.autoHighlight = true;
 248
 249 /**
 250  * Whether or not the input field should be automatically updated
 251  * with the first query result as the user types, auto-selecting the substring
 252  * that the user has not typed.
 253  *
 254  * @property typeAhead
 255  * @type Boolean
 256  * @default false
 257  */
 258 YAHOO.widget.AutoComplete.prototype.typeAhead = false;
 259
 260 /**
 261  * Whether or not to animate the expansion/collapse of the results container in the
 262  * horizontal direction.
 263  *
 264  * @property animHoriz
 265  * @type Boolean
 266  * @default false
 267  */
 268 YAHOO.widget.AutoComplete.prototype.animHoriz = false;
 269
 270 /**
 271  * Whether or not to animate the expansion/collapse of the results container in the
 272  * vertical direction.
 273  *
 274  * @property animVert
 275  * @type Boolean
 276  * @default true
 277  */
 278 YAHOO.widget.AutoComplete.prototype.animVert = true;
 279
 280 /**
 281  * Speed of container expand/collapse animation, in seconds..
 282  *
 283  * @property animSpeed
 284  * @type Number
 285  * @default 0.3
 286  */
 287 YAHOO.widget.AutoComplete.prototype.animSpeed = 0.3;
 288
 289 /**
 290  * Whether or not to force the user's selection to match one of the query
 291  * results. Enabling this feature essentially transforms the input field into a
 292  * &lt;select&gt; field. This feature is not recommended with delimiter character(s)
 293  * defined.
 294  *
 295  * @property forceSelection
 296  * @type Boolean
 297  * @default false
 298  */
 299 YAHOO.widget.AutoComplete.prototype.forceSelection = false;
 300
 301 /**
 302  * Whether or not to allow browsers to cache user-typed input in the input
 303  * field. Disabling this feature will prevent the widget from setting the
 304  * autocomplete="off" on the input field. When autocomplete="off"
 305  * and users click the back button after form submission, user-typed input can
 306  * be prefilled by the browser from its cache. This caching of user input may
 307  * not be desired for sensitive data, such as credit card numbers, in which
 308  * case, implementers should consider setting allowBrowserAutocomplete to false.
 309  *
 310  * @property allowBrowserAutocomplete
 311  * @type Boolean
 312  * @default true
 313  */
 314 YAHOO.widget.AutoComplete.prototype.allowBrowserAutocomplete = true;
 315
 316 /**
 317  * Whether or not the results container should always be displayed.
 318  * Enabling this feature displays the container when the widget is instantiated
 319  * and prevents the toggling of the container to a collapsed state.
 320  *
 321  * @property alwaysShowContainer
 322  * @type Boolean
 323  * @default false
 324  */
 325 YAHOO.widget.AutoComplete.prototype.alwaysShowContainer = false;
 326
 327 /**
 328  * Whether or not to use an iFrame to layer over Windows form elements in
 329  * IE. Set to true only when the results container will be on top of a
 330  * &lt;select&gt; field in IE and thus exposed to the IE z-index bug (i.e.,
 331  * 5.5 < IE < 7).
 332  *
 333  * @property useIFrame
 334  * @type Boolean
 335  * @default false
 336  */
 337 YAHOO.widget.AutoComplete.prototype.useIFrame = false;
 338
 339 /**
 340  * Whether or not the results container should have a shadow.
 341  *
 342  * @property useShadow
 343  * @type Boolean
 344  * @default false
 345  */
 346 YAHOO.widget.AutoComplete.prototype.useShadow = false;
 347
 348 /////////////////////////////////////////////////////////////////////////////
 349 //
 350 // Public methods
 351 //
 352 /////////////////////////////////////////////////////////////////////////////
 353
 354  /**
 355  * Public accessor to the unique name of the AutoComplete instance.
 356  *
 357  * @method toString
 358  * @return {String} Unique name of the AutoComplete instance.
 359  */
 360 YAHOO.widget.AutoComplete.prototype.toString = function() {
 361     return "AutoComplete " + this._sName;
 362 };
 363
 364  /**
 365  * Returns true if container is in an expanded state, false otherwise.
 366  *
 367  * @method isContainerOpen
 368  * @return {Boolean} Returns true if container is in an expanded state, false otherwise.
 369  */
 370 YAHOO.widget.AutoComplete.prototype.isContainerOpen = function() {
 371     return this._bContainerOpen;
 372 };
 373
 374 /**
 375  * Public accessor to the internal array of DOM &lt;li&gt; elements that
 376  * display query results within the results container.
 377  *
 378  * @method getListItems
 379  * @return {HTMLElement[]} Array of &lt;li&gt; elements within the results container.
 380  */
 381 YAHOO.widget.AutoComplete.prototype.getListItems = function() {
 382     return this._aListItems;
 383 };
 384
 385 /**
 386  * Public accessor to the data held in an &lt;li&gt; element of the
 387  * results container.
 388  *
 389  * @method getListItemData
 390  * @return {Object | Object[]} Object or array of result data or null
 391  */
 392 YAHOO.widget.AutoComplete.prototype.getListItemData = function(oListItem) {
 393     if(oListItem._oResultData) {
 394         return oListItem._oResultData;
 395     }
 396     else {
 397         return false;
 398     }
 399 };
 400
 401 /**
 402  * Sets HTML markup for the results container header. This markup will be
 403  * inserted within a &lt;div&gt; tag with a class of "yui-ac-hd".
 404  *
 405  * @method setHeader
 406  * @param sHeader {String} HTML markup for results container header.
 407  */
 408 YAHOO.widget.AutoComplete.prototype.setHeader = function(sHeader) {
 409     if(this._elHeader) {
 410         var elHeader = this._elHeader;
 411         if(sHeader) {
 412             elHeader.innerHTML = sHeader;
 413             elHeader.style.display = "block";
 414         }
 415         else {
 416             elHeader.innerHTML = "";
 417             elHeader.style.display = "none";
 418         }
 419     }
 420 };
 421
 422 /**
 423  * Sets HTML markup for the results container footer. This markup will be
 424  * inserted within a &lt;div&gt; tag with a class of "yui-ac-ft".
 425  *
 426  * @method setFooter
 427  * @param sFooter {String} HTML markup for results container footer.
 428  */
 429 YAHOO.widget.AutoComplete.prototype.setFooter = function(sFooter) {
 430     if(this._elFooter) {
 431         var elFooter = this._elFooter;
 432         if(sFooter) {
 433                 elFooter.innerHTML = sFooter;
 434                 elFooter.style.display = "block";
 435         }
 436         else {
 437             elFooter.innerHTML = "";
 438             elFooter.style.display = "none";
 439         }
 440     }
 441 };
 442
 443 /**
 444  * Sets HTML markup for the results container body. This markup will be
 445  * inserted within a &lt;div&gt; tag with a class of "yui-ac-bd".
 446  *
 447  * @method setBody
 448  * @param sBody {String} HTML markup for results container body.
 449  */
 450 YAHOO.widget.AutoComplete.prototype.setBody = function(sBody) {
 451     if(this._elBody) {
 452         var elBody = this._elBody;
 453         if(sBody) {
 454                 elBody.innerHTML = sBody;
 455                 elBody.style.display = "block";
 456                 elBody.style.display = "block";
 457         }
 458         else {
 459             elBody.innerHTML = "";
 460             elBody.style.display = "none";
 461         }
 462         this._maxResultsDisplayed = 0;
 463     }
 464 };
 465
 466 /**
 467  * Overridable method that converts a result item object into HTML markup
 468  * for display. Return data values are accessible via the oResultItem object,
 469  * and the key return value will always be oResultItem[0]. Markup will be
 470  * displayed within &lt;li&gt; element tags in the container.
 471  *
 472  * @method formatResult
 473  * @param oResultItem {Object} Result item representing one query result. Data is held in an array.
 474  * @param sQuery {String} The current query string.
 475  * @return {String} HTML markup of formatted result data.
 476  */
 477 YAHOO.widget.AutoComplete.prototype.formatResult = function(oResultItem, sQuery) {
 478     var sResult = oResultItem[0];
 479     if(sResult) {
 480         return sResult;
 481     }
 482     else {
 483         return "";
 484     }
 485 };
 486
 487 /**
 488  * Overridable method called before container expands allows implementers to access data
 489  * and DOM elements.
 490  *
 491  * @method doBeforeExpandContainer
 492  * @param elTextbox {HTMLElement} The text input box.
 493  * @param elContainer {HTMLElement} The container element.
 494  * @param sQuery {String} The query string.
 495  * @param aResults {Object[]}  An array of query results.
 496  * @return {Boolean} Return true to continue expanding container, false to cancel the expand.
 497  */
 498 YAHOO.widget.AutoComplete.prototype.doBeforeExpandContainer = function(elTextbox, elContainer, sQuery, aResults) {
 499     return true;
 500 };
 501
 502 /**
 503  * Makes query request to the DataSource.
 504  *
 505  * @method sendQuery
 506  * @param sQuery {String} Query string.
 507  */
 508 YAHOO.widget.AutoComplete.prototype.sendQuery = function(sQuery) {
 509     this._sendQuery(sQuery);
 510 };
 511
 512 /**
 513  * Overridable method gives implementers access to the query before it gets sent.
 514  *
 515  * @method doBeforeSendQuery
 516  * @param sQuery {String} Query string.
 517  * @return {String} Query string.
 518  */
 519 YAHOO.widget.AutoComplete.prototype.doBeforeSendQuery = function(sQuery) {
 520     return sQuery;
 521 };
 522
 523 /**
 524  * Nulls out the entire AutoComplete instance and related objects, removes attached
 525  * event listeners, and clears out DOM elements inside the container. After
 526  * calling this method, the instance reference should be expliclitly nulled by
 527  * implementer, as in myDataTable = null. Use with caution!
 528  *
 529  * @method destroy
 530  */
 531 YAHOO.widget.AutoComplete.prototype.destroy = function() {
 532     var instanceName = this.toString();
 533     var elInput = this._elTextbox;
 534     var elContainer = this._elContainer;
 535
 536     // Unhook custom events
 537     this.textboxFocusEvent.unsubscribeAll();
 538     this.textboxKeyEvent.unsubscribeAll();
 539     this.dataRequestEvent.unsubscribeAll();
 540     this.dataReturnEvent.unsubscribeAll();
 541     this.dataErrorEvent.unsubscribeAll();
 542     this.containerExpandEvent.unsubscribeAll();
 543     this.typeAheadEvent.unsubscribeAll();
 544     this.itemMouseOverEvent.unsubscribeAll();
 545     this.itemMouseOutEvent.unsubscribeAll();
 546     this.itemArrowToEvent.unsubscribeAll();
 547     this.itemArrowFromEvent.unsubscribeAll();
 548     this.itemSelectEvent.unsubscribeAll();
 549     this.unmatchedItemSelectEvent.unsubscribeAll();
 550     this.selectionEnforceEvent.unsubscribeAll();
 551     this.containerCollapseEvent.unsubscribeAll();
 552     this.textboxBlurEvent.unsubscribeAll();
 553
 554     // Unhook DOM events
 555     YAHOO.util.Event.purgeElement(elInput, true);
 556     YAHOO.util.Event.purgeElement(elContainer, true);
 557
 558     // Remove DOM elements
 559     elContainer.innerHTML = "";
 560
 561     // Null out objects
 562     for(var key in this) {
 563         if(YAHOO.lang.hasOwnProperty(this, key)) {
 564             this[key] = null;
 565         }
 566     }
 567
 568     YAHOO.log("AutoComplete instance destroyed: " + instanceName);
 569 };
 570
 571 /////////////////////////////////////////////////////////////////////////////
 572 //
 573 // Public events
 574 //
 575 /////////////////////////////////////////////////////////////////////////////
 576
 577 /**
 578  * Fired when the input field receives focus.
 579  *
 580  * @event textboxFocusEvent
 581  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
 582  */
 583 YAHOO.widget.AutoComplete.prototype.textboxFocusEvent = null;
 584
 585 /**
 586  * Fired when the input field receives key input.
 587  *
 588  * @event textboxKeyEvent
 589  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
 590  * @param nKeycode {Number} The keycode number.
 591  */
 592 YAHOO.widget.AutoComplete.prototype.textboxKeyEvent = null;
 593
 594 /**
 595  * Fired when the AutoComplete instance makes a query to the DataSource.
 596  *
 597  * @event dataRequestEvent
 598  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
 599  * @param sQuery {String} The query string.
 600  */
 601 YAHOO.widget.AutoComplete.prototype.dataRequestEvent = null;
 602
 603 /**
 604  * Fired when the AutoComplete instance receives query results from the data
 605  * source.
 606  *
 607  * @event dataReturnEvent
 608  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
 609  * @param sQuery {String} The query string.
 610  * @param aResults {Object[]} Results array.
 611  */
 612 YAHOO.widget.AutoComplete.prototype.dataReturnEvent = null;
 613
 614 /**
 615  * Fired when the AutoComplete instance does not receive query results from the
 616  * DataSource due to an error.
 617  *
 618  * @event dataErrorEvent
 619  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
 620  * @param sQuery {String} The query string.
 621  */
 622 YAHOO.widget.AutoComplete.prototype.dataErrorEvent = null;
 623
 624 /**
 625  * Fired when the results container is expanded.
 626  *
 627  * @event containerExpandEvent
 628  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
 629  */
 630 YAHOO.widget.AutoComplete.prototype.containerExpandEvent = null;
 631
 632 /**
 633  * Fired when the input field has been prefilled by the type-ahead
 634  * feature.
 635  *
 636  * @event typeAheadEvent
 637  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
 638  * @param sQuery {String} The query string.
 639  * @param sPrefill {String} The prefill string.
 640  */
 641 YAHOO.widget.AutoComplete.prototype.typeAheadEvent = null;
 642
 643 /**
 644  * Fired when result item has been moused over.
 645  *
 646  * @event itemMouseOverEvent
 647  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
 648  * @param elItem {HTMLElement} The &lt;li&gt element item moused to.
 649  */
 650 YAHOO.widget.AutoComplete.prototype.itemMouseOverEvent = null;
 651
 652 /**
 653  * Fired when result item has been moused out.
 654  *
 655  * @event itemMouseOutEvent
 656  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
 657  * @param elItem {HTMLElement} The &lt;li&gt; element item moused from.
 658  */
 659 YAHOO.widget.AutoComplete.prototype.itemMouseOutEvent = null;
 660
 661 /**
 662  * Fired when result item has been arrowed to.
 663  *
 664  * @event itemArrowToEvent
 665  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
 666  * @param elItem {HTMLElement} The &lt;li&gt; element item arrowed to.
 667  */
 668 YAHOO.widget.AutoComplete.prototype.itemArrowToEvent = null;
 669
 670 /**
 671  * Fired when result item has been arrowed away from.
 672  *
 673  * @event itemArrowFromEvent
 674  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
 675  * @param elItem {HTMLElement} The &lt;li&gt; element item arrowed from.
 676  */
 677 YAHOO.widget.AutoComplete.prototype.itemArrowFromEvent = null;
 678
 679 /**
 680  * Fired when an item is selected via mouse click, ENTER key, or TAB key.
 681  *
 682  * @event itemSelectEvent
 683  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
 684  * @param elItem {HTMLElement} The selected &lt;li&gt; element item.
 685  * @param oData {Object} The data returned for the item, either as an object,
 686  * or mapped from the schema into an array.
 687  */
 688 YAHOO.widget.AutoComplete.prototype.itemSelectEvent = null;
 689
 690 /**
 691  * Fired when a user selection does not match any of the displayed result items.
 692  *
 693  * @event unmatchedItemSelectEvent
 694  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
 695  */
 696 YAHOO.widget.AutoComplete.prototype.unmatchedItemSelectEvent = null;
 697
 698 /**
 699  * Fired if forceSelection is enabled and the user's input has been cleared
 700  * because it did not match one of the returned query results.
 701  *
 702  * @event selectionEnforceEvent
 703  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
 704  */
 705 YAHOO.widget.AutoComplete.prototype.selectionEnforceEvent = null;
 706
 707 /**
 708  * Fired when the results container is collapsed.
 709  *
 710  * @event containerCollapseEvent
 711  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
 712  */
 713 YAHOO.widget.AutoComplete.prototype.containerCollapseEvent = null;
 714
 715 /**
 716  * Fired when the input field loses focus.
 717  *
 718  * @event textboxBlurEvent
 719  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
 720  */
 721 YAHOO.widget.AutoComplete.prototype.textboxBlurEvent = null;
 722
 723 /////////////////////////////////////////////////////////////////////////////
 724 //
 725 // Private member variables
 726 //
 727 /////////////////////////////////////////////////////////////////////////////
 728
 729 /**
 730  * Internal class variable to index multiple AutoComplete instances.
 731  *
 732  * @property _nIndex
 733  * @type Number
 734  * @default 0
 735  * @private
 736  */
 737 YAHOO.widget.AutoComplete._nIndex = 0;
 738
 739 /**
 740  * Name of AutoComplete instance.
 741  *
 742  * @property _sName
 743  * @type String
 744  * @private
 745  */
 746 YAHOO.widget.AutoComplete.prototype._sName = null;
 747
 748 /**
 749  * Text input field DOM element.
 750  *
 751  * @property _elTextbox
 752  * @type HTMLElement
 753  * @private
 754  */
 755 YAHOO.widget.AutoComplete.prototype._elTextbox = null;
 756
 757 /**
 758  * Container DOM element.
 759  *
 760  * @property _elContainer
 761  * @type HTMLElement
 762  * @private
 763  */
 764 YAHOO.widget.AutoComplete.prototype._elContainer = null;
 765
 766 /**
 767  * Reference to content element within container element.
 768  *
 769  * @property _elContent
 770  * @type HTMLElement
 771  * @private
 772  */
 773 YAHOO.widget.AutoComplete.prototype._elContent = null;
 774
 775 /**
 776  * Reference to header element within content element.
 777  *
 778  * @property _elHeader
 779  * @type HTMLElement
 780  * @private
 781  */
 782 YAHOO.widget.AutoComplete.prototype._elHeader = null;
 783
 784 /**
 785  * Reference to body element within content element.
 786  *
 787  * @property _elBody
 788  * @type HTMLElement
 789  * @private
 790  */
 791 YAHOO.widget.AutoComplete.prototype._elBody = null;
 792
 793 /**
 794  * Reference to footer element within content element.
 795  *
 796  * @property _elFooter
 797  * @type HTMLElement
 798  * @private
 799  */
 800 YAHOO.widget.AutoComplete.prototype._elFooter = null;
 801
 802 /**
 803  * Reference to shadow element within container element.
 804  *
 805  * @property _elShadow
 806  * @type HTMLElement
 807  * @private
 808  */
 809 YAHOO.widget.AutoComplete.prototype._elShadow = null;
 810
 811 /**
 812  * Reference to iframe element within container element.
 813  *
 814  * @property _elIFrame
 815  * @type HTMLElement
 816  * @private
 817  */
 818 YAHOO.widget.AutoComplete.prototype._elIFrame = null;
 819
 820 /**
 821  * Whether or not the input field is currently in focus. If query results come back
 822  * but the user has already moved on, do not proceed with auto complete behavior.
 823  *
 824  * @property _bFocused
 825  * @type Boolean
 826  * @private
 827  */
 828 YAHOO.widget.AutoComplete.prototype._bFocused = true;
 829
 830 /**
 831  * Animation instance for container expand/collapse.
 832  *
 833  * @property _oAnim
 834  * @type Boolean
 835  * @private
 836  */
 837 YAHOO.widget.AutoComplete.prototype._oAnim = null;
 838
 839 /**
 840  * Whether or not the results container is currently open.
 841  *
 842  * @property _bContainerOpen
 843  * @type Boolean
 844  * @private
 845  */
 846 YAHOO.widget.AutoComplete.prototype._bContainerOpen = false;
 847
 848 /**
 849  * Whether or not the mouse is currently over the results
 850  * container. This is necessary in order to prevent clicks on container items
 851  * from being text input field blur events.
 852  *
 853  * @property _bOverContainer
 854  * @type Boolean
 855  * @private
 856  */
 857 YAHOO.widget.AutoComplete.prototype._bOverContainer = false;
 858
 859 /**
 860  * Array of &lt;li&gt; elements references that contain query results within the
 861  * results container.
 862  *
 863  * @property _aListItems
 864  * @type HTMLElement[]
 865  * @private
 866  */
 867 YAHOO.widget.AutoComplete.prototype._aListItems = null;
 868
 869 /**
 870  * Number of &lt;li&gt; elements currently displayed in results container.
 871  *
 872  * @property _nDisplayedItems
 873  * @type Number
 874  * @private
 875  */
 876 YAHOO.widget.AutoComplete.prototype._nDisplayedItems = 0;
 877
 878 /**
 879  * Internal count of &lt;li&gt; elements displayed and hidden in results container.
 880  *
 881  * @property _maxResultsDisplayed
 882  * @type Number
 883  * @private
 884  */
 885 YAHOO.widget.AutoComplete.prototype._maxResultsDisplayed = 0;
 886
 887 /**
 888  * Current query string
 889  *
 890  * @property _sCurQuery
 891  * @type String
 892  * @private
 893  */
 894 YAHOO.widget.AutoComplete.prototype._sCurQuery = null;
 895
 896 /**
 897  * Past queries this session (for saving delimited queries).
 898  *
 899  * @property _sSavedQuery
 900  * @type String
 901  * @private
 902  */
 903 YAHOO.widget.AutoComplete.prototype._sSavedQuery = null;
 904
 905 /**
 906  * Pointer to the currently highlighted &lt;li&gt; element in the container.
 907  *
 908  * @property _oCurItem
 909  * @type HTMLElement
 910  * @private
 911  */
 912 YAHOO.widget.AutoComplete.prototype._oCurItem = null;
 913
 914 /**
 915  * Whether or not an item has been selected since the container was populated
 916  * with results. Reset to false by _populateList, and set to true when item is
 917  * selected.
 918  *
 919  * @property _bItemSelected
 920  * @type Boolean
 921  * @private
 922  */
 923 YAHOO.widget.AutoComplete.prototype._bItemSelected = false;
 924
 925 /**
 926  * Key code of the last key pressed in textbox.
 927  *
 928  * @property _nKeyCode
 929  * @type Number
 930  * @private
 931  */
 932 YAHOO.widget.AutoComplete.prototype._nKeyCode = null;
 933
 934 /**
 935  * Delay timeout ID.
 936  *
 937  * @property _nDelayID
 938  * @type Number
 939  * @private
 940  */
 941 YAHOO.widget.AutoComplete.prototype._nDelayID = -1;
 942
 943 /**
 944  * Src to iFrame used when useIFrame = true. Supports implementations over SSL
 945  * as well.
 946  *
 947  * @property _iFrameSrc
 948  * @type String
 949  * @private
 950  */
 951 YAHOO.widget.AutoComplete.prototype._iFrameSrc = "javascript:false;";
 952
 953 /**
 954  * For users typing via certain IMEs, queries must be triggered by intervals,
 955  * since key events yet supported across all browsers for all IMEs.
 956  *
 957  * @property _queryInterval
 958  * @type Object
 959  * @private
 960  */
 961 YAHOO.widget.AutoComplete.prototype._queryInterval = null;
 962
 963 /**
 964  * Internal tracker to last known textbox value, used to determine whether or not
 965  * to trigger a query via interval for certain IME users.
 966  *
 967  * @event _sLastTextboxValue
 968  * @type String
 969  * @private
 970  */
 971 YAHOO.widget.AutoComplete.prototype._sLastTextboxValue = null;
 972
 973 /////////////////////////////////////////////////////////////////////////////
 974 //
 975 // Private methods
 976 //
 977 /////////////////////////////////////////////////////////////////////////////
 978
 979 /**
 980  * Updates and validates latest public config properties.
 981  *
 982  * @method __initProps
 983  * @private
 984  */
 985 YAHOO.widget.AutoComplete.prototype._initProps = function() {
 986     // Correct any invalid values
 987     var minQueryLength = this.minQueryLength;
 988     if(!YAHOO.lang.isNumber(minQueryLength)) {
 989         this.minQueryLength = 1;
 990     }
 991     var maxResultsDisplayed = this.maxResultsDisplayed;
 992     if(!YAHOO.lang.isNumber(maxResultsDisplayed) || (maxResultsDisplayed < 1)) {
 993         this.maxResultsDisplayed = 10;
 994     }
 995     var queryDelay = this.queryDelay;
 996     if(!YAHOO.lang.isNumber(queryDelay) || (queryDelay < 0)) {
 997         this.queryDelay = 0.2;
 998     }
 999     var delimChar = this.delimChar;
1000     if(YAHOO.lang.isString(delimChar) && (delimChar.length > 0)) {
1001         this.delimChar = [delimChar];
1002     }
1003     else if(!YAHOO.lang.isArray(delimChar)) {
1004         this.delimChar = null;
1005     }
1006     var animSpeed = this.animSpeed;
1007     if((this.animHoriz || this.animVert) && YAHOO.util.Anim) {
1008         if(!YAHOO.lang.isNumber(animSpeed) || (animSpeed < 0)) {
1009             this.animSpeed = 0.3;
1010         }
1011         if(!this._oAnim ) {
1012             this._oAnim = new YAHOO.util.Anim(this._elContent, {}, this.animSpeed);
1013         }
1014         else {
1015             this._oAnim.duration = this.animSpeed;
1016         }
1017     }
1018     if(this.forceSelection && delimChar) {
1019         YAHOO.log("The forceSelection feature has been enabled with delimChar defined.","warn", this.toString());
1020     }
1021 };
1022
1023 /**
1024  * Initializes the results container helpers if they are enabled and do
1025  * not exist
1026  *
1027  * @method _initContainerHelpers
1028  * @private
1029  */
1030 YAHOO.widget.AutoComplete.prototype._initContainerHelpers = function() {
1031     if(this.useShadow && !this._elShadow) {
1032         var elShadow = document.createElement("div");
1033         elShadow.className = "yui-ac-shadow";
1034         this._elShadow = this._elContainer.appendChild(elShadow);
1035     }
1036     if(this.useIFrame && !this._elIFrame) {
1037         var elIFrame = document.createElement("iframe");
1038         elIFrame.src = this._iFrameSrc;
1039         elIFrame.frameBorder = 0;
1040         elIFrame.scrolling = "no";
1041         elIFrame.style.position = "absolute";
1042         elIFrame.style.width = "100%";
1043         elIFrame.style.height = "100%";
1044         elIFrame.tabIndex = -1;
1045         this._elIFrame = this._elContainer.appendChild(elIFrame);
1046     }
1047 };
1048
1049 /**
1050  * Initializes the results container once at object creation
1051  *
1052  * @method _initContainer
1053  * @private
1054  */
1055 YAHOO.widget.AutoComplete.prototype._initContainer = function() {
1056     YAHOO.util.Dom.addClass(this._elContainer, "yui-ac-container");
1057
1058     if(!this._elContent) {
1059         // The elContent div helps size the iframe and shadow properly
1060         var elContent = document.createElement("div");
1061         elContent.className = "yui-ac-content";
1062         elContent.style.display = "none";
1063         this._elContent = this._elContainer.appendChild(elContent);
1064
1065         var elHeader = document.createElement("div");
1066         elHeader.className = "yui-ac-hd";
1067         elHeader.style.display = "none";
1068         this._elHeader = this._elContent.appendChild(elHeader);
1069
1070         var elBody = document.createElement("div");
1071         elBody.className = "yui-ac-bd";
1072         this._elBody = this._elContent.appendChild(elBody);
1073
1074         var elFooter = document.createElement("div");
1075         elFooter.className = "yui-ac-ft";
1076         elFooter.style.display = "none";
1077         this._elFooter = this._elContent.appendChild(elFooter);
1078     }
1079     else {
1080         YAHOO.log("Could not initialize the container","warn",this.toString());
1081     }
1082 };
1083
1084 /**
1085  * Clears out contents of container body and creates up to
1086  * YAHOO.widget.AutoComplete#maxResultsDisplayed &lt;li&gt; elements in an
1087  * &lt;ul&gt; element.
1088  *
1089  * @method _initList
1090  * @private
1091  */
1092 YAHOO.widget.AutoComplete.prototype._initList = function() {
1093     this._aListItems = [];
1094     while(this._elBody.hasChildNodes()) {
1095         var oldListItems = this.getListItems();
1096         if(oldListItems) {
1097             for(var oldi = oldListItems.length-1; oldi >= 0; oldi--) {
1098                 oldListItems[oldi] = null;
1099             }
1100         }
1101         this._elBody.innerHTML = "";
1102     }
1103
1104     var oList = document.createElement("ul");
1105     oList = this._elBody.appendChild(oList);
1106     for(var i=0; i<this.maxResultsDisplayed; i++) {
1107         var oItem = document.createElement("li");
1108         oItem = oList.appendChild(oItem);
1109         this._aListItems[i] = oItem;
1110         this._initListItem(oItem, i);
1111     }
1112     this._maxResultsDisplayed = this.maxResultsDisplayed;
1113 };
1114
1115 /**
1116  * Initializes each &lt;li&gt; element in the container list.
1117  *
1118  * @method _initListItem
1119  * @param oItem {HTMLElement} The &lt;li&gt; DOM element.
1120  * @param nItemIndex {Number} The index of the element.
1121  * @private
1122  */
1123 YAHOO.widget.AutoComplete.prototype._initListItem = function(oItem, nItemIndex) {
1124     var oSelf = this;
1125     oItem.style.display = "none";
1126     oItem._nItemIndex = nItemIndex;
1127
1128     oItem.mouseover = oItem.mouseout = oItem.onclick = null;
1129     YAHOO.util.Event.addListener(oItem,"mouseover",oSelf._onItemMouseover,oSelf);
1130     YAHOO.util.Event.addListener(oItem,"mouseout",oSelf._onItemMouseout,oSelf);
1131     YAHOO.util.Event.addListener(oItem,"click",oSelf._onItemMouseclick,oSelf);
1132 };
1133
1134 /**
1135  * Enables interval detection for  Korean IME support.
1136  *
1137  * @method _onIMEDetected
1138  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
1139  * @private
1140  */
1141 YAHOO.widget.AutoComplete.prototype._onIMEDetected = function(oSelf) {
1142     oSelf._enableIntervalDetection();
1143 };
1144
1145 /**
1146  * Enables query triggers based on text input detection by intervals (rather
1147  * than by key events).
1148  *
1149  * @method _enableIntervalDetection
1150  * @private
1151  */
1152 YAHOO.widget.AutoComplete.prototype._enableIntervalDetection = function() {
1153     var currValue = this._elTextbox.value;
1154     var lastValue = this._sLastTextboxValue;
1155     if(currValue != lastValue) {
1156         this._sLastTextboxValue = currValue;
1157         this._sendQuery(currValue);
1158     }
1159 };
1160
1161
1162 /**
1163  * Cancels text input detection by intervals.
1164  *
1165  * @method _cancelIntervalDetection
1166  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
1167  * @private
1168  */
1169 YAHOO.widget.AutoComplete.prototype._cancelIntervalDetection = function(oSelf) {
1170     if(oSelf._queryInterval) {
1171         clearInterval(oSelf._queryInterval);
1172     }
1173 };
1174
1175
1176 /**
1177  * Whether or not key is functional or should be ignored. Note that the right
1178  * arrow key is NOT an ignored key since it triggers queries for certain intl
1179  * charsets.
1180  *
1181  * @method _isIgnoreKey
1182  * @param nKeycode {Number} Code of key pressed.
1183  * @return {Boolean} True if key should be ignored, false otherwise.
1184  * @private
1185  */
1186 YAHOO.widget.AutoComplete.prototype._isIgnoreKey = function(nKeyCode) {
1187     if((nKeyCode == 9) || (nKeyCode == 13)  || // tab, enter
1188             (nKeyCode == 16) || (nKeyCode == 17) || // shift, ctl
1189             (nKeyCode >= 18 && nKeyCode <= 20) || // alt,pause/break,caps lock
1190             (nKeyCode == 27) || // esc
1191             (nKeyCode >= 33 && nKeyCode <= 35) || // page up,page down,end
1192             /*(nKeyCode >= 36 && nKeyCode <= 38) || // home,left,up
1193             (nKeyCode == 40) || // down*/
1194             (nKeyCode >= 36 && nKeyCode <= 40) || // home,left,up, right, down
1195             (nKeyCode >= 44 && nKeyCode <= 45)) { // print screen,insert
1196         return true;
1197     }
1198     return false;
1199 };
1200
1201 /**
1202  * Makes query request to the DataSource.
1203  *
1204  * @method _sendQuery
1205  * @param sQuery {String} Query string.
1206  * @private
1207  */
1208 YAHOO.widget.AutoComplete.prototype._sendQuery = function(sQuery) {
1209     // Widget has been effectively turned off
1210     if(this.minQueryLength == -1) {
1211         this._toggleContainer(false);
1212         YAHOO.log("Property minQueryLength is set to -1", "info", this.toString());
1213         return;
1214     }
1215     // Delimiter has been enabled
1216     var aDelimChar = (this.delimChar) ? this.delimChar : null;
1217     if(aDelimChar) {
1218         // Loop through all possible delimiters and find the latest one
1219         // A " " may be a false positive if they are defined as delimiters AND
1220         // are used to separate delimited queries
1221         var nDelimIndex = -1;
1222         for(var i = aDelimChar.length-1; i >= 0; i--) {
1223             var nNewIndex = sQuery.lastIndexOf(aDelimChar[i]);
1224             if(nNewIndex > nDelimIndex) {
1225                 nDelimIndex = nNewIndex;
1226             }
1227         }
1228         // If we think the last delimiter is a space (" "), make sure it is NOT
1229         // a false positive by also checking the char directly before it
1230         if(aDelimChar[i] == " ") {
1231             for (var j = aDelimChar.length-1; j >= 0; j--) {
1232                 if(sQuery[nDelimIndex - 1] == aDelimChar[j]) {
1233                     nDelimIndex--;
1234                     break;
1235                 }
1236             }
1237         }
1238         // A delimiter has been found so extract the latest query
1239         if(nDelimIndex > -1) {
1240             var nQueryStart = nDelimIndex + 1;
1241             // Trim any white space from the beginning...
1242             while(sQuery.charAt(nQueryStart) == " ") {
1243                 nQueryStart += 1;
1244             }
1245             // ...and save the rest of the string for later
1246             this._sSavedQuery = sQuery.substring(0,nQueryStart);
1247             // Here is the query itself
1248             sQuery = sQuery.substr(nQueryStart);
1249         }
1250         else if(sQuery.indexOf(this._sSavedQuery) < 0){
1251             this._sSavedQuery = null;
1252         }
1253     }
1254
1255     // Don't search queries that are too short
1256     if((sQuery && (sQuery.length < this.minQueryLength)) || (!sQuery && this.minQueryLength > 0)) {
1257         if(this._nDelayID != -1) {
1258             clearTimeout(this._nDelayID);
1259         }
1260         this._toggleContainer(false);
1261         YAHOO.log("Query \"" + sQuery + "\" is too short", "info", this.toString());
1262         return;
1263     }
1264
1265     sQuery = encodeURIComponent(sQuery);
1266     this._nDelayID = -1;    // Reset timeout ID because request has been made
1267     sQuery = this.doBeforeSendQuery(sQuery);
1268     this.dataRequestEvent.fire(this, sQuery);
1269     YAHOO.log("Sending query \"" + sQuery + "\"", "info", this.toString());
1270     this.dataSource.getResults(this._populateList, sQuery, this);
1271 };
1272
1273 /**
1274  * Populates the array of &lt;li&gt; elements in the container with query
1275  * results. This method is passed to YAHOO.widget.DataSource#getResults as a
1276  * callback function so results from the DataSource instance are returned to the
1277  * AutoComplete instance.
1278  *
1279  * @method _populateList
1280  * @param sQuery {String} The query string.
1281  * @param aResults {Object[]} An array of query result objects from the DataSource.
1282  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
1283  * @private
1284  */
1285 YAHOO.widget.AutoComplete.prototype._populateList = function(sQuery, aResults, oSelf) {
1286     if(aResults === null) {
1287         oSelf.dataErrorEvent.fire(oSelf, sQuery);
1288     }
1289     if(!oSelf._bFocused || !aResults) {
1290         YAHOO.log("Could not populate list", "info", oSelf.toString());
1291         return;
1292     }
1293
1294     var isOpera = (navigator.userAgent.toLowerCase().indexOf("opera") != -1);
1295     var contentStyle = oSelf._elContent.style;
1296     contentStyle.width = (!isOpera) ? null : "";
1297     contentStyle.height = (!isOpera) ? null : "";
1298
1299     var sCurQuery = decodeURIComponent(sQuery);
1300     oSelf._sCurQuery = sCurQuery;
1301     oSelf._bItemSelected = false;
1302
1303     if(oSelf._maxResultsDisplayed != oSelf.maxResultsDisplayed) {
1304         oSelf._initList();
1305     }
1306
1307     var nItems = Math.min(aResults.length,oSelf.maxResultsDisplayed);
1308     oSelf._nDisplayedItems = nItems;
1309     if(nItems > 0) {
1310         oSelf._initContainerHelpers();
1311         var aItems = oSelf._aListItems;
1312
1313         // Fill items with data
1314         for(var i = nItems-1; i >= 0; i--) {
1315             var oItemi = aItems[i];
1316             var oResultItemi = aResults[i];
1317             oItemi.innerHTML = oSelf.formatResult(oResultItemi, sCurQuery);
1318             oItemi.style.display = "list-item";
1319             oItemi._sResultKey = oResultItemi[0];
1320             oItemi._oResultData = oResultItemi;
1321
1322         }
1323
1324         // Empty out remaining items if any
1325         for(var j = aItems.length-1; j >= nItems ; j--) {
1326             var oItemj = aItems[j];
1327             oItemj.innerHTML = null;
1328             oItemj.style.display = "none";
1329             oItemj._sResultKey = null;
1330             oItemj._oResultData = null;
1331         }
1332
1333         // Expand the container
1334         var ok = oSelf.doBeforeExpandContainer(oSelf._elTextbox, oSelf._elContainer, sQuery, aResults);
1335         oSelf._toggleContainer(ok);
1336
1337         if(oSelf.autoHighlight) {
1338             // Go to the first item
1339             var oFirstItem = aItems[0];
1340             oSelf._toggleHighlight(oFirstItem,"to");
1341             oSelf.itemArrowToEvent.fire(oSelf, oFirstItem);
1342             YAHOO.log("Arrowed to first item", "info", oSelf.toString());
1343             oSelf._typeAhead(oFirstItem,sQuery);
1344         }
1345         else {
1346             oSelf._oCurItem = null;
1347         }
1348     }
1349     else {
1350         oSelf._toggleContainer(false);
1351     }
1352     oSelf.dataReturnEvent.fire(oSelf, sQuery, aResults);
1353     YAHOO.log("Container populated with list items", "info", oSelf.toString());
1354
1355 };
1356
1357 /**
1358  * When forceSelection is true and the user attempts
1359  * leave the text input box without selecting an item from the query results,
1360  * the user selection is cleared.
1361  *
1362  * @method _clearSelection
1363  * @private
1364  */
1365 YAHOO.widget.AutoComplete.prototype._clearSelection = function() {
1366     var sValue = this._elTextbox.value;
1367     var sChar = (this.delimChar) ? this.delimChar[0] : null;
1368     var nIndex = (sChar) ? sValue.lastIndexOf(sChar, sValue.length-2) : -1;
1369     if(nIndex > -1) {
1370         this._elTextbox.value = sValue.substring(0,nIndex);
1371     }
1372     else {
1373          this._elTextbox.value = "";
1374     }
1375     this._sSavedQuery = this._elTextbox.value;
1376
1377     // Fire custom event
1378     this.selectionEnforceEvent.fire(this);
1379     YAHOO.log("Selection enforced", "info", this.toString());
1380 };
1381
1382 /**
1383  * Whether or not user-typed value in the text input box matches any of the
1384  * query results.
1385  *
1386  * @method _textMatchesOption
1387  * @return {HTMLElement} Matching list item element if user-input text matches
1388  * a result, null otherwise.
1389  * @private
1390  */
1391 YAHOO.widget.AutoComplete.prototype._textMatchesOption = function() {
1392     var foundMatch = null;
1393
1394     for(var i = this._nDisplayedItems-1; i >= 0 ; i--) {
1395         var oItem = this._aListItems[i];
1396         var sMatch = oItem._sResultKey.toLowerCase();
1397         if(sMatch == this._sCurQuery.toLowerCase()) {
1398             foundMatch = oItem;
1399             break;
1400         }
1401     }
1402     return(foundMatch);
1403 };
1404
1405 /**
1406  * Updates in the text input box with the first query result as the user types,
1407  * selecting the substring that the user has not typed.
1408  *
1409  * @method _typeAhead
1410  * @param oItem {HTMLElement} The &lt;li&gt; element item whose data populates the input field.
1411  * @param sQuery {String} Query string.
1412  * @private
1413  */
1414 YAHOO.widget.AutoComplete.prototype._typeAhead = function(oItem, sQuery) {
1415     // Don't update if turned off
1416     if(!this.typeAhead || (this._nKeyCode == 8)) {
1417         return;
1418     }
1419
1420     var elTextbox = this._elTextbox;
1421     var sValue = this._elTextbox.value; // any saved queries plus what user has typed
1422
1423     // Don't update with type-ahead if text selection is not supported
1424     if(!elTextbox.setSelectionRange && !elTextbox.createTextRange) {
1425         return;
1426     }
1427
1428     // Select the portion of text that the user has not typed
1429     var nStart = sValue.length;
1430     this._updateValue(oItem);
1431     var nEnd = elTextbox.value.length;
1432     this._selectText(elTextbox,nStart,nEnd);
1433     var sPrefill = elTextbox.value.substr(nStart,nEnd);
1434     this.typeAheadEvent.fire(this,sQuery,sPrefill);
1435     YAHOO.log("Typeahead occured with prefill string \"" + sPrefill + "\"", "info", this.toString());
1436 };
1437
1438 /**
1439  * Selects text in the input field.
1440  *
1441  * @method _selectText
1442  * @param elTextbox {HTMLElement} Text input box element in which to select text.
1443  * @param nStart {Number} Starting index of text string to select.
1444  * @param nEnd {Number} Ending index of text selection.
1445  * @private
1446  */
1447 YAHOO.widget.AutoComplete.prototype._selectText = function(elTextbox, nStart, nEnd) {
1448     if(elTextbox.setSelectionRange) { // For Mozilla
1449         elTextbox.setSelectionRange(nStart,nEnd);
1450     }
1451     else if(elTextbox.createTextRange) { // For IE
1452         var oTextRange = elTextbox.createTextRange();
1453         oTextRange.moveStart("character", nStart);
1454         oTextRange.moveEnd("character", nEnd-elTextbox.value.length);
1455         oTextRange.select();
1456     }
1457     else {
1458         elTextbox.select();
1459     }
1460 };
1461
1462 /**
1463  * Syncs results container with its helpers.
1464  *
1465  * @method _toggleContainerHelpers
1466  * @param bShow {Boolean} True if container is expanded, false if collapsed
1467  * @private
1468  */
1469 YAHOO.widget.AutoComplete.prototype._toggleContainerHelpers = function(bShow) {
1470     var bFireEvent = false;
1471     var width = this._elContent.offsetWidth + "px";
1472     var height = this._elContent.offsetHeight + "px";
1473
1474     if(this.useIFrame && this._elIFrame) {
1475         bFireEvent = true;
1476         if(bShow) {
1477             this._elIFrame.style.width = width;
1478             this._elIFrame.style.height = height;
1479         }
1480         else {
1481             this._elIFrame.style.width = 0;
1482             this._elIFrame.style.height = 0;
1483         }
1484     }
1485     if(this.useShadow && this._elShadow) {
1486         bFireEvent = true;
1487         if(bShow) {
1488             this._elShadow.style.width = width;
1489             this._elShadow.style.height = height;
1490         }
1491         else {
1492            this._elShadow.style.width = 0;
1493             this._elShadow.style.height = 0;
1494         }
1495     }
1496 };
1497
1498 /**
1499  * Animates expansion or collapse of the container.
1500  *
1501  * @method _toggleContainer
1502  * @param bShow {Boolean} True if container should be expanded, false if container should be collapsed
1503  * @private
1504  */
1505 YAHOO.widget.AutoComplete.prototype._toggleContainer = function(bShow) {
1506     var elContainer = this._elContainer;
1507
1508     // Implementer has container always open so don't mess with it
1509     if(this.alwaysShowContainer && this._bContainerOpen) {
1510         return;
1511     }
1512
1513     // Clear contents of container
1514     if(!bShow) {
1515         this._elContent.scrollTop = 0;
1516         var aItems = this._aListItems;
1517
1518         if(aItems && (aItems.length > 0)) {
1519             for(var i = aItems.length-1; i >= 0 ; i--) {
1520                 aItems[i].style.display = "none";
1521             }
1522         }
1523
1524         if(this._oCurItem) {
1525             this._toggleHighlight(this._oCurItem,"from");
1526         }
1527
1528         this._oCurItem = null;
1529         this._nDisplayedItems = 0;
1530         this._sCurQuery = null;
1531     }
1532
1533     // Container is already closed
1534     if(!bShow && !this._bContainerOpen) {
1535         this._elContent.style.display = "none";
1536         return;
1537     }
1538
1539     // If animation is enabled...
1540     var oAnim = this._oAnim;
1541     if(oAnim && oAnim.getEl() && (this.animHoriz || this.animVert)) {
1542         // If helpers need to be collapsed, do it right away...
1543         // but if helpers need to be expanded, wait until after the container expands
1544         if(!bShow) {
1545             this._toggleContainerHelpers(bShow);
1546         }
1547
1548         if(oAnim.isAnimated()) {
1549             oAnim.stop();
1550         }
1551
1552         // Clone container to grab current size offscreen
1553         var oClone = this._elContent.cloneNode(true);
1554         elContainer.appendChild(oClone);
1555         oClone.style.top = "-9000px";
1556         oClone.style.display = "block";
1557
1558         // Current size of the container is the EXPANDED size
1559         var wExp = oClone.offsetWidth;
1560         var hExp = oClone.offsetHeight;
1561
1562         // Calculate COLLAPSED sizes based on horiz and vert anim
1563         var wColl = (this.animHoriz) ? 0 : wExp;
1564         var hColl = (this.animVert) ? 0 : hExp;
1565
1566         // Set animation sizes
1567         oAnim.attributes = (bShow) ?
1568             {width: { to: wExp }, height: { to: hExp }} :
1569             {width: { to: wColl}, height: { to: hColl }};
1570
1571         // If opening anew, set to a collapsed size...
1572         if(bShow && !this._bContainerOpen) {
1573             this._elContent.style.width = wColl+"px";
1574             this._elContent.style.height = hColl+"px";
1575         }
1576         // Else, set it to its last known size.
1577         else {
1578             this._elContent.style.width = wExp+"px";
1579             this._elContent.style.height = hExp+"px";
1580         }
1581
1582         elContainer.removeChild(oClone);
1583         oClone = null;
1584
1585         var oSelf = this;
1586         var onAnimComplete = function() {
1587             // Finish the collapse
1588                 oAnim.onComplete.unsubscribeAll();
1589
1590             if(bShow) {
1591                 oSelf.containerExpandEvent.fire(oSelf);
1592                 YAHOO.log("Container expanded", "info", oSelf.toString());
1593             }
1594             else {
1595                 oSelf._elContent.style.display = "none";
1596                 oSelf.containerCollapseEvent.fire(oSelf);
1597                 YAHOO.log("Container collapsed", "info", oSelf.toString());
1598             }
1599             oSelf._toggleContainerHelpers(bShow);
1600         };
1601
1602         // Display container and animate it
1603         this._elContent.style.display = "block";
1604         oAnim.onComplete.subscribe(onAnimComplete);
1605         oAnim.animate();
1606         this._bContainerOpen = bShow;
1607     }
1608     // Else don't animate, just show or hide
1609     else {
1610         if(bShow) {
1611             this._elContent.style.display = "block";
1612             this.containerExpandEvent.fire(this);
1613             YAHOO.log("Container expanded", "info", this.toString());
1614         }
1615         else {
1616             this._elContent.style.display = "none";
1617             this.containerCollapseEvent.fire(this);
1618             YAHOO.log("Container collapsed", "info", this.toString());
1619         }
1620         this._toggleContainerHelpers(bShow);
1621         this._bContainerOpen = bShow;
1622    }
1623
1624 };
1625
1626 /**
1627  * Toggles the highlight on or off for an item in the container, and also cleans
1628  * up highlighting of any previous item.
1629  *
1630  * @method _toggleHighlight
1631  * @param oNewItem {HTMLElement} The &lt;li&gt; element item to receive highlight behavior.
1632  * @param sType {String} Type "mouseover" will toggle highlight on, and "mouseout" will toggle highlight off.
1633  * @private
1634  */
1635 YAHOO.widget.AutoComplete.prototype._toggleHighlight = function(oNewItem, sType) {
1636     var sHighlight = this.highlightClassName;
1637     if(this._oCurItem) {
1638         // Remove highlight from old item
1639         YAHOO.util.Dom.removeClass(this._oCurItem, sHighlight);
1640     }
1641
1642     if((sType == "to") && sHighlight) {
1643         // Apply highlight to new item
1644         YAHOO.util.Dom.addClass(oNewItem, sHighlight);
1645         this._oCurItem = oNewItem;
1646     }
1647 };
1648
1649 /**
1650  * Toggles the pre-highlight on or off for an item in the container.
1651  *
1652  * @method _togglePrehighlight
1653  * @param oNewItem {HTMLElement} The &lt;li&gt; element item to receive highlight behavior.
1654  * @param sType {String} Type "mouseover" will toggle highlight on, and "mouseout" will toggle highlight off.
1655  * @private
1656  */
1657 YAHOO.widget.AutoComplete.prototype._togglePrehighlight = function(oNewItem, sType) {
1658     if(oNewItem == this._oCurItem) {
1659         return;
1660     }
1661
1662     var sPrehighlight = this.prehighlightClassName;
1663     if((sType == "mouseover") && sPrehighlight) {
1664         // Apply prehighlight to new item
1665         YAHOO.util.Dom.addClass(oNewItem, sPrehighlight);
1666     }
1667     else {
1668         // Remove prehighlight from old item
1669         YAHOO.util.Dom.removeClass(oNewItem, sPrehighlight);
1670     }
1671 };
1672
1673 /**
1674  * Updates the text input box value with selected query result. If a delimiter
1675  * has been defined, then the value gets appended with the delimiter.
1676  *
1677  * @method _updateValue
1678  * @param oItem {HTMLElement} The &lt;li&gt; element item with which to update the value.
1679  * @private
1680  */
1681 YAHOO.widget.AutoComplete.prototype._updateValue = function(oItem) {
1682     var elTextbox = this._elTextbox;
1683     var sDelimChar = (this.delimChar) ? (this.delimChar[0] || this.delimChar) : null;
1684     var sSavedQuery = this._sSavedQuery;
1685     var sResultKey = oItem._sResultKey;
1686     elTextbox.focus();
1687
1688     // First clear text field
1689     elTextbox.value = "";
1690     // Grab data to put into text field
1691     if(sDelimChar) {
1692         if(sSavedQuery) {
1693             elTextbox.value = sSavedQuery;
1694         }
1695         elTextbox.value += sResultKey + sDelimChar;
1696         if(sDelimChar != " ") {
1697             elTextbox.value += " ";
1698         }
1699     }
1700     else { elTextbox.value = sResultKey; }
1701
1702     // scroll to bottom of textarea if necessary
1703     if(elTextbox.type == "textarea") {
1704         elTextbox.scrollTop = elTextbox.scrollHeight;
1705     }
1706
1707     // move cursor to end
1708     var end = elTextbox.value.length;
1709     this._selectText(elTextbox,end,end);
1710
1711     this._oCurItem = oItem;
1712 };
1713
1714 /**
1715  * Selects a result item from the container
1716  *
1717  * @method _selectItem
1718  * @param oItem {HTMLElement} The selected &lt;li&gt; element item.
1719  * @private
1720  */
1721 YAHOO.widget.AutoComplete.prototype._selectItem = function(oItem) {
1722     this._bItemSelected = true;
1723     this._updateValue(oItem);
1724     this._cancelIntervalDetection(this);
1725     this.itemSelectEvent.fire(this, oItem, oItem._oResultData);
1726     YAHOO.log("Item selected: " + YAHOO.lang.dump(oItem._oResultData), "info", this.toString());
1727     this._toggleContainer(false);
1728 };
1729
1730 /**
1731  * If an item is highlighted in the container, the right arrow key jumps to the
1732  * end of the textbox and selects the highlighted item, otherwise the container
1733  * is closed.
1734  *
1735  * @method _jumpSelection
1736  * @private
1737  */
1738 YAHOO.widget.AutoComplete.prototype._jumpSelection = function() {
1739     if(this._oCurItem) {
1740         this._selectItem(this._oCurItem);
1741     }
1742     else {
1743         this._toggleContainer(false);
1744     }
1745 };
1746
1747 /**
1748  * Triggered by up and down arrow keys, changes the current highlighted
1749  * &lt;li&gt; element item. Scrolls container if necessary.
1750  *
1751  * @method _moveSelection
1752  * @param nKeyCode {Number} Code of key pressed.
1753  * @private
1754  */
1755 YAHOO.widget.AutoComplete.prototype._moveSelection = function(nKeyCode) {
1756     if(this._bContainerOpen) {
1757         // Determine current item's id number
1758         var oCurItem = this._oCurItem;
1759         var nCurItemIndex = -1;
1760
1761         if(oCurItem) {
1762             nCurItemIndex = oCurItem._nItemIndex;
1763         }
1764
1765         var nNewItemIndex = (nKeyCode == 40) ?
1766                 (nCurItemIndex + 1) : (nCurItemIndex - 1);
1767
1768         // Out of bounds
1769         if(nNewItemIndex < -2 || nNewItemIndex >= this._nDisplayedItems) {
1770             return;
1771         }
1772
1773         if(oCurItem) {
1774             // Unhighlight current item
1775             this._toggleHighlight(oCurItem, "from");
1776             this.itemArrowFromEvent.fire(this, oCurItem);
1777             YAHOO.log("Item arrowed from", "info", this.toString());
1778         }
1779         if(nNewItemIndex == -1) {
1780            // Go back to query (remove type-ahead string)
1781             if(this.delimChar && this._sSavedQuery) {
1782                 if(!this._textMatchesOption()) {
1783                     this._elTextbox.value = this._sSavedQuery;
1784                 }
1785                 else {
1786                     this._elTextbox.value = this._sSavedQuery + this._sCurQuery;
1787                 }
1788             }
1789             else {
1790                 this._elTextbox.value = this._sCurQuery;
1791             }
1792             this._oCurItem = null;
1793             return;
1794         }
1795         if(nNewItemIndex == -2) {
1796             // Close container
1797             this._toggleContainer(false);
1798             return;
1799         }
1800
1801         var oNewItem = this._aListItems[nNewItemIndex];
1802
1803         // Scroll the container if necessary
1804         var elContent = this._elContent;
1805         var scrollOn = ((YAHOO.util.Dom.getStyle(elContent,"overflow") == "auto") ||
1806             (YAHOO.util.Dom.getStyle(elContent,"overflowY") == "auto"));
1807         if(scrollOn && (nNewItemIndex > -1) &&
1808         (nNewItemIndex < this._nDisplayedItems)) {
1809             // User is keying down
1810             if(nKeyCode == 40) {
1811                 // Bottom of selected item is below scroll area...
1812                 if((oNewItem.offsetTop+oNewItem.offsetHeight) > (elContent.scrollTop + elContent.offsetHeight)) {
1813                     // Set bottom of scroll area to bottom of selected item
1814                     elContent.scrollTop = (oNewItem.offsetTop+oNewItem.offsetHeight) - elContent.offsetHeight;
1815                 }
1816                 // Bottom of selected item is above scroll area...
1817                 else if((oNewItem.offsetTop+oNewItem.offsetHeight) < elContent.scrollTop) {
1818                     // Set top of selected item to top of scroll area
1819                     elContent.scrollTop = oNewItem.offsetTop;
1820
1821                 }
1822             }
1823             // User is keying up
1824             else {
1825                 // Top of selected item is above scroll area
1826                 if(oNewItem.offsetTop < elContent.scrollTop) {
1827                     // Set top of scroll area to top of selected item
1828                     this._elContent.scrollTop = oNewItem.offsetTop;
1829                 }
1830                 // Top of selected item is below scroll area
1831                 else if(oNewItem.offsetTop > (elContent.scrollTop + elContent.offsetHeight)) {
1832                     // Set bottom of selected item to bottom of scroll area
1833                     this._elContent.scrollTop = (oNewItem.offsetTop+oNewItem.offsetHeight) - elContent.offsetHeight;
1834                 }
1835             }
1836         }
1837
1838         this._toggleHighlight(oNewItem, "to");
1839         this.itemArrowToEvent.fire(this, oNewItem);
1840         YAHOO.log("Item arrowed to", "info", this.toString());
1841         if(this.typeAhead) {
1842             this._updateValue(oNewItem);
1843         }
1844     }
1845 };
1846
1847 /////////////////////////////////////////////////////////////////////////////
1848 //
1849 // Private event handlers
1850 //
1851 /////////////////////////////////////////////////////////////////////////////
1852
1853 /**
1854  * Handles &lt;li&gt; element mouseover events in the container.
1855  *
1856  * @method _onItemMouseover
1857  * @param v {HTMLEvent} The mouseover event.
1858  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
1859  * @private
1860  */
1861 YAHOO.widget.AutoComplete.prototype._onItemMouseover = function(v,oSelf) {
1862     if(oSelf.prehighlightClassName) {
1863         oSelf._togglePrehighlight(this,"mouseover");
1864     }
1865     else {
1866         oSelf._toggleHighlight(this,"to");
1867     }
1868
1869     oSelf.itemMouseOverEvent.fire(oSelf, this);
1870     YAHOO.log("Item moused over", "info", oSelf.toString());
1871 };
1872
1873 /**
1874  * Handles &lt;li&gt; element mouseout events in the container.
1875  *
1876  * @method _onItemMouseout
1877  * @param v {HTMLEvent} The mouseout event.
1878  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
1879  * @private
1880  */
1881 YAHOO.widget.AutoComplete.prototype._onItemMouseout = function(v,oSelf) {
1882     if(oSelf.prehighlightClassName) {
1883         oSelf._togglePrehighlight(this,"mouseout");
1884     }
1885     else {
1886         oSelf._toggleHighlight(this,"from");
1887     }
1888
1889     oSelf.itemMouseOutEvent.fire(oSelf, this);
1890     YAHOO.log("Item moused out", "info", oSelf.toString());
1891 };
1892
1893 /**
1894  * Handles &lt;li&gt; element click events in the container.
1895  *
1896  * @method _onItemMouseclick
1897  * @param v {HTMLEvent} The click event.
1898  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
1899  * @private
1900  */
1901 YAHOO.widget.AutoComplete.prototype._onItemMouseclick = function(v,oSelf) {
1902     // In case item has not been moused over
1903     oSelf._toggleHighlight(this,"to");
1904     oSelf._selectItem(this);
1905 };
1906
1907 /**
1908  * Handles container mouseover events.
1909  *
1910  * @method _onContainerMouseover
1911  * @param v {HTMLEvent} The mouseover event.
1912  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
1913  * @private
1914  */
1915 YAHOO.widget.AutoComplete.prototype._onContainerMouseover = function(v,oSelf) {
1916     oSelf._bOverContainer = true;
1917 };
1918
1919 /**
1920  * Handles container mouseout events.
1921  *
1922  * @method _onContainerMouseout
1923  * @param v {HTMLEvent} The mouseout event.
1924  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
1925  * @private
1926  */
1927 YAHOO.widget.AutoComplete.prototype._onContainerMouseout = function(v,oSelf) {
1928     oSelf._bOverContainer = false;
1929     // If container is still active
1930     if(oSelf._oCurItem) {
1931         oSelf._toggleHighlight(oSelf._oCurItem,"to");
1932     }
1933 };
1934
1935 /**
1936  * Handles container scroll events.
1937  *
1938  * @method _onContainerScroll
1939  * @param v {HTMLEvent} The scroll event.
1940  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
1941  * @private
1942  */
1943 YAHOO.widget.AutoComplete.prototype._onContainerScroll = function(v,oSelf) {
1944     oSelf._elTextbox.focus();
1945 };
1946
1947 /**
1948  * Handles container resize events.
1949  *
1950  * @method _onContainerResize
1951  * @param v {HTMLEvent} The resize event.
1952  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
1953  * @private
1954  */
1955 YAHOO.widget.AutoComplete.prototype._onContainerResize = function(v,oSelf) {
1956     oSelf._toggleContainerHelpers(oSelf._bContainerOpen);
1957 };
1958
1959
1960 /**
1961  * Handles textbox keydown events of functional keys, mainly for UI behavior.
1962  *
1963  * @method _onTextboxKeyDown
1964  * @param v {HTMLEvent} The keydown event.
1965  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
1966  * @private
1967  */
1968 YAHOO.widget.AutoComplete.prototype._onTextboxKeyDown = function(v,oSelf) {
1969     var nKeyCode = v.keyCode;
1970
1971     switch (nKeyCode) {
1972         case 9: // tab
1973             if((navigator.userAgent.toLowerCase().indexOf("mac") == -1)) {
1974                 // select an item or clear out
1975                 if(oSelf._oCurItem) {
1976                     if(oSelf.delimChar && (oSelf._nKeyCode != nKeyCode)) {
1977                         if(oSelf._bContainerOpen) {
1978                             YAHOO.util.Event.stopEvent(v);
1979                         }
1980                     }
1981                     oSelf._selectItem(oSelf._oCurItem);
1982                 }
1983                 else {
1984                     oSelf._toggleContainer(false);
1985                 }
1986             }
1987             break;
1988         case 13: // enter
1989             if((navigator.userAgent.toLowerCase().indexOf("mac") == -1)) {
1990                 if(oSelf._oCurItem) {
1991                     if(oSelf._nKeyCode != nKeyCode) {
1992                         if(oSelf._bContainerOpen) {
1993                             YAHOO.util.Event.stopEvent(v);
1994                         }
1995                     }
1996                     oSelf._selectItem(oSelf._oCurItem);
1997                 }
1998                 else {
1999                     oSelf._toggleContainer(false);
2000                 }
2001             }
2002             break;
2003         case 27: // esc
2004             oSelf._toggleContainer(false);
2005             return;
2006         case 39: // right
2007             oSelf._jumpSelection();
2008             break;
2009         case 38: // up
2010             YAHOO.util.Event.stopEvent(v);
2011             oSelf._moveSelection(nKeyCode);
2012             break;
2013         case 40: // down
2014             YAHOO.util.Event.stopEvent(v);
2015             oSelf._moveSelection(nKeyCode);
2016             break;
2017         default:
2018             break;
2019     }
2020 };
2021
2022 /**
2023  * Handles textbox keypress events.
2024  * @method _onTextboxKeyPress
2025  * @param v {HTMLEvent} The keypress event.
2026  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
2027  * @private
2028  */
2029 YAHOO.widget.AutoComplete.prototype._onTextboxKeyPress = function(v,oSelf) {
2030     var nKeyCode = v.keyCode;
2031
2032         //Expose only to Mac browsers, where stopEvent is ineffective on keydown events (bug 790337)
2033         if((navigator.userAgent.toLowerCase().indexOf("mac") != -1)) {
2034             switch (nKeyCode) {
2035             case 9: // tab
2036                 // select an item or clear out
2037                 if(oSelf._oCurItem) {
2038                     if(oSelf.delimChar && (oSelf._nKeyCode != nKeyCode)) {
2039                         if(oSelf._bContainerOpen) {
2040                             YAHOO.util.Event.stopEvent(v);
2041                         }
2042                     }
2043                     oSelf._selectItem(oSelf._oCurItem);
2044                 }
2045                 else {
2046                     oSelf._toggleContainer(false);
2047                 }
2048                 break;
2049             case 13: // enter
2050                 if(oSelf._oCurItem) {
2051                     if(oSelf._nKeyCode != nKeyCode) {
2052                         if(oSelf._bContainerOpen) {
2053                             YAHOO.util.Event.stopEvent(v);
2054                         }
2055                     }
2056                     oSelf._selectItem(oSelf._oCurItem);
2057                 }
2058                 else {
2059                     oSelf._toggleContainer(false);
2060                 }
2061                 break;
2062             default:
2063                 break;
2064             }
2065         }
2066
2067         //TODO: (?) limit only to non-IE, non-Mac-FF for Korean IME support (bug 811948)
2068         // Korean IME detected
2069         else if(nKeyCode == 229) {
2070             oSelf._queryInterval = setInterval(function() { oSelf._onIMEDetected(oSelf); },500);
2071         }
2072 };
2073
2074 /**
2075  * Handles textbox keyup events that trigger queries.
2076  *
2077  * @method _onTextboxKeyUp
2078  * @param v {HTMLEvent} The keyup event.
2079  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
2080  * @private
2081  */
2082 YAHOO.widget.AutoComplete.prototype._onTextboxKeyUp = function(v,oSelf) {
2083     // Check to see if any of the public properties have been updated
2084     oSelf._initProps();
2085
2086     var nKeyCode = v.keyCode;
2087
2088     oSelf._nKeyCode = nKeyCode;
2089     var sText = this.value; //string in textbox
2090
2091     // Filter out chars that don't trigger queries
2092     if(oSelf._isIgnoreKey(nKeyCode) || (sText.toLowerCase() == oSelf._sCurQuery)) {
2093         return;
2094     }
2095     else {
2096         oSelf._bItemSelected = false;
2097         YAHOO.util.Dom.removeClass(oSelf._oCurItem,  oSelf.highlightClassName);
2098         oSelf._oCurItem = null;
2099
2100         oSelf.textboxKeyEvent.fire(oSelf, nKeyCode);
2101         YAHOO.log("Textbox keyed", "info", oSelf.toString());
2102     }
2103
2104     // Set timeout on the request
2105     if(oSelf.queryDelay > 0) {
2106         var nDelayID =
2107             setTimeout(function(){oSelf._sendQuery(sText);},(oSelf.queryDelay * 1000));
2108
2109         if(oSelf._nDelayID != -1) {
2110             clearTimeout(oSelf._nDelayID);
2111         }
2112
2113         oSelf._nDelayID = nDelayID;
2114     }
2115     else {
2116         // No delay so send request immediately
2117         oSelf._sendQuery(sText);
2118     }
2119 };
2120
2121 /**
2122  * Handles text input box receiving focus.
2123  *
2124  * @method _onTextboxFocus
2125  * @param v {HTMLEvent} The focus event.
2126  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
2127  * @private
2128  */
2129 YAHOO.widget.AutoComplete.prototype._onTextboxFocus = function (v,oSelf) {
2130     oSelf._elTextbox.setAttribute("autocomplete","off");
2131     oSelf._bFocused = true;
2132     if(!oSelf._bItemSelected) {
2133         oSelf.textboxFocusEvent.fire(oSelf);
2134         YAHOO.log("Textbox focused", "info", oSelf.toString());
2135     }
2136 };
2137
2138 /**
2139  * Handles text input box losing focus.
2140  *
2141  * @method _onTextboxBlur
2142  * @param v {HTMLEvent} The focus event.
2143  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
2144  * @private
2145  */
2146 YAHOO.widget.AutoComplete.prototype._onTextboxBlur = function (v,oSelf) {
2147     // Don't treat as a blur if it was a selection via mouse click
2148     if(!oSelf._bOverContainer || (oSelf._nKeyCode == 9)) {
2149         // Current query needs to be validated as a selection
2150         if(!oSelf._bItemSelected) {
2151             var oMatch = oSelf._textMatchesOption();
2152             // Container is closed or current query doesn't match any result
2153             if(!oSelf._bContainerOpen || (oSelf._bContainerOpen && (oMatch === null))) {
2154                 // Force selection is enabled so clear the current query
2155                 if(oSelf.forceSelection) {
2156                     oSelf._clearSelection();
2157                 }
2158                 // Treat current query as a valid selection
2159                 else {
2160                     oSelf.unmatchedItemSelectEvent.fire(oSelf);
2161                     YAHOO.log("Unmatched item selected", "info", oSelf.toString());
2162                 }
2163             }
2164             // Container is open and current query matches a result
2165             else {
2166                 // Force a selection when textbox is blurred with a match
2167                 if(oSelf.forceSelection) {
2168                     oSelf._selectItem(oMatch);
2169                 }
2170             }
2171         }
2172
2173         if(oSelf._bContainerOpen) {
2174             oSelf._toggleContainer(false);
2175         }
2176         oSelf._cancelIntervalDetection(oSelf);
2177         oSelf._bFocused = false;
2178         oSelf.textboxBlurEvent.fire(oSelf);
2179         YAHOO.log("Textbox blurred", "info", oSelf.toString());
2180     }
2181 };
2182
2183 /**
2184  * Handles window unload event.
2185  *
2186  * @method _onWindowUnload
2187  * @param v {HTMLEvent} The unload event.
2188  * @param oSelf {YAHOO.widget.AutoComplete} The AutoComplete instance.
2189  * @private
2190  */
2191 YAHOO.widget.AutoComplete.prototype._onWindowUnload = function(v,oSelf) {
2192     if(oSelf && oSelf._elTextbox && oSelf.allowBrowserAutocomplete) {
2193         oSelf._elTextbox.setAttribute("autocomplete","on");
2194     }
2195 };
2196
2197 /****************************************************************************/
2198 /****************************************************************************/
2199 /****************************************************************************/
2200
2201 /**
2202  * The DataSource classes manages sending a request and returning response from a live
2203  * database. Supported data include local JavaScript arrays and objects and databases
2204  * accessible via XHR connections. Supported response formats include JavaScript arrays,
2205  * JSON, XML, and flat-file textual data.
2206  *
2207  * @class DataSource
2208  * @constructor
2209  */
2210 YAHOO.widget.DataSource = function() {
2211     /* abstract class */
2212 };
2213
2214
2215 /////////////////////////////////////////////////////////////////////////////
2216 //
2217 // Public constants
2218 //
2219 /////////////////////////////////////////////////////////////////////////////
2220
2221 /**
2222  * Error message for null data responses.
2223  *
2224  * @property ERROR_DATANULL
2225  * @type String
2226  * @static
2227  * @final
2228  */
2229 YAHOO.widget.DataSource.ERROR_DATANULL = "Response data was null";
2230
2231 /**
2232  * Error message for data responses with parsing errors.
2233  *
2234  * @property ERROR_DATAPARSE
2235  * @type String
2236  * @static
2237  * @final
2238  */
2239 YAHOO.widget.DataSource.ERROR_DATAPARSE = "Response data could not be parsed";
2240
2241
2242 /////////////////////////////////////////////////////////////////////////////
2243 //
2244 // Public member variables
2245 //
2246 /////////////////////////////////////////////////////////////////////////////
2247
2248 /**
2249  * Max size of the local cache.  Set to 0 to turn off caching.  Caching is
2250  * useful to reduce the number of server connections.  Recommended only for data
2251  * sources that return comprehensive results for queries or when stale data is
2252  * not an issue.
2253  *
2254  * @property maxCacheEntries
2255  * @type Number
2256  * @default 15
2257  */
2258 YAHOO.widget.DataSource.prototype.maxCacheEntries = 15;
2259
2260 /**
2261  * Use this to fine-tune the matching algorithm used against JS Array types of
2262  * DataSource and DataSource caches. If queryMatchContains is true, then the JS
2263  * Array or cache returns results that "contain" the query string. By default,
2264  * queryMatchContains is set to false, so that only results that "start with"
2265  * the query string are returned.
2266  *
2267  * @property queryMatchContains
2268  * @type Boolean
2269  * @default false
2270  */
2271 YAHOO.widget.DataSource.prototype.queryMatchContains = false;
2272
2273 /**
2274  * Enables query subset matching. If caching is on and queryMatchSubset is
2275  * true, substrings of queries will return matching cached results. For
2276  * instance, if the first query is for "abc" susequent queries that start with
2277  * "abc", like "abcd", will be queried against the cache, and not the live data
2278  * source. Recommended only for DataSources that return comprehensive results
2279  * for queries with very few characters.
2280  *
2281  * @property queryMatchSubset
2282  * @type Boolean
2283  * @default false
2284  *
2285  */
2286 YAHOO.widget.DataSource.prototype.queryMatchSubset = false;
2287
2288 /**
2289  * Enables case-sensitivity in the matching algorithm used against JS Array
2290  * types of DataSources and DataSource caches. If queryMatchCase is true, only
2291  * case-sensitive matches will return.
2292  *
2293  * @property queryMatchCase
2294  * @type Boolean
2295  * @default false
2296  */
2297 YAHOO.widget.DataSource.prototype.queryMatchCase = false;
2298
2299
2300 /////////////////////////////////////////////////////////////////////////////
2301 //
2302 // Public methods
2303 //
2304 /////////////////////////////////////////////////////////////////////////////
2305
2306  /**
2307  * Public accessor to the unique name of the DataSource instance.
2308  *
2309  * @method toString
2310  * @return {String} Unique name of the DataSource instance
2311  */
2312 YAHOO.widget.DataSource.prototype.toString = function() {
2313     return "DataSource " + this._sName;
2314 };
2315
2316 /**
2317  * Retrieves query results, first checking the local cache, then making the
2318  * query request to the live data source as defined by the function doQuery.
2319  *
2320  * @method getResults
2321  * @param oCallbackFn {HTMLFunction} Callback function defined by oParent object to which to return results.
2322  * @param sQuery {String} Query string.
2323  * @param oParent {Object} The object instance that has requested data.
2324  */
2325 YAHOO.widget.DataSource.prototype.getResults = function(oCallbackFn, sQuery, oParent) {
2326
2327     // First look in cache
2328     var aResults = this._doQueryCache(oCallbackFn,sQuery,oParent);
2329     // Not in cache, so get results from server
2330     if(aResults.length === 0) {
2331         this.queryEvent.fire(this, oParent, sQuery);
2332         YAHOO.log("Query received \"" + sQuery, "info", this.toString());
2333         this.doQuery(oCallbackFn, sQuery, oParent);
2334     }
2335 };
2336
2337 /**
2338  * Abstract method implemented by subclasses to make a query to the live data
2339  * source. Must call the callback function with the response returned from the
2340  * query. Populates cache (if enabled).
2341  *
2342  * @method doQuery
2343  * @param oCallbackFn {HTMLFunction} Callback function implemented by oParent to which to return results.
2344  * @param sQuery {String} Query string.
2345  * @param oParent {Object} The object instance that has requested data.
2346  */
2347 YAHOO.widget.DataSource.prototype.doQuery = function(oCallbackFn, sQuery, oParent) {
2348     /* override this */
2349 };
2350
2351 /**
2352  * Flushes cache.
2353  *
2354  * @method flushCache
2355  */
2356 YAHOO.widget.DataSource.prototype.flushCache = function() {
2357     if(this._aCache) {
2358         this._aCache = [];
2359     }
2360     if(this._aCacheHelper) {
2361         this._aCacheHelper = [];
2362     }
2363     this.cacheFlushEvent.fire(this);
2364     YAHOO.log("Cache flushed", "info", this.toString());
2365
2366 };
2367
2368 /////////////////////////////////////////////////////////////////////////////
2369 //
2370 // Public events
2371 //
2372 /////////////////////////////////////////////////////////////////////////////
2373
2374 /**
2375  * Fired when a query is made to the live data source.
2376  *
2377  * @event queryEvent
2378  * @param oSelf {Object} The DataSource instance.
2379  * @param oParent {Object} The requesting object.
2380  * @param sQuery {String} The query string.
2381  */
2382 YAHOO.widget.DataSource.prototype.queryEvent = null;
2383
2384 /**
2385  * Fired when a query is made to the local cache.
2386  *
2387  * @event cacheQueryEvent
2388  * @param oSelf {Object} The DataSource instance.
2389  * @param oParent {Object} The requesting object.
2390  * @param sQuery {String} The query string.
2391  */
2392 YAHOO.widget.DataSource.prototype.cacheQueryEvent = null;
2393
2394 /**
2395  * Fired when data is retrieved from the live data source.
2396  *
2397  * @event getResultsEvent
2398  * @param oSelf {Object} The DataSource instance.
2399  * @param oParent {Object} The requesting object.
2400  * @param sQuery {String} The query string.
2401  * @param aResults {Object[]} Array of result objects.
2402  */
2403 YAHOO.widget.DataSource.prototype.getResultsEvent = null;
2404
2405 /**
2406  * Fired when data is retrieved from the local cache.
2407  *
2408  * @event getCachedResultsEvent
2409  * @param oSelf {Object} The DataSource instance.
2410  * @param oParent {Object} The requesting object.
2411  * @param sQuery {String} The query string.
2412  * @param aResults {Object[]} Array of result objects.
2413  */
2414 YAHOO.widget.DataSource.prototype.getCachedResultsEvent = null;
2415
2416 /**
2417  * Fired when an error is encountered with the live data source.
2418  *
2419  * @event dataErrorEvent
2420  * @param oSelf {Object} The DataSource instance.
2421  * @param oParent {Object} The requesting object.
2422  * @param sQuery {String} The query string.
2423  * @param sMsg {String} Error message string
2424  */
2425 YAHOO.widget.DataSource.prototype.dataErrorEvent = null;
2426
2427 /**
2428  * Fired when the local cache is flushed.
2429  *
2430  * @event cacheFlushEvent
2431  * @param oSelf {Object} The DataSource instance
2432  */
2433 YAHOO.widget.DataSource.prototype.cacheFlushEvent = null;
2434
2435 /////////////////////////////////////////////////////////////////////////////
2436 //
2437 // Private member variables
2438 //
2439 /////////////////////////////////////////////////////////////////////////////
2440
2441 /**
2442  * Internal class variable to index multiple DataSource instances.
2443  *
2444  * @property _nIndex
2445  * @type Number
2446  * @private
2447  * @static
2448  */
2449 YAHOO.widget.DataSource._nIndex = 0;
2450
2451 /**
2452  * Name of DataSource instance.
2453  *
2454  * @property _sName
2455  * @type String
2456  * @private
2457  */
2458 YAHOO.widget.DataSource.prototype._sName = null;
2459
2460 /**
2461  * Local cache of data result objects indexed chronologically.
2462  *
2463  * @property _aCache
2464  * @type Object[]
2465  * @private
2466  */
2467 YAHOO.widget.DataSource.prototype._aCache = null;
2468
2469
2470 /////////////////////////////////////////////////////////////////////////////
2471 //
2472 // Private methods
2473 //
2474 /////////////////////////////////////////////////////////////////////////////
2475
2476 /**
2477  * Initializes DataSource instance.
2478  *
2479  * @method _init
2480  * @private
2481  */
2482 YAHOO.widget.DataSource.prototype._init = function() {
2483     // Validate and initialize public configs
2484     var maxCacheEntries = this.maxCacheEntries;
2485     if(!YAHOO.lang.isNumber(maxCacheEntries) || (maxCacheEntries < 0)) {
2486         maxCacheEntries = 0;
2487     }
2488     // Initialize local cache
2489     if(maxCacheEntries > 0 && !this._aCache) {
2490         this._aCache = [];
2491     }
2492
2493     this._sName = "instance" + YAHOO.widget.DataSource._nIndex;
2494     YAHOO.widget.DataSource._nIndex++;
2495
2496     this.queryEvent = new YAHOO.util.CustomEvent("query", this);
2497     this.cacheQueryEvent = new YAHOO.util.CustomEvent("cacheQuery", this);
2498     this.getResultsEvent = new YAHOO.util.CustomEvent("getResults", this);
2499     this.getCachedResultsEvent = new YAHOO.util.CustomEvent("getCachedResults", this);
2500     this.dataErrorEvent = new YAHOO.util.CustomEvent("dataError", this);
2501     this.cacheFlushEvent = new YAHOO.util.CustomEvent("cacheFlush", this);
2502 };
2503
2504 /**
2505  * Adds a result object to the local cache, evicting the oldest element if the
2506  * cache is full. Newer items will have higher indexes, the oldest item will have
2507  * index of 0.
2508  *
2509  * @method _addCacheElem
2510  * @param oResult {Object} Data result object, including array of results.
2511  * @private
2512  */
2513 YAHOO.widget.DataSource.prototype._addCacheElem = function(oResult) {
2514     var aCache = this._aCache;
2515     // Don't add if anything important is missing.
2516     if(!aCache || !oResult || !oResult.query || !oResult.results) {
2517         return;
2518     }
2519
2520     // If the cache is full, make room by removing from index=0
2521     if(aCache.length >= this.maxCacheEntries) {
2522         aCache.shift();
2523     }
2524
2525     // Add to cache, at the end of the array
2526     aCache.push(oResult);
2527 };
2528
2529 /**
2530  * Queries the local cache for results. If query has been cached, the callback
2531  * function is called with the results, and the cached is refreshed so that it
2532  * is now the newest element.
2533  *
2534  * @method _doQueryCache
2535  * @param oCallbackFn {HTMLFunction} Callback function defined by oParent object to which to return results.
2536  * @param sQuery {String} Query string.
2537  * @param oParent {Object} The object instance that has requested data.
2538  * @return aResults {Object[]} Array of results from local cache if found, otherwise null.
2539  * @private
2540  */
2541 YAHOO.widget.DataSource.prototype._doQueryCache = function(oCallbackFn, sQuery, oParent) {
2542     var aResults = [];
2543     var bMatchFound = false;
2544     var aCache = this._aCache;
2545     var nCacheLength = (aCache) ? aCache.length : 0;
2546     var bMatchContains = this.queryMatchContains;
2547     var sOrigQuery;
2548
2549     // If cache is enabled...
2550     if((this.maxCacheEntries > 0) && aCache && (nCacheLength > 0)) {
2551         this.cacheQueryEvent.fire(this, oParent, sQuery);
2552         YAHOO.log("Querying cache: \"" + sQuery + "\"", "info", this.toString());
2553         // If case is unimportant, normalize query now instead of in loops
2554         if(!this.queryMatchCase) {
2555             sOrigQuery = sQuery;
2556             sQuery = sQuery.toLowerCase();
2557         }
2558
2559         // Loop through each cached element's query property...
2560         for(var i = nCacheLength-1; i >= 0; i--) {
2561             var resultObj = aCache[i];
2562             var aAllResultItems = resultObj.results;
2563             // If case is unimportant, normalize match key for comparison
2564             var matchKey = (!this.queryMatchCase) ?
2565                 encodeURIComponent(resultObj.query).toLowerCase():
2566                 encodeURIComponent(resultObj.query);
2567
2568             // If a cached match key exactly matches the query...
2569             if(matchKey == sQuery) {
2570                     // Stash all result objects into aResult[] and stop looping through the cache.
2571                     bMatchFound = true;
2572                     aResults = aAllResultItems;
2573
2574                     // The matching cache element was not the most recent,
2575                     // so now we need to refresh the cache.
2576                     if(i != nCacheLength-1) {
2577                         // Remove element from its original location
2578                         aCache.splice(i,1);
2579                         // Add element as newest
2580                         this._addCacheElem(resultObj);
2581                     }
2582                     break;
2583             }
2584             // Else if this query is not an exact match and subset matching is enabled...
2585             else if(this.queryMatchSubset) {
2586                 // Loop through substrings of each cached element's query property...
2587                 for(var j = sQuery.length-1; j >= 0 ; j--) {
2588                     var subQuery = sQuery.substr(0,j);
2589
2590                     // If a substring of a cached sQuery exactly matches the query...
2591                     if(matchKey == subQuery) {
2592                         bMatchFound = true;
2593
2594                         // Go through each cached result object to match against the query...
2595                         for(var k = aAllResultItems.length-1; k >= 0; k--) {
2596                             var aRecord = aAllResultItems[k];
2597                             var sKeyIndex = (this.queryMatchCase) ?
2598                                 encodeURIComponent(aRecord[0]).indexOf(sQuery):
2599                                 encodeURIComponent(aRecord[0]).toLowerCase().indexOf(sQuery);
2600
2601                             // A STARTSWITH match is when the query is found at the beginning of the key string...
2602                             if((!bMatchContains && (sKeyIndex === 0)) ||
2603                             // A CONTAINS match is when the query is found anywhere within the key string...
2604                             (bMatchContains && (sKeyIndex > -1))) {
2605                                 // Stash a match into aResults[].
2606                                 aResults.unshift(aRecord);
2607                             }
2608                         }
2609
2610                         // Add the subset match result set object as the newest element to cache,
2611                         // and stop looping through the cache.
2612                         resultObj = {};
2613                         resultObj.query = sQuery;
2614                         resultObj.results = aResults;
2615                         this._addCacheElem(resultObj);
2616                         break;
2617                     }
2618                 }
2619                 if(bMatchFound) {
2620                     break;
2621                 }
2622             }
2623         }
2624
2625         // If there was a match, send along the results.
2626         if(bMatchFound) {
2627             this.getCachedResultsEvent.fire(this, oParent, sOrigQuery, aResults);
2628             YAHOO.log("Cached results found for query \"" + sQuery + "\": " +
2629                     YAHOO.lang.dump(aResults), "info", this.toString());
2630             oCallbackFn(sOrigQuery, aResults, oParent);
2631         }
2632     }
2633     return aResults;
2634 };
2635
2636
2637 /****************************************************************************/
2638 /****************************************************************************/
2639 /****************************************************************************/
2640
2641 /**
2642  * Implementation of YAHOO.widget.DataSource using XML HTTP requests that return
2643  * query results.
2644  *
2645  * @class DS_XHR
2646  * @extends YAHOO.widget.DataSource
2647  * @requires connection
2648  * @constructor
2649  * @param sScriptURI {String} Absolute or relative URI to script that returns query
2650  * results as JSON, XML, or delimited flat-file data.
2651  * @param aSchema {String[]} Data schema definition of results.
2652  * @param oConfigs {Object} (optional) Object literal of config params.
2653  */
2654 YAHOO.widget.DS_XHR = function(sScriptURI, aSchema, oConfigs) {
2655     // Set any config params passed in to override defaults
2656     if(oConfigs && (oConfigs.constructor == Object)) {
2657         for(var sConfig in oConfigs) {
2658             this[sConfig] = oConfigs[sConfig];
2659         }
2660     }
2661
2662     // Initialization sequence
2663     if(!YAHOO.lang.isArray(aSchema) || !YAHOO.lang.isString(sScriptURI)) {
2664         YAHOO.log("Could not instantiate XHR DataSource due to invalid arguments", "error", this.toString());
2665         return;
2666     }
2667
2668     this.schema = aSchema;
2669     this.scriptURI = sScriptURI;
2670
2671     this._init();
2672     YAHOO.log("XHR DataSource initialized","info",this.toString());
2673 };
2674
2675 YAHOO.widget.DS_XHR.prototype = new YAHOO.widget.DataSource();
2676
2677 /////////////////////////////////////////////////////////////////////////////
2678 //
2679 // Public constants
2680 //
2681 /////////////////////////////////////////////////////////////////////////////
2682
2683 /**
2684  * JSON data type.
2685  *
2686  * @property TYPE_JSON
2687  * @type Number
2688  * @static
2689  * @final
2690  */
2691 YAHOO.widget.DS_XHR.TYPE_JSON = 0;
2692
2693 /**
2694  * XML data type.
2695  *
2696  * @property TYPE_XML
2697  * @type Number
2698  * @static
2699  * @final
2700  */
2701 YAHOO.widget.DS_XHR.TYPE_XML = 1;
2702
2703 /**
2704  * Flat-file data type.
2705  *
2706  * @property TYPE_FLAT
2707  * @type Number
2708  * @static
2709  * @final
2710  */
2711 YAHOO.widget.DS_XHR.TYPE_FLAT = 2;
2712
2713 /**
2714  * Error message for XHR failure.
2715  *
2716  * @property ERROR_DATAXHR
2717  * @type String
2718  * @static
2719  * @final
2720  */
2721 YAHOO.widget.DS_XHR.ERROR_DATAXHR = "XHR response failed";
2722
2723 /////////////////////////////////////////////////////////////////////////////
2724 //
2725 // Public member variables
2726 //
2727 /////////////////////////////////////////////////////////////////////////////
2728
2729 /**
2730  * Alias to YUI Connection Manager, to allow implementers to customize the utility.
2731  *
2732  * @property connMgr
2733  * @type Object
2734  * @default YAHOO.util.Connect
2735  */
2736 YAHOO.widget.DS_XHR.prototype.connMgr = YAHOO.util.Connect;
2737
2738 /**
2739  * Number of milliseconds the XHR connection will wait for a server response. A
2740  * a value of zero indicates the XHR connection will wait forever. Any value
2741  * greater than zero will use the Connection utility's Auto-Abort feature.
2742  *
2743  * @property connTimeout
2744  * @type Number
2745  * @default 0
2746  */
2747 YAHOO.widget.DS_XHR.prototype.connTimeout = 0;
2748
2749 /**
2750  * Absolute or relative URI to script that returns query results. For instance,
2751  * queries will be sent to &#60;scriptURI&#62;?&#60;scriptQueryParam&#62;=userinput
2752  *
2753  * @property scriptURI
2754  * @type String
2755  */
2756 YAHOO.widget.DS_XHR.prototype.scriptURI = null;
2757
2758 /**
2759  * Query string parameter name sent to scriptURI. For instance, queries will be
2760  * sent to &#60;scriptURI&#62;?&#60;scriptQueryParam&#62;=userinput
2761  *
2762  * @property scriptQueryParam
2763  * @type String
2764  * @default "query"
2765  */
2766 YAHOO.widget.DS_XHR.prototype.scriptQueryParam = "query";
2767
2768 /**
2769  * String of key/value pairs to append to requests made to scriptURI. Define
2770  * this string when you want to send additional query parameters to your script.
2771  * When defined, queries will be sent to
2772  * &#60;scriptURI&#62;?&#60;scriptQueryParam&#62;=userinput&#38;&#60;scriptQueryAppend&#62;
2773  *
2774  * @property scriptQueryAppend
2775  * @type String
2776  * @default ""
2777  */
2778 YAHOO.widget.DS_XHR.prototype.scriptQueryAppend = "";
2779
2780 /**
2781  * XHR response data type. Other types that may be defined are YAHOO.widget.DS_XHR.TYPE_XML
2782  * and YAHOO.widget.DS_XHR.TYPE_FLAT.
2783  *
2784  * @property responseType
2785  * @type String
2786  * @default YAHOO.widget.DS_XHR.TYPE_JSON
2787  */
2788 YAHOO.widget.DS_XHR.prototype.responseType = YAHOO.widget.DS_XHR.TYPE_JSON;
2789
2790 /**
2791  * String after which to strip results. If the results from the XHR are sent
2792  * back as HTML, the gzip HTML comment appears at the end of the data and should
2793  * be ignored.
2794  *
2795  * @property responseStripAfter
2796  * @type String
2797  * @default "\n&#60;!-"
2798  */
2799 YAHOO.widget.DS_XHR.prototype.responseStripAfter = "\n<!-";
2800
2801 /////////////////////////////////////////////////////////////////////////////
2802 //
2803 // Public methods
2804 //
2805 /////////////////////////////////////////////////////////////////////////////
2806
2807 /**
2808  * Queries the live data source defined by scriptURI for results. Results are
2809  * passed back to a callback function.
2810  *
2811  * @method doQuery
2812  * @param oCallbackFn {HTMLFunction} Callback function defined by oParent object to which to return results.
2813  * @param sQuery {String} Query string.
2814  * @param oParent {Object} The object instance that has requested data.
2815  */
2816 YAHOO.widget.DS_XHR.prototype.doQuery = function(oCallbackFn, sQuery, oParent) {
2817     var isXML = (this.responseType == YAHOO.widget.DS_XHR.TYPE_XML);
2818     var sUri = this.scriptURI+"?"+this.scriptQueryParam+"="+sQuery;
2819     if(this.scriptQueryAppend.length > 0) {
2820         sUri += "&" + this.scriptQueryAppend;
2821     }
2822     YAHOO.log("DataSource is querying URL " + sUri, "info", this.toString());
2823     var oResponse = null;
2824
2825     var oSelf = this;
2826     /*
2827      * Sets up ajax request callback
2828      *
2829      * @param {object} oReq          HTTPXMLRequest object
2830      * @private
2831      */
2832     var responseSuccess = function(oResp) {
2833         // Response ID does not match last made request ID.
2834         if(!oSelf._oConn || (oResp.tId != oSelf._oConn.tId)) {
2835             oSelf.dataErrorEvent.fire(oSelf, oParent, sQuery, YAHOO.widget.DataSource.ERROR_DATANULL);
2836             YAHOO.log(YAHOO.widget.DataSource.ERROR_DATANULL, "error", oSelf.toString());
2837             return;
2838         }
2839 //DEBUG
2840 /*YAHOO.log(oResp.responseXML.getElementsByTagName("Result"),'warn');
2841 for(var foo in oResp) {
2842     YAHOO.log(foo + ": "+oResp[foo],'warn');
2843 }
2844 YAHOO.log('responseXML.xml: '+oResp.responseXML.xml,'warn');*/
2845         if(!isXML) {
2846             oResp = oResp.responseText;
2847         }
2848         else {
2849             oResp = oResp.responseXML;
2850         }
2851         if(oResp === null) {
2852             oSelf.dataErrorEvent.fire(oSelf, oParent, sQuery, YAHOO.widget.DataSource.ERROR_DATANULL);
2853             YAHOO.log(YAHOO.widget.DataSource.ERROR_DATANULL, "error", oSelf.toString());
2854             return;
2855         }
2856
2857         var aResults = oSelf.parseResponse(sQuery, oResp, oParent);
2858         var resultObj = {};
2859         resultObj.query = decodeURIComponent(sQuery);
2860         resultObj.results = aResults;
2861         if(aResults === null) {
2862             oSelf.dataErrorEvent.fire(oSelf, oParent, sQuery, YAHOO.widget.DataSource.ERROR_DATAPARSE);
2863             YAHOO.log(YAHOO.widget.DataSource.ERROR_DATAPARSE, "error", oSelf.toString());
2864             aResults = [];
2865         }
2866         else {
2867             oSelf.getResultsEvent.fire(oSelf, oParent, sQuery, aResults);
2868             YAHOO.log("Results returned for query \"" + sQuery + "\": " +
2869                     YAHOO.lang.dump(aResults), "info", oSelf.toString());
2870             oSelf._addCacheElem(resultObj);
2871         }
2872         oCallbackFn(sQuery, aResults, oParent);
2873     };
2874
2875     var responseFailure = function(oResp) {
2876         oSelf.dataErrorEvent.fire(oSelf, oParent, sQuery, YAHOO.widget.DS_XHR.ERROR_DATAXHR);
2877         YAHOO.log(YAHOO.widget.DS_XHR.ERROR_DATAXHR + ": " + oResp.statusText, "error", oSelf.toString());
2878         return;
2879     };
2880
2881     var oCallback = {
2882         success:responseSuccess,
2883         failure:responseFailure
2884     };
2885
2886     if(YAHOO.lang.isNumber(this.connTimeout) && (this.connTimeout > 0)) {
2887         oCallback.timeout = this.connTimeout;
2888     }
2889
2890     if(this._oConn) {
2891         this.connMgr.abort(this._oConn);
2892     }
2893
2894     oSelf._oConn = this.connMgr.asyncRequest("GET", sUri, oCallback, null);
2895 };
2896
2897 /**
2898  * Parses raw response data into an array of result objects. The result data key
2899  * is always stashed in the [0] element of each result object.
2900  *
2901  * @method parseResponse
2902  * @param sQuery {String} Query string.
2903  * @param oResponse {Object} The raw response data to parse.
2904  * @param oParent {Object} The object instance that has requested data.
2905  * @returns {Object[]} Array of result objects.
2906  */
2907 YAHOO.widget.DS_XHR.prototype.parseResponse = function(sQuery, oResponse, oParent) {
2908     var aSchema = this.schema;
2909     var aResults = [];
2910     var bError = false;
2911
2912     // Strip out comment at the end of results
2913     var nEnd = ((this.responseStripAfter !== "") && (oResponse.indexOf)) ?
2914         oResponse.indexOf(this.responseStripAfter) : -1;
2915     if(nEnd != -1) {
2916         oResponse = oResponse.substring(0,nEnd);
2917     }
2918
2919     switch (this.responseType) {
2920         case YAHOO.widget.DS_XHR.TYPE_JSON:
2921             var jsonList, jsonObjParsed;
2922             // Check for YUI JSON
2923             if(YAHOO.lang.JSON) {
2924                 // Use the JSON utility if available
2925                 jsonObjParsed = YAHOO.lang.JSON.parse(oResponse);
2926                 if(!jsonObjParsed) {
2927                     bError = true;
2928                     break;
2929                 }
2930                 else {
2931                     try {
2932                         // eval is necessary here since aSchema[0] is of unknown depth
2933                         jsonList = eval("jsonObjParsed." + aSchema[0]);
2934                     }
2935                     catch(e) {
2936                         bError = true;
2937                         break;
2938                    }
2939                 }
2940             }
2941             // Check for JSON lib
2942             else if(oResponse.parseJSON) {
2943                 // Use the new JSON utility if available
2944                 jsonObjParsed = oResponse.parseJSON();
2945                 if(!jsonObjParsed) {
2946                     bError = true;
2947                 }
2948                 else {
2949                     try {
2950                         // eval is necessary here since aSchema[0] is of unknown depth
2951                         jsonList = eval("jsonObjParsed." + aSchema[0]);
2952                     }
2953                     catch(e) {
2954                         bError = true;
2955                         break;
2956                    }
2957                 }
2958             }
2959             // Use older JSON lib if available
2960             else if(window.JSON) {
2961                 jsonObjParsed = JSON.parse(oResponse);
2962                 if(!jsonObjParsed) {
2963                     bError = true;
2964                     break;
2965                 }
2966                 else {
2967                     try {
2968                         // eval is necessary here since aSchema[0] is of unknown depth
2969                         jsonList = eval("jsonObjParsed." + aSchema[0]);
2970                     }
2971                     catch(e) {
2972                         bError = true;
2973                         break;
2974                    }
2975                 }
2976             }
2977             else {
2978                 // Parse the JSON response as a string
2979                 try {
2980                     // Trim leading spaces
2981                     while (oResponse.substring(0,1) == " ") {
2982                         oResponse = oResponse.substring(1, oResponse.length);
2983                     }
2984
2985                     // Invalid JSON response
2986                     if(oResponse.indexOf("{") < 0) {
2987                         bError = true;
2988                         break;
2989                     }
2990
2991                     // Empty (but not invalid) JSON response
2992                     if(oResponse.indexOf("{}") === 0) {
2993                         break;
2994                     }
2995
2996                     // Turn the string into an object literal...
2997                     // ...eval is necessary here
2998                     var jsonObjRaw = eval("(" + oResponse + ")");
2999                     if(!jsonObjRaw) {
3000                         bError = true;
3001                         break;
3002                     }
3003
3004                     // Grab the object member that contains an array of all reponses...
3005                     // ...eval is necessary here since aSchema[0] is of unknown depth
3006                     jsonList = eval("(jsonObjRaw." + aSchema[0]+")");
3007                 }
3008                 catch(e) {
3009                     bError = true;
3010                     break;
3011                }
3012             }
3013
3014             if(!jsonList) {
3015                 bError = true;
3016                 break;
3017             }
3018
3019             if(!YAHOO.lang.isArray(jsonList)) {
3020                 jsonList = [jsonList];
3021             }
3022
3023             // Loop through the array of all responses...
3024             for(var i = jsonList.length-1; i >= 0 ; i--) {
3025                 var aResultItem = [];
3026                 var jsonResult = jsonList[i];
3027                 // ...and loop through each data field value of each response
3028                 for(var j = aSchema.length-1; j >= 1 ; j--) {
3029                     // ...and capture data into an array mapped according to the schema...
3030                     var dataFieldValue = jsonResult[aSchema[j]];
3031                     if(!dataFieldValue) {
3032                         dataFieldValue = "";
3033                     }
3034                     //YAHOO.log("data: " + i + " value:" +j+" = "+dataFieldValue,"debug",this.toString());
3035                     aResultItem.unshift(dataFieldValue);
3036                 }
3037                 // If schema isn't well defined, pass along the entire result object
3038                 if(aResultItem.length == 1) {
3039                     aResultItem.push(jsonResult);
3040                 }
3041                 // Capture the array of data field values in an array of results
3042                 aResults.unshift(aResultItem);
3043             }
3044             break;
3045         case YAHOO.widget.DS_XHR.TYPE_XML:
3046             // Get the collection of results
3047             var xmlList = oResponse.getElementsByTagName(aSchema[0]);
3048             if(!xmlList) {
3049                 bError = true;
3050                 break;
3051             }
3052             // Loop through each result
3053             for(var k = xmlList.length-1; k >= 0 ; k--) {
3054                 var result = xmlList.item(k);
3055                 //YAHOO.log("Result"+k+" is "+result.attributes.item(0).firstChild.nodeValue,"debug",this.toString());
3056                 var aFieldSet = [];
3057                 // Loop through each data field in each result using the schema
3058                 for(var m = aSchema.length-1; m >= 1 ; m--) {
3059                     //YAHOO.log(aSchema[m]+" is "+result.attributes.getNamedItem(aSchema[m]).firstChild.nodeValue);
3060                     var sValue = null;
3061                     // Values may be held in an attribute...
3062                     var xmlAttr = result.attributes.getNamedItem(aSchema[m]);
3063                     if(xmlAttr) {
3064                         sValue = xmlAttr.value;
3065                         //YAHOO.log("Attr value is "+sValue,"debug",this.toString());
3066                     }
3067                     // ...or in a node
3068                     else{
3069                         var xmlNode = result.getElementsByTagName(aSchema[m]);
3070                         if(xmlNode && xmlNode.item(0) && xmlNode.item(0).firstChild) {
3071                             sValue = xmlNode.item(0).firstChild.nodeValue;
3072                             //YAHOO.log("Node value is "+sValue,"debug",this.toString());
3073                         }
3074                         else {
3075                             sValue = "";
3076                             //YAHOO.log("Value not found","debug",this.toString());
3077                         }
3078                     }
3079                     // Capture the schema-mapped data field values into an array
3080                     aFieldSet.unshift(sValue);
3081                 }
3082                 // Capture each array of values into an array of results
3083                 aResults.unshift(aFieldSet);
3084             }
3085             break;
3086         case YAHOO.widget.DS_XHR.TYPE_FLAT:
3087             if(oResponse.length > 0) {
3088                 // Delete the last line delimiter at the end of the data if it exists
3089                 var newLength = oResponse.length-aSchema[0].length;
3090                 if(oResponse.substr(newLength) == aSchema[0]) {
3091                     oResponse = oResponse.substr(0, newLength);
3092                 }
3093                 if(oResponse.length > 0) {
3094                     var aRecords = oResponse.split(aSchema[0]);
3095                     for(var n = aRecords.length-1; n >= 0; n--) {
3096                         if(aRecords[n].length > 0) {
3097                             aResults[n] = aRecords[n].split(aSchema[1]);
3098                         }
3099                     }
3100                 }
3101             }
3102             break;
3103         default:
3104             break;
3105     }
3106     sQuery = null;
3107     oResponse = null;
3108     oParent = null;
3109     if(bError) {
3110         return null;
3111     }
3112     else {
3113         return aResults;
3114     }
3115 };
3116
3117 /////////////////////////////////////////////////////////////////////////////
3118 //
3119 // Private member variables
3120 //
3121 /////////////////////////////////////////////////////////////////////////////
3122
3123 /**
3124  * XHR connection object.
3125  *
3126  * @property _oConn
3127  * @type Object
3128  * @private
3129  */
3130 YAHOO.widget.DS_XHR.prototype._oConn = null;
3131
3132
3133 /****************************************************************************/
3134 /****************************************************************************/
3135 /****************************************************************************/
3136
3137 /**
3138  * Implementation of YAHOO.widget.DataSource using the Get Utility to generate
3139  * dynamic SCRIPT nodes for data retrieval.
3140  *
3141  * @class DS_ScriptNode
3142  * @constructor
3143  * @extends YAHOO.widget.DataSource
3144  * @param sUri {String} URI to the script location that will return data.
3145  * @param aSchema {String[]} Data schema definition of results.
3146  * @param oConfigs {Object} (optional) Object literal of config params.
3147  */
3148 YAHOO.widget.DS_ScriptNode = function(sUri, aSchema, oConfigs) {
3149     // Set any config params passed in to override defaults
3150     if(oConfigs && (oConfigs.constructor == Object)) {
3151         for(var sConfig in oConfigs) {
3152             this[sConfig] = oConfigs[sConfig];
3153         }
3154     }
3155
3156     // Initialization sequence
3157     if(!YAHOO.lang.isArray(aSchema) || !YAHOO.lang.isString(sUri)) {
3158         YAHOO.log("Could not instantiate Script Node DataSource due to invalid arguments", "error", this.toString());
3159         return;
3160     }
3161
3162     this.schema = aSchema;
3163     this.scriptURI = sUri;
3164
3165     this._init();
3166     YAHOO.log("Script Node DataSource initialized","info",this.toString());
3167 };
3168
3169 YAHOO.widget.DS_ScriptNode.prototype = new YAHOO.widget.DataSource();
3170
3171 /////////////////////////////////////////////////////////////////////////////
3172 //
3173 // Public member variables
3174 //
3175 /////////////////////////////////////////////////////////////////////////////
3176
3177 /**
3178  * Alias to YUI Get Utility. Allows implementers to specify their own
3179  * subclasses of the YUI Get Utility.
3180  *
3181  * @property getUtility
3182  * @type Object
3183  * @default YAHOO.util.Get
3184  */
3185 YAHOO.widget.DS_ScriptNode.prototype.getUtility = YAHOO.util.Get;
3186
3187 /**
3188  * URI to the script that returns data.
3189  *
3190  * @property scriptURI
3191  * @type String
3192  */
3193 YAHOO.widget.DS_ScriptNode.prototype.scriptURI = null;
3194
3195 /**
3196  * Query string parameter name sent to scriptURI. For instance, requests will be
3197  * sent to &#60;scriptURI&#62;?&#60;scriptQueryParam&#62;=queryString
3198  *
3199  * @property scriptQueryParam
3200  * @type String
3201  * @default "query"
3202  */
3203 YAHOO.widget.DS_ScriptNode.prototype.scriptQueryParam = "query";
3204
3205 /**
3206  * Defines request/response management in the following manner:
3207  * <dl>
3208  *     <!--<dt>queueRequests</dt>
3209  *     <dd>If a request is already in progress, wait until response is returned before sending the next request.</dd>
3210  *     <dt>cancelStaleRequests</dt>
3211  *     <dd>If a request is already in progress, cancel it before sending the next request.</dd>-->
3212  *     <dt>ignoreStaleResponses</dt>
3213  *     <dd>Send all requests, but handle only the response for the most recently sent request.</dd>
3214  *     <dt>allowAll</dt>
3215  *     <dd>Send all requests and handle all responses.</dd>
3216  * </dl>
3217  *
3218  * @property asyncMode
3219  * @type String
3220  * @default "allowAll"
3221  */
3222 YAHOO.widget.DS_ScriptNode.prototype.asyncMode = "allowAll";
3223
3224 /**
3225  * Callback string parameter name sent to scriptURI. For instance, requests will be
3226  * sent to &#60;scriptURI&#62;?&#60;scriptCallbackParam&#62;=callbackFunction
3227  *
3228  * @property scriptCallbackParam
3229  * @type String
3230  * @default "callback"
3231  */
3232 YAHOO.widget.DS_ScriptNode.prototype.scriptCallbackParam = "callback";
3233
3234 /**
3235  * Global array of callback functions, one for each request sent.
3236  *
3237  * @property callbacks
3238  * @type Function[]
3239  * @static
3240  */
3241 YAHOO.widget.DS_ScriptNode.callbacks = [];
3242
3243 /////////////////////////////////////////////////////////////////////////////
3244 //
3245 // Private member variables
3246 //
3247 /////////////////////////////////////////////////////////////////////////////
3248
3249 /**
3250  * Unique ID to track requests.
3251  *
3252  * @property _nId
3253  * @type Number
3254  * @private
3255  * @static
3256  */
3257 YAHOO.widget.DS_ScriptNode._nId = 0;
3258
3259 /**
3260  * Counter for pending requests. When this is 0, it is safe to purge callbacks
3261  * array.
3262  *
3263  * @property _nPending
3264  * @type Number
3265  * @private
3266  * @static
3267  */
3268 YAHOO.widget.DS_ScriptNode._nPending = 0;
3269
3270 /////////////////////////////////////////////////////////////////////////////
3271 //
3272 // Public methods
3273 //
3274 /////////////////////////////////////////////////////////////////////////////
3275
3276 /**
3277  * Queries the live data source. Results are passed back to a callback function.
3278  *
3279  * @method doQuery
3280  * @param oCallbackFn {HTMLFunction} Callback function defined by oParent object to which to return results.
3281  * @param sQuery {String} Query string.
3282  * @param oParent {Object} The object instance that has requested data.
3283  */
3284 YAHOO.widget.DS_ScriptNode.prototype.doQuery = function(oCallbackFn, sQuery, oParent) {
3285     var oSelf = this;
3286
3287     // If there are no global pending requests, it is safe to purge global callback stack and global counter
3288     if(YAHOO.widget.DS_ScriptNode._nPending === 0) {
3289         YAHOO.widget.DS_ScriptNode.callbacks = [];
3290         YAHOO.widget.DS_ScriptNode._nId = 0;
3291     }
3292
3293     // ID for this request
3294     var id = YAHOO.widget.DS_ScriptNode._nId;
3295     YAHOO.widget.DS_ScriptNode._nId++;
3296
3297     // Dynamically add handler function with a closure to the callback stack
3298     YAHOO.widget.DS_ScriptNode.callbacks[id] = function(oResponse) {
3299         if((oSelf.asyncMode !== "ignoreStaleResponses")||
3300                 (id === YAHOO.widget.DS_ScriptNode.callbacks.length-1)) { // Must ignore stale responses
3301             oSelf.handleResponse(oResponse, oCallbackFn, sQuery, oParent);
3302         }
3303         else {
3304             YAHOO.log("DataSource ignored stale response for " + sQuery, "info", oSelf.toString());
3305         }
3306
3307         delete YAHOO.widget.DS_ScriptNode.callbacks[id];
3308     };
3309
3310     // We are now creating a request
3311     YAHOO.widget.DS_ScriptNode._nPending++;
3312
3313     var sUri = this.scriptURI+"&"+ this.scriptQueryParam+"="+sQuery+"&"+
3314             this.scriptCallbackParam+"=YAHOO.widget.DS_ScriptNode.callbacks["+id+"]";
3315     YAHOO.log("DataSource is querying URL " + sUri, "info", this.toString());
3316     this.getUtility.script(sUri,
3317             {autopurge:true,
3318             onsuccess:YAHOO.widget.DS_ScriptNode._bumpPendingDown,
3319             onfail:YAHOO.widget.DS_ScriptNode._bumpPendingDown});
3320 };
3321
3322 /**
3323  * Parses JSON response data into an array of result objects and passes it to
3324  * the callback function.
3325  *
3326  * @method handleResponse
3327  * @param oResponse {Object} The raw response data to parse.
3328  * @param oCallbackFn {HTMLFunction} Callback function defined by oParent object to which to return results.
3329  * @param sQuery {String} Query string.
3330  * @param oParent {Object} The object instance that has requested data.
3331  */
3332 YAHOO.widget.DS_ScriptNode.prototype.handleResponse = function(oResponse, oCallbackFn, sQuery, oParent) {
3333     var aSchema = this.schema;
3334     var aResults = [];
3335     var bError = false;
3336
3337     var jsonList, jsonObjParsed;
3338
3339     // Parse the JSON response as a string
3340     try {
3341         // Grab the object member that contains an array of all reponses...
3342         // ...eval is necessary here since aSchema[0] is of unknown depth
3343         jsonList = eval("(oResponse." + aSchema[0]+")");
3344     }
3345     catch(e) {
3346         bError = true;
3347    }
3348
3349     if(!jsonList) {
3350         bError = true;
3351         jsonList = [];
3352     }
3353
3354     else if(!YAHOO.lang.isArray(jsonList)) {
3355         jsonList = [jsonList];
3356     }
3357
3358     // Loop through the array of all responses...
3359     for(var i = jsonList.length-1; i >= 0 ; i--) {
3360         var aResultItem = [];
3361         var jsonResult = jsonList[i];
3362         // ...and loop through each data field value of each response
3363         for(var j = aSchema.length-1; j >= 1 ; j--) {
3364             // ...and capture data into an array mapped according to the schema...
3365             var dataFieldValue = jsonResult[aSchema[j]];
3366             if(!dataFieldValue) {
3367                 dataFieldValue = "";
3368             }
3369             //YAHOO.log("data: " + i + " value:" +j+" = "+dataFieldValue,"debug",this.toString());
3370             aResultItem.unshift(dataFieldValue);
3371         }
3372         // If schema isn't well defined, pass along the entire result object
3373         if(aResultItem.length == 1) {
3374             aResultItem.push(jsonResult);
3375         }
3376         // Capture the array of data field values in an array of results
3377         aResults.unshift(aResultItem);
3378     }
3379
3380     if(bError) {
3381         aResults = null;
3382     }
3383
3384     if(aResults === null) {
3385         this.dataErrorEvent.fire(this, oParent, sQuery, YAHOO.widget.DataSource.ERROR_DATAPARSE);
3386         YAHOO.log(YAHOO.widget.DataSource.ERROR_DATAPARSE, "error", this.toString());
3387         aResults = [];
3388     }
3389     else {
3390         var resultObj = {};
3391         resultObj.query = decodeURIComponent(sQuery);
3392         resultObj.results = aResults;
3393         this._addCacheElem(resultObj);
3394
3395         this.getResultsEvent.fire(this, oParent, sQuery, aResults);
3396         YAHOO.log("Results returned for query \"" + sQuery + "\": " +
3397                 YAHOO.lang.dump(aResults), "info", this.toString());
3398     }
3399
3400     oCallbackFn(sQuery, aResults, oParent);
3401 };
3402
3403 /////////////////////////////////////////////////////////////////////////////
3404 //
3405 // Private methods
3406 //
3407 /////////////////////////////////////////////////////////////////////////////
3408
3409 /**
3410  * Any success/failure response should decrement counter.
3411  *
3412  * @method _bumpPendingDown
3413  * @private
3414  */
3415 YAHOO.widget.DS_ScriptNode._bumpPendingDown = function() {
3416     YAHOO.widget.DS_ScriptNode._nPending--;
3417 };
3418
3419
3420 /****************************************************************************/
3421 /****************************************************************************/
3422 /****************************************************************************/
3423
3424 /**
3425  * Implementation of YAHOO.widget.DataSource using a native Javascript function as
3426  * its live data source.
3427  *
3428  * @class DS_JSFunction
3429  * @constructor
3430  * @extends YAHOO.widget.DataSource
3431  * @param oFunction {HTMLFunction} In-memory Javascript function that returns query results as an array of objects.
3432  * @param oConfigs {Object} (optional) Object literal of config params.
3433  */
3434 YAHOO.widget.DS_JSFunction = function(oFunction, oConfigs) {
3435     // Set any config params passed in to override defaults
3436     if(oConfigs && (oConfigs.constructor == Object)) {
3437         for(var sConfig in oConfigs) {
3438             this[sConfig] = oConfigs[sConfig];
3439         }
3440     }
3441
3442     // Initialization sequence
3443     if(!YAHOO.lang.isFunction(oFunction)) {
3444         YAHOO.log("Could not instantiate JSFunction DataSource due to invalid arguments", "error", this.toString());
3445         return;
3446     }
3447     else {
3448         this.dataFunction = oFunction;
3449         this._init();
3450         YAHOO.log("JS Function DataSource initialized","info",this.toString());
3451     }
3452 };
3453
3454 YAHOO.widget.DS_JSFunction.prototype = new YAHOO.widget.DataSource();
3455
3456 /////////////////////////////////////////////////////////////////////////////
3457 //
3458 // Public member variables
3459 //
3460 /////////////////////////////////////////////////////////////////////////////
3461
3462 /**
3463  * In-memory Javascript function that returns query results.
3464  *
3465  * @property dataFunction
3466  * @type HTMLFunction
3467  */
3468 YAHOO.widget.DS_JSFunction.prototype.dataFunction = null;
3469
3470 /////////////////////////////////////////////////////////////////////////////
3471 //
3472 // Public methods
3473 //
3474 /////////////////////////////////////////////////////////////////////////////
3475
3476 /**
3477  * Queries the live data source defined by function for results. Results are
3478  * passed back to a callback function.
3479  *
3480  * @method doQuery
3481  * @param oCallbackFn {HTMLFunction} Callback function defined by oParent object to which to return results.
3482  * @param sQuery {String} Query string.
3483  * @param oParent {Object} The object instance that has requested data.
3484  */
3485 YAHOO.widget.DS_JSFunction.prototype.doQuery = function(oCallbackFn, sQuery, oParent) {
3486     var oFunction = this.dataFunction;
3487     var aResults = [];
3488
3489     aResults = oFunction(sQuery);
3490     if(aResults === null) {
3491         this.dataErrorEvent.fire(this, oParent, sQuery, YAHOO.widget.DataSource.ERROR_DATANULL);
3492         YAHOO.log(YAHOO.widget.DataSource.ERROR_DATANULL, "error", this.toString());
3493         return;
3494     }
3495
3496     var resultObj = {};
3497     resultObj.query = decodeURIComponent(sQuery);
3498     resultObj.results = aResults;
3499     this._addCacheElem(resultObj);
3500
3501     this.getResultsEvent.fire(this, oParent, sQuery, aResults);
3502     YAHOO.log("Results returned for query \"" + sQuery +
3503             "\": " + YAHOO.lang.dump(aResults), "info", this.toString());
3504     oCallbackFn(sQuery, aResults, oParent);
3505     return;
3506 };
3507
3508
3509 /****************************************************************************/
3510 /****************************************************************************/
3511 /****************************************************************************/
3512
3513 /**
3514  * Implementation of YAHOO.widget.DataSource using a native Javascript array as
3515  * its live data source.
3516  *
3517  * @class DS_JSArray
3518  * @constructor
3519  * @extends YAHOO.widget.DataSource
3520  * @param aData {String[]} In-memory Javascript array of simple string data.
3521  * @param oConfigs {Object} (optional) Object literal of config params.
3522  */
3523 YAHOO.widget.DS_JSArray = function(aData, oConfigs) {
3524     // Set any config params passed in to override defaults
3525     if(oConfigs && (oConfigs.constructor == Object)) {
3526         for(var sConfig in oConfigs) {
3527             this[sConfig] = oConfigs[sConfig];
3528         }
3529     }
3530
3531     // Initialization sequence
3532     if(!YAHOO.lang.isArray(aData)) {
3533         YAHOO.log("Could not instantiate JSArray DataSource due to invalid arguments", "error", this.toString());
3534         return;
3535     }
3536     else {
3537         this.data = aData;
3538         this._init();
3539         YAHOO.log("JS Array DataSource initialized","info",this.toString());
3540     }
3541 };
3542
3543 YAHOO.widget.DS_JSArray.prototype = new YAHOO.widget.DataSource();
3544
3545 /////////////////////////////////////////////////////////////////////////////
3546 //
3547 // Public member variables
3548 //
3549 /////////////////////////////////////////////////////////////////////////////
3550
3551 /**
3552  * In-memory Javascript array of strings.
3553  *
3554  * @property data
3555  * @type Array
3556  */
3557 YAHOO.widget.DS_JSArray.prototype.data = null;
3558
3559 /////////////////////////////////////////////////////////////////////////////
3560 //
3561 // Public methods
3562 //
3563 /////////////////////////////////////////////////////////////////////////////
3564
3565 /**
3566  * Queries the live data source defined by data for results. Results are passed
3567  * back to a callback function.
3568  *
3569  * @method doQuery
3570  * @param oCallbackFn {HTMLFunction} Callback function defined by oParent object to which to return results.
3571  * @param sQuery {String} Query string.
3572  * @param oParent {Object} The object instance that has requested data.
3573  */
3574 YAHOO.widget.DS_JSArray.prototype.doQuery = function(oCallbackFn, sQuery, oParent) {
3575     var i;
3576     var aData = this.data; // the array
3577     var aResults = []; // container for results
3578     var bMatchFound = false;
3579     var bMatchContains = this.queryMatchContains;
3580     if(sQuery) {
3581         if(!this.queryMatchCase) {
3582             sQuery = sQuery.toLowerCase();
3583         }
3584
3585         // Loop through each element of the array...
3586         // which can be a string or an array of strings
3587         for(i = aData.length-1; i >= 0; i--) {
3588             var aDataset = [];
3589
3590             if(YAHOO.lang.isString(aData[i])) {
3591                 aDataset[0] = aData[i];
3592             }
3593             else if(YAHOO.lang.isArray(aData[i])) {
3594                 aDataset = aData[i];
3595             }
3596
3597             if(YAHOO.lang.isString(aDataset[0])) {
3598                 var sKeyIndex = (this.queryMatchCase) ?
3599                 encodeURIComponent(aDataset[0]).indexOf(sQuery):
3600                 encodeURIComponent(aDataset[0]).toLowerCase().indexOf(sQuery);
3601
3602                 // A STARTSWITH match is when the query is found at the beginning of the key string...
3603                 if((!bMatchContains && (sKeyIndex === 0)) ||
3604                 // A CONTAINS match is when the query is found anywhere within the key string...
3605                 (bMatchContains && (sKeyIndex > -1))) {
3606                     // Stash a match into aResults[].
3607                     aResults.unshift(aDataset);
3608                 }
3609             }
3610         }
3611     }
3612     else {
3613         for(i = aData.length-1; i >= 0; i--) {
3614             if(YAHOO.lang.isString(aData[i])) {
3615                 aResults.unshift([aData[i]]);
3616             }
3617             else if(YAHOO.lang.isArray(aData[i])) {
3618                 aResults.unshift(aData[i]);
3619             }
3620         }
3621     }
3622
3623     this.getResultsEvent.fire(this, oParent, sQuery, aResults);
3624     YAHOO.log("Results returned for query \"" + sQuery +
3625             "\": " + YAHOO.lang.dump(aResults), "info", this.toString());
3626     oCallbackFn(sQuery, aResults, oParent);
3627 };
3628
3629 YAHOO.register("autocomplete", YAHOO.widget.AutoComplete, {version: "2.5.2", build: "1076"});