Jquery + Autocomplete plugin 使用說明

這是JQ的Autocomplete plugin的介紹文
JQ基本觀念..就不多說了
如果要學JQ的話，可以考慮這本益大資訊~精通JavaScript+jQuery
這本的plugin介紹不多
不過目前沒有看到對plugin介紹很深入的書，因此不如把JS、JQ整個學好一點比較有用
進階點的JQ書也不少，如果已經對JS有觀念的話，直接找JQ書籍也不錯
以上是我的觀點啦

JQ的AUtocomplete有很多套件
這篇所用的是http://bassistance.de/jquery-plugins/jquery-plugin-autocomplete/
官方說明:http://docs.jquery.com/Plugins/Autocomplete#Setup
寫的時候版本是JQ 1.3.2, autocomplete 1.0.2
基本重點：
1.Jquery沒有預設指定編碼，最好先進行UTF8設定
找到contentType:application/x-www-form-urlencoded
改成contentType:application/x-www-form-urlencoded; charset=UTF-8
如果資料或頁面是big5時，也要記得先進行轉換

2.可處理的資料格式，一行一筆記錄，各欄位間用 | 分隔
而換行符號要用/n而不是
(HTML寫太順手的話，容易犯這錯誤)
JSON的話，聽說要是這種格式: ["test","test","test 123","test 456"]

3.autocomplete的預設參數是q, 資料來源為web service時要記得

基本方法
1.最基本的寫法
$("ID").autocomplete(資料來源, options);
ex: $("ID").autocomplete("data.php",
{
max:10, scroll:false, width:162,
});
2.result方法在每筆列表資料產生時候都會被呼叫，並擁有三個參數(evt, data, formatted)
$("#mytextbox").autocomplete("clients.php")
.result(function (evt, data, formatted) {
$("#hiddenIDbox").val(data[1]);
});
以上例子能將mytextbox的輸入傳送到clients.php
並在取得回傳值後，將每筆記錄的第二欄位值設定為ID:hiddenIDbox的值



相關方法：
autocomplete(url or data, options)
讓指定的input或text執行，範例：$("#test").autocomplete(data)

result( handler )
得到搜索结果的句柄

search( )
触发一个search事件

flushCache( ) Returns: jQuery
清空缓存


相關參數：
setOptions( options )
參數說明
minChars，Default: 1
觸發執行autocomplete的最小字元數

delay，預設400毫秒
顯示自動自動完成選擇框的延遲時間

cacheLength，預設10
緩存長度。後端儲存的cache次數(?)。最小值1時，只會儲存目前的結果(等於沒有cache)。

matchSubset Boolean
Default: true
匹配子集，預設開啟。要有效的話，cache length要大於1。
不過還不確定運作方式..
Whether or not the autocompleter can use a cache for more specific queries. This means that all matches of "foot" are a subset of all matches for "foo". Usually this is true, and using this options decreases server load and increases performance. Only useful with cacheLength settings bigger than one, like 10.

matchCase, 預設false
大小寫選項。

matchContains，預設false
在字句內尋找。
開啟後，輸入"ba"時會搜尋到"foo bar"。
不該與autofill一起使用(混淆)。

mustMatch，預設false
必須完全匹配。設成true時，
看不懂..
If set to true, the autocompleter will only allow results that are presented by the backend. Note that illegal values result in an empty input box.

selectFirst Boolean
Default: true
如果設置為true則第一個值會被自動選中。
If this is set to true, the first autocomplete value will be automatically selected on tab/return, even if it has not been handpicked by keyboard or mouse action. If there is a handpicked (highlighted) result, that result will take precedence.
extraParams Object

以下是額外的參數，
Extra parameters for the backend. If you were to specify { bar:4 }, the autocompleter would call my_autocomplete_backend.php?q=foo&bar=4 (assuming the input box contains "foo"). The param can be a function that is called to calculate the param before each request.


formatItem Function
Default: Assumes that a single row contains a single value.
對結果進行進階的格式處理，預設的資料型態是一行中一個值，要讓一行有多值，就需要用到formatItem。
autocomplete中的每筆資料產生時，就會觸發這函數。
回傳值的基本型態是

xxxx

。
autoComplete會傳遞四個參數，
1.結果列
2.索引位置(從1開始)
3.總資料筆數
4.搜尋字串
Provides advanced markup for an item. For each row of results, this function will be called. The returned value will be displayed inside an LI element in the results list. Autocompleter will provide 4 parameters: the results row, the position of the row in the list of results (starting at 1), the number of items in the list of results and the search term.

formatMatch Function
Default: formatItem is used
格式化匹配項
Use this option if you want to limit the data that autocomplete searches for matches. For example, there may be items you want displayed to the user, but don't want included in the data that's searched. Gets called with the same arguments as formatItem.

formatResult Function
Default: Assumes either plain data to use as result or uses the same value as provided by formatItem.
格式化結果，注意有三個參數(資料項, 資料位置(從1開始)，資料筆數)
Similar to formatItem, but provides the formatting for the value to be put into the input field. Again three arguments: Data, position (starting with one) and total number of data.

multiple,Default: false
是否能放多於一個的數值
Whether to allow more than one autocompleted-value to enter.

multipleSeparator，Default: ", "
Seperator to put between values when using multiple option.
同一行中的分割符號，預設為逗號 ","
同時也是多重選項中的分割符號


width
選擇框的寬度

autoFill，Default: false
當選中自動提示框裡面的選項時INPUT框內是否自動補全

max Number
Default: 10
自動完成提示的顯示數量

highlight Boolean ,Function
Default: Wraps the search term in a < strong > Element
高亮顯示當匹配到選擇框的元素。
Whether and how to highlight matches in the select box. Set to false to disable. Set to a function to customize. The function gets the value as the first argument and the search term as the second and must return the formatted value.

scroll，Default: true
當結果集result set大於預設高度時是否使用卷軸顯示

scrollHeight，高度180
自動完成提示的卷軸高度用圖元大小表示


根據其他選項的輸入產生資料
$("#states").autocomplete(url, {
extraParams: {
country: function() { return $("#country").val(); }
}
});

進階參數
autoFill:(預設值為false):自動填充
inputclass （預設值： “ ac_input ” ）
這個階層將被添加到輸入框。
resultsclass （預設值： “ ac_results ” ）
階級為UL認證將包含結果專案（專案的結果是李元素） 。
loadingclass = （預設值： “ ac_loading ” ）

lineseparator = （預設值： “ \ n ” ）
字元分隔線，結果從後端。
cellseparator （預設值： “ | ” ）
字元分隔細胞的結果，從後端。
minchars （預設值： 1 ）
最低的字元數使用者輸入之前， autocompleter啟動。
拖延（預設值： 400 ）
延遲在毫秒該autocompleter等待後，一按鍵來啟動本身。如果您使用的資料財產設立一個本地陣列，您可能希望增加延遲，以在較短的時限內（如40ms ） 。
cachelength （預設值： 1 ）
人數後端的查詢結果，存儲在緩存中。如果設置為1 （目前的結果） ，不緩存會發生。不設低於1 。
matchsubset （預設值： 1 ）
是否或不是autocompleter可以使用一個緩存為更具體的疑問。這意味著所有匹配的“腳”是的一個子集所有匹配的“富” 。通常這是事實，和使用這個選項跌幅伺服器負載，並提高性能。記得設置cachelength ，以更大的數目，如10 。
matchcase （預設值： 0 ）
是否或不比較是區分大小寫的。唯一重要的唯一如果您使用的緩存。
matchcontains = options.matchcontains | | 0 ;
是否或不是比較看來，內（即是否“廣管局”匹配“富網吧” ）的搜索結果。唯一重要如果您使用的緩存。
maxitemstoshow （預設值： -1 ）
限制的結果數量將顯示在下拉。這是非常有用的如果您有大量的資料和不想為使用者提供一份清單，列出可能包含數以百計的項目。要禁用此功能，將該值設置為-1 。
mustmatch （預設值： 0 ）
如果設置為1 （ True ） ， autocompleter將只允許結果是由後端。請注意，非法價值觀的結果，在一個空的輸入框。在為例，在本月初的檔，打字“頁腳” ，會導致一個空的輸入框。
extraparams （預設值： （ ） ）
額外的參數為後端。如果你要指定（酒吧： 4 ） ， autocompleter將要求my_autocomplete_backend.php問=富酒吧= 4 （假設輸入框包含“富” ） 。
寬度（預設值： 0 ）
寬度設為下拉層。如果一個非正整數是指定的，那麼寬度的方塊，將取決於寬度的投入要素。一般來說，您會想要離開這個價值。然而，在某些情況下，您可能有一個小的投入要素如下拉層的需要，顯示了很多的選擇。在這種情況下，您可以指定一個較大的規模。
selectfirst （預設值：虛假）
如果是這樣的設置為True ，第一次自動完成的價值將被自動選定的標籤/回報率，即使沒有親自通過鍵盤或滑鼠的行動。如果有一個親自（突出） ，結果，這一結果將優先考慮。
selectonly （預設值：虛假）
如果是這樣的設置為TRUE ，和只存在一個自動當用戶點擊標籤/返回，這將是選定的，即使它並未親自通過鍵盤或滑鼠的行動。這是壓倒selectfirst 。
formatitem （預設值：無）
一個JavaScript函數，可以提供先進的標記為一個專案。每一行的結果，此功能將被稱為。返回的值將被車廂內所展示的李元素在結果清單中。 autocompleter將提供3個參數：結果連續的立場，列在名單的結果，以及有多少個項目，在結果列表。見的原始程式碼http://www.dyve.net/jquery?autocomplete一個例子。
onselectitem （預設值：無）
JavaScript函數將被稱為當一個項目被選中。該autocompleter將指定一個單一的說法，作為李元素被選中。李元素，這將有屬性的“額外”包含一個陣列的所有細胞，後端指定。見的原始程式碼http://www.dyve.net/jquery?autocomplete一個例子。
onfindvalue （預設值：無）
JavaScript函數將被稱為當findvalue （ ）方法是所謂的。該函數會予以通過，專責李元素-就像o nselectitem功能。
如果您想要做更多與您的autocompleter ，你可以改變一些方案對飛。
該autocompleter訪問作為一個屬性，輸入框。
例如：
/ /設置autocompleter
無功交流= $ （ “ ＃ input_box ” ） 。自動（ “ my_autocomplete_backend.php ” ） ;
/ /會看的價值，自動框的基礎上，在文字輸入的元素
交流[ 0 ] 。 autocompleter.findvalue （ ） ;
有下列功能，可被稱為影響的行為，在執行時間：
findvalue （ ）
這將研究的價值，目前在投入要素並期待它的價值，看看是否能找到一個匹配的價值。這個功能可以潛在的執行AJAX操作，因此， findvalue （ ）函數沒有返回值。相反，你需要具體的一onfindvalue回呼函數將運行。這種方法是有價值的，如果您需要設置自動投入要素的價值通過JavaScript和“價值”的文本欄位映射到擴展屬性存儲在李元素的“額外”的財產。
flushcache （ ）
這刷新緩存。
setextraparams （目標）
這集的額外參數的autocompleter ，以目標（即應該是一個JavaScript物件，見上文） 。
它的往往是明智的刷新緩存後，要求setextraparameters