Repeater 是 JQueryElement 這個開源專案中的亮點控件:它把「表格的填充、搜索、排序、分頁、行內編輯、新增、刪除」全部封裝成宣告式設定,前端只需寫模板,後端只需提供資料。以下依功能模組整理用法。
示例圖:

先從 https://code.google.com/p/zsharedcode/wiki/Download 下載最新版的 JQueryElement,並在頁面頂端註冊命名空間:
<%@ Register Assembly="zoyobar.shared.panzer.JQueryElement"
Namespace="zoyobar.shared.panzer.ui.jqueryui" TagPrefix="je" %>
<%@ Register Assembly="zoyobar.shared.panzer.JQueryElement"
Namespace="zoyobar.shared.panzer.web.jqueryui" TagPrefix="je" %>
接著從 jqueryui.com 下載 jQuery 與 jQueryUI 的腳本和樣式:
<link type="text/css" rel="stylesheet" href="[樣式路徑]/jquery-ui-1.8.15.custom.css" />
<script type="text/javascript" src="[腳本路徑]/jquery-1.6.2.min.js"></script>
<script type="text/javascript" src="[腳本路徑]/jquery-ui-1.8.15.custom.min.js"></script>
<script type="text/javascript" src="[腳本路徑]/jquery.ui.datepicker-zh-CN.js"></script>
在列模板中以 #{欄位名} 輸出欄位值:
<ItemTemplate>
<span>#{id}</span>
<span>#{realname}</span>
<span>#{age}</span>
</ItemTemplate>
欄位也能綁到標籤屬性上,例如 <span title="#{realname}">#{realname}</span>。
所有模板都能用 @{屬性名} 綁定 Repeater 自身的狀態屬性:
<FooterTemplate>
第 @{pageindex}/@{pagecount} 頁,共 @{itemcount} 筆
</FooterTemplate>
Selector 是一個 JavaScript 表達式,用來指定最終呈現 Repeater 的元素(寫法參照 jquery.com):
<table id="list"></table>
<je:Repeater ID="studentRepeater" runat="server" Selector="'#list'"> ... </je:Repeater>
IsVariable="true" 會在客戶端產生與 ClientID 同名的 JavaScript 變數,之後就能直接呼叫它的方法:
$(function () { studentRepeater.__repeater('fill'); });
若 ClientID 與 ID 不同,可改用 JQueryScript 控件的內嵌語法 [%id:studentRepeater%] 來取得變數。
分頁:PageSize 設定每頁筆數,PageIndex 設定初始頁碼(預設 1)。
欄位:Field 是參與綁定的欄位,形式為 JavaScript 字串陣列,例如 ['id', 'realname', 'age']。若不設定,會由第一次填充的資料自動決定——但這會導致沒有資料時無法新增,所以正式環境建議明確指定。FilterField 指定可搜索的欄位,FilterFieldDefault 是這些欄位為 null 或空字串時的預設值(如 ['', '', 0]),SortField 則指定可排序的欄位。
最簡潔的寫法是直接宣告四組 URL/MethodName:
<je:Repeater ID="studentRepeater" runat="server"
FillAsync-Url="Student.aspx" FillAsync-MethodName="Fill"
UpdateAsync-Url="Student.aspx" UpdateAsync-MethodName="Update"
InsertAsync-Url="Student.aspx" InsertAsync-MethodName="Insert"
RemoveAsync-Url="Student.aspx" RemoveAsync-MethodName="Remove" >
/* ... */
</je:Repeater>
若需要傳更多參數,改用 ParameterList:
<FillAsync Url="Student.aspx" MethodName="Fill">
<ParameterList>
<je:Parameter Name="ws" Type="Expression" Value="website" Default="'-'" />
<je:Parameter Name="year" Type="Selector" Value="'#year'" Default="2011" />
</ParameterList>
</FillAsync>
Type="Expression" 時 Value 是 JavaScript 表達式(website 代表取變數值,也可寫成 'www.google.com' 或 100 等常數);Type="Selector" 時 Value 會作為選擇器,取該元素的值。Default 是參數為 null 或空字串時採用的預設表達式。
填充/搜索時,後端會收到 pageindex、pagesize,以及與欄位同名的搜索參數和形如 <欄位名>_order 的排序參數("" 不排序、"asc" 升冪、"desc" 降冪):
[WebMethod()]
public static object Fill ( int pageindex, int pagesize
, string realname, int age
, string id_order ) { }
回傳的 JSON 必須符合以下結構,其中 __success 預設為 true,itemcount 可省略(但省略後無法計算總頁數):
{
"__success": <是否成功的布林值>,
"rows": <目前頁的列資料陣列>,
"itemcount": <總列數>
}
在 .NET 4.0 中可以用匿名型別直接產生,不必手刻字串:
[WebMethod()]
public static object Fill ( /* 參數 */ ) {
List<object> students = new List<object> ( );
students.Add ( new { id = 1, realname = "jack", age = 20 } );
return new { __success = true, rows = students.ToArray ( ), itemcount = 120 };
}
更新、刪除、新建三項的請求與回傳格式大同小異,因篇幅不在此列出,可參考線上文件。
客戶端 JavaScript 中,列有 4 種狀態:unchanged(未改變)、updated(已更新)、inserted(新增後)、removed(刪除後)。排序則有 none(無排序或預設排序)、asc、desc 三種狀態值。這些狀態名可直接用於樣式選擇器,是「不同狀態顯示不同外觀」的基礎。
模板中的 HTML 必須是完整、合法的,且不要直接使用單引號(需轉義),否則可能造成最終顯示異常。
顯示 unchanged 狀態的列。若未設定 UpdatedItemTemplate 或 InsertedItemTemplate,則 updated/inserted 狀態的列也會用這個模板顯示:
<ItemTemplate>
<tr>
<td>#{id}</td>
<td>#{realname}</td>
<td>#{age}</td>
<td><span je-onclick="beginedit">編輯</span> <span je-onclick="remove">刪除</span></td>
</tr>
</ItemTemplate>
分別用於顯示 updated 與 inserted 狀態的列,主要目的是用不同樣式區隔狀態。不過這個效果用 je-class 會更簡潔:
<UpdatedItemTemplate>
<tr style="font-weight: bold;"> ... </tr>
</UpdatedItemTemplate>
<InsertedItemTemplate>
<tr style="color: green;"> ... </tr>
</InsertedItemTemplate>
另有 RemovedItemTemplate、EditItemTemplate、FilterTemplate/NewItemTemplate、HeaderTemplate/FooterTemplate/EmptyTemplate,各自對應刪除後的殘留顯示、編輯中的列、搜索列/新增列、以及頁首頁尾與空資料狀態。
je-id="<欄位名>" 用於 input 元素,在 EditItemTemplate 中它會帶入該欄位的新值;在 FilterTemplate 中帶入搜索條件(該欄位須列於 FilterField);在 NewItemTemplate 中帶入新建資料的值。
為事件綁定內建行為,常用值包含:
beginedit 開始編輯、endedit 取消編輯、update 保存更新、remove 刪除、toggleselect 切換選取(以上僅限列模板)insert 新建(用於 NewItemTemplate)、filter 搜索(用於 FilterTemplate)、togglesort 切換排序(用於 HeaderTemplate)togglesort 需要額外指定排序欄位,寫成 je-onclick="togglesort,realname",該欄位須已設定在 SortField 中。
為狀態綁定樣式,可用值包含 {header}(ui-widget-header)、{active}、{highlight}、{disabled}、{error}、{default}、{state}(列狀態)、{sort}(排序狀態)。
<ItemTemplate>
<tr je-class="{state}-item"> ... </tr>
</ItemTemplate>
其語法分別為 {state[,<未改變樣式>[,<新建樣式>[,<修改樣式>[,<刪除樣式>]]]]} 與 {sort,<排序欄位>[,<無排序樣式>[,<升冪樣式>[,<降冪樣式>]]]}。若省略某狀態的樣式,會直接以該狀態的名稱作為 class,例如 {state,,new-item} 時,unchanged 狀態的列就會得到名為 unchanged 的 class。
在 ItemTemplate 中用 je-checked="selected" 搭配 je-onclick="toggleselect" 表示列是否被選取;je-selected 則用於 EditItemTemplate 中的 select 元素。
在 FilterTemplate 中標記初始的搜索條件欄位。
目前支援 je-button 與 je-datepicker,屬性寫法與 jQueryUI 一致:
<td>
<input type="text" je-id="birthday"
je-datepicker="dateFormat='yy-mm-dd';" value="#{birthday}" />
</td>
<td>
<span je-button="label='編輯';icons={ primary: 'ui-icon-pencil' };" je-onclick="beginedit"></span>
<span je-button="label='刪除';icons={ primary: 'ui-icon-trash' };" je-onclick="remove"></span>
</td>
Repeater 的所有事件都帶有 tag(Repeater 所在元素)與 e(事件資料)兩個參數:
PreUpdate/Updated、PreRemove/Removed、PreInsert/Inserted:操作前後。e.row 為該列資料;Updated/Removed/Inserted 的 e 另有 isSuccess。PreFill/Filled:填充前後。PreExecute/Executed:任何操作前後。PreCustom/Customed:自訂操作前後,e.command 為操作名稱。PreSubStep/SubStepped:分批處理前後,e.count 為總數、e.completed 為已完成列數。Navigable:導航可用性變動時,e.prev/e.next 表示是否有上/下頁。Blocked:有操作被阻擋時觸發。在 Pre* 事件中回傳 false 即可取消該操作,這是做前端二次驗證與確認框的入口:
PreUpdate="
function(tag, e){
if(e.row.realname == '' || e.row.age == '' || e.row.birthday == ''){
$('#message').text('請將信息填寫完整');
return false;
}
}"
PreRemove="
function(tag, e){ if(!confirm('是否刪除 ' + e.row.realname)){ return false; } }"
Updated="
function(tag, e){ $('#message').text('更新 ' + e.row.realname + (e.isSuccess ? ' 成功' : ' 失敗')); }"
由於篇幅,客戶端方法與部分模板細節未在此列出,完整說明請參考:https://code.google.com/p/zsharedcode/wiki/JQueryElementRepeaterDoc
示例程式碼下載:https://zsharedcode.googlecode.com/files/JQueryElementTest.rar
實際操作演示:https://www.tudou.com/programs/view/GQeh0ZIJ0RY/(建議全螢幕觀看)
歡迎訪問 panzer 開源專案 https://zsharedcode.googlecode.com/,其中除了 jQueryUI 的 ASP.NET 控件 JQueryElement,還包含可控制 WebBrowser 執行各類 js/jQuery 腳本並錄製的 IEBrowser 工具。