XPages 開發實踐：開發通用的 Tree View 定製控制元件

所以，當在 XPage 頁面中加入 Dojo 物件時，請務必使用 HTML 標籤。

資料

本例中的資料來源於 Domino 檢視，除此之外，資料也可以來源於 Domino 的文件或者其它的關係型資料庫。圖 1 中圖示（1）標明的路線是我們應用 Domino 檢視資料的方式：用 Java 類讀取 Domino 檢視資料，並將資料構造為 Dojo 物件 JSON Schema 要求的格式； 再用伺服器端 JavaScript. 呼叫 Java 類方法獲得這些資料，並將它儲存在 XPage 頁面的客戶端 JavaScript. 變數中。

動作

圖 1 中圖示（2）標明瞭 Dojo 物件動作響應的客戶端 JavaScript. 的來源：Dojo 包中的針對該物件的和使用者自定義的客戶端 JavaScript。在實際的應用中，使用者通常是通過編寫客戶端的 JavaScript，來為 Dojo 物件支援的客戶端使用者事件，如 onClick，onChange 等加入動作響應的。

外觀

圖 1 中圖示（3）標明瞭決定 Dojo 物件外觀格式的來源：Dojo 包中關於物件外觀的定義和使用者自定義的 CSS。為了改變 Dojo 定義的預設外觀顯示格式，使用者需要通過“過載”的方式重新定義該物件的 CSS 類檔案。

使用 Dojo Tree 展示 Domino 檢視

本文的 第 3 部分，將詳細說明我們是如何從 Domino 資料庫中提取資料，並且將資料與 Tree 檢視顯示繫結起來的。讓我們遵循 圖 2 例項流程圖的步驟來構建一個 Dojo Tree Widget 的使用者定製控制元件吧。

圖 2. 流程圖（檢視大圖）

獲取 Domino 檢視 JSON 資料

Domino 檢視擁有自己的 JSON 資料，利用 URL 命令引數，我們可以檢視 Domino 檢視的 JSON 資料。對一個可以從 Web 瀏覽的 Domino 檢視，只需在瀏覽器 URL 的最後面新增引數“?ReadViewEntries&outputformat=JSON”，就可以看到它的 JSON 格式。

但是，Domino 檢視的 JSON 資料與 Dojo Tree 的 JSON Schema 並不一致，所以我們無法直接地使用 Domino 檢視 JSON 資料作為 Dojo Tree 物件的資料來源。下圖的 Domino 檢視 JSON 格式如圖 3(a)，如果要構造 Dojo tree，卻需要如圖 3(b) 格式的 JSON。

圖 3. Domino 檢視 JSON 和 Dojo tree JSON

我們可以使用 Java 類和伺服器端的 JavaScript. 來實現這兩種不同 JSON 格式的轉換。

首先，建立 Java 類獲取 Domino 檢視資料。Domino Designer 8.5 基於 Eclipse 平臺，可以很方便的建立 Java 類。我們通過“視窗 > 開啟透檢視 > Java”選擇 Java 視窗。

在右側選擇自己的專案 tree.nsf，在專案下建立相關的 Java 類檔案。本例中，我們建立了兩個類 TreeNode 和 OrganJSON，具體程式碼可以參見本文後的附錄。其中，OrganJSON 類中的 getOrganTree 方法實現的功能是將 Domino 的檢視層次轉化為樹結構，並且返回型別為 TreeNode 的根節點，通過樹的的根節點，我們可以遍歷樹中所有的節點；getTreeJSON 方法實現則是由樹的根節點開始做遍歷，並最終生成 Dojo Tree 能夠識別的 JSON 格式的字串。

然後我們在 Designer 中建立一個伺服器端的 JavaScript. 用於呼叫剛才建立的 Java 類中的方法。我們通過“視窗 > 開啟透檢視 > Domino Designer”回到 Designer 的工作區。在“程式碼 -> Script. 庫”中選擇“新建伺服器 JavaScript. 庫”，建立 Tree.jss 檔案。在這個檔案中，建立了 getJsonString 函式，在該方法中，我們需要傳入 Domino 的檢視名字和檢視中一個列的名字，這個列的名字用於在樹狀結構中顯示，在本示例中可以選擇 name 列，也可以選擇 email 列。

清單 3. JavaScript. getTreeJSON 函式

				 
function getJsonString(view, column){ 
    var viewName:String = view; 
    var columnName:String = column; 
    var organJSON:com.ibm.test.tree.OrganJSON =new com.ibm.test.tree.OrganJSON(); 
    var organTree:com.ibm.test.tree.TreeNode = organJSON.getOrganTree(session, 
        "tree.nsf", viewName, columnName); 
    var rganTreeStr=organJSON.getTreeJSON(organTree); 
    return organTreeStr; 
} 
     

繫結 Domino 檢視資料

接下來需要在 XPage 頁面中新增 Dojo 的資料來源，我們通過一個計算域來實現，程式碼如下：

清單 4. JavaScript. 用計算域獲取伺服器端資料

				 
 
     
        "
        result += "var jsonStore = new dojo.data.ItemFileReadStore({data:" + json + "});"
        result += ""
        return result;}]]> 
     
 
 		 

我們首先得到傳入使用者定製控制元件的屬性 ViewName 和 ColumnName（有關使用者定製控制元件和屬性的說明，參照 第 4 部分），然後通過呼叫我們之前建立的伺服器端的 JavaScript. 中的方法 json=getJsonString(viewName, columnName); 來生成 JSON 格式的資料來源。

有了 JSON 的資料來源，接下來我們只需要在控制元件頁面中利用 Dojo Tree 提供的相關 API 就可以將我們的樹狀結構展示出來了。在源中加入以下標準的 HTML 程式碼。其中 store="jsonStore" 是我們在前面的計算域中定義過的 jsonStore，也就是本示例中用到的資料來源。query="{name:'0'}" 是我們從資料來源 jsonStore 中讀取的根節點，將其作為樹狀結構的根元素。

清單 5. XPage 中的 Dojo 物件

				 
 
 

 
     
        alert("Execute of node " + jsonStore.getLabel(item) +", 
        population=" + jsonStore.getValue(item, "population")); 
    
 

建立使用者定製控制元件

建立使用者定製控制元件

在 XPages 中，使用者定製控制元件是一個允許使用者定義、編輯，並且在不同的 XPage 頁面中複用的元件。它類似於 Domino 模板設計中的“子模板”，或者 Web 頁面設計中的皮膚。不同的是，它提供了更為強大的功能和可定製性。如，支援使用者以拖拽的方式直接將 XPages 的“核心控制元件”組合在一起；支援使用者自定義的控制元件屬性；管理並支援使用者以拖拽和定製的方式複用控制元件。如果使用者開發的 Web 應用中有一些部分是會被反覆使用的，比如 Header, Menu bar, Navigator，或者就如我們正在建立的展示 Domino View 層次結構的通用 Dojo Tree，那麼建立一個可複用的“定製控制元件”是最好的選擇。

通過右鍵“控制元件”選擇“新建定製控制元件”ccTree，如 圖 4。在工作區中，我們可以在“設計”和“原始碼”兩個頁面中編輯它。在工作區下面，可以看到控制元件的屬性、事件。圖的右下角，在定製控制元件管理皮膚中，ccTree 被列在裡面，當要建立其它的 Xpage 頁面或者其他的定製控制元件時，我們都可以直接通過把它拖入工作區複用它。也就是說，定製控制元件是支援巢狀的。

定製控制元件還允許使用者自定義屬性，使用它時，通過傳入不同的屬性值就可以實現對它的定製。而圖中的 ViewName 和 ColumnName 正是我們為 ccTree 定義的屬性。ViewName 代表了希望展示的 Domino 檢視的名字，ColumnName 代表了用於在樹狀結構中顯示的列的名字。

為了在 XPages 中使用 Dojo Tree 元素，需要將用到的 Dojo 包引入到控制元件中，通過“屬性 > 資源 > 新增指令碼庫”按鈕，新增將要用到的 dojo.parser、dojo、data、ItemFileReadStore 及 dijit.Tree 包。也可以選擇通過直接編輯原始碼實現。

同時，為了能使用我們之前定義的 JavaScript. 庫，也需要把它引入到控制元件中，同樣通過“屬性 > 資源 > 新增指令碼庫”來實現。當然，也可以選擇通過直接在原始碼的 里加入 語句來實現。

ccTree 使用者定製控制元件的檔案內容請參照附件。

在 XPages 中複用控制元件 ccTree

我們建立的定製控制元件 ccTree 現在已經可以使用了。讓我們看看使用它是多麼方便和靈活吧！

我們需要做的僅僅是：

1. 新建一個 XPage 頁面。
2. 將 ccTree 控制元件從定製控制元件皮膚中拖入工作區（需要切換到“設計”頁才可實現拖拽）。
3. 傳入引數。切換到“原始碼”頁，找到控制元件的位置，加入 Domino 檢視名字和需要顯示的列名字。程式碼如下，在本例中的資料庫 tree.nsf 中，有一個名叫 Contacts 的檢視顯示了聯絡人列表，其中 Name 列是聯絡人的名稱。
   

之後，預覽這個 XPage 頁面，就能看到如 圖 5(b) 的 Dojo Tree 樹狀圖，展現了 Contacts 檢視的層次結構，在葉節點上顯示的是聯絡人名稱。就本例而言，如果您想讓葉節點上顯示聯絡人的郵件地址，很簡單！在上述的程式碼中將 ColumnName 的值設為 Email；如果您想顯示別的檢視，也很簡單，修改上述程式碼中的 ViewName 和 ColumnName 值就可以了。

示例效果展示

為了使讀者能夠更直觀地瞭解本文實現的 Dojo Tree 定製控制元件，我們給出瞭如 圖 1 的例項效果圖。圖 5(a), 是 Domino 預設支援的 Web 檢視；圖 5(b)，是利用本文提供的定製控制元件，在 XPages 中生成的 Dojo Tree 風格的檢視層次。這樣的 Web 頁面更符合 Web 2.0 使用者的使用習慣。更重要的是，它以 XPages 定製控制元件的形式提供給使用者，非常易於複用和定製，可以很方便地複用在任何 XPage 頁面中，通過傳入少量引數即可用來顯示任何 Domino 檢視。

如何使用本文中的原始檔

本文主要用到的原始檔。包括 :

1. Java 函式庫、Java 類檔案：OrganJSON.java，TreeNode.java
2. 伺服器端 JavaScript. 函式庫：Tree.jss （程式碼 > Script. 庫 > Tree）
3. 定製控制元件：ccTree （定製控制元件 > ccTree）

如何應用這些原始檔：

1. 開啟 Domino Designer 8.5，新建一個資料庫 tree.nsf（如果要在 Designer 中預覽，需要將 tree.nsf 拷貝到 Notes 的 Data 目錄中）。
2. 切換到 Java 透檢視，將 Java 類檔案 OrganJSON.java、TreeNode.java 拷貝到 tree.nsf 工程目錄中。
3. 切換回 Desinger 工作區，定製控制元件 ccTree 和 JavaScript. 函式庫 Tree.jss 拷貝到您的資料庫中。
4. 在您資料庫中需要加入 ccTree 控制元件的 XPage 頁面中按照 第 4.2 節 生成“XPage 頁面”的方法加入 ccTree 控制元件，並配置它的引數，用來顯示您資料庫中已有的 Domino 檢視。
5. 選擇“設計 > 在 Web 瀏覽器中預覽” 。

佈署到 Domino Server 上瀏覽：

1. 將 tree.nsf 拷貝到 Domino Server 的 Data 目錄中。
2. 從瀏覽器中訪問 http://(dominoserver host)/tree.nsf/Tree.xsp。

   結束語

   本文通過一個例項詳細介紹瞭如何使用 XPages 開發一個通用的 Dojo Tree 風格定製控制元件，用來展現 Domino 檢視的層次結構。通過本文，讀者應用 XPages 技術，在基於 Domino 的 Web 應用中開發靈活的、可複用的使用者定製控制元件，並且使用和整合 Dojo 的 JavaScript. 類庫。

來自 “ ITPUB部落格 ” ，連結：http://blog.itpub.net/14751907/viewspace-611982/，如需轉載，請註明出處，否則將追究法律責任。