DIV CSS 佈局教程網

ASP.NET 三十分鐘上手無刷新 Repeater:JQueryElement 控件完整指南
編輯:JQuery特效代碼     

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 必須是完整、合法的,且不要直接使用單引號(需轉義),否則可能造成最終顯示異常。

ItemTemplate

顯示 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>

UpdatedItemTemplate/InsertedItemTemplate

分別用於顯示 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

je-id="<欄位名>" 用於 input 元素,在 EditItemTemplate 中它會帶入該欄位的新值;在 FilterTemplate 中帶入搜索條件(該欄位須列於 FilterField);在 NewItemTemplate 中帶入新建資料的值。

je-<JavaScript 事件名>

為事件綁定內建行為,常用值包含:

  • beginedit 開始編輯、endedit 取消編輯、update 保存更新、remove 刪除、toggleselect 切換選取(以上僅限列模板)
  • insert 新建(用於 NewItemTemplate)、filter 搜索(用於 FilterTemplate)、togglesort 切換排序(用於 HeaderTemplate)

togglesort 需要額外指定排序欄位,寫成 je-onclick="togglesort,realname",該欄位須已設定在 SortField 中。

je-class

為狀態綁定樣式,可用值包含 {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。

je-checked/selected/readonly

在 ItemTemplate 中用 je-checked="selected" 搭配 je-onclick="toggleselect" 表示列是否被選取;je-selected 則用於 EditItemTemplate 中的 select 元素。

je-value

在 FilterTemplate 中標記初始的搜索條件欄位。

je-<jQueryUI 插件名>

目前支援 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 工具。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved