DIV CSS 佈局教程網

SharePoint 用戶端物件模型(一):ECMAScript 篇
編輯:關於JavaScript     

所謂的用戶端物件模型(Client Object Model),背後其實是呼叫 WCF 服務來取得資料,並用 JSON 作為傳輸格式以減輕封包大小。從設計上也能看到不少「降低資料存取量」的考量。技術上並沒有太多突破——你若有心,在 SharePoint 2007 裡也能實作出類似功能——但在使用便利性上確實改進了很多。

SharePoint 2010 提供了三種用戶端模型:.NET 託管、ECMA 腳本、Silverlight Client。

ECMAScript Client OM 的注意事項

  • ECMAScript 只能在 SharePoint 站點內使用,無法在其他 ASP.NET 站點中用它存取 SharePoint 資源,也不能跨 SharePoint 站點存取。
  • 與 jQuery 併用不會衝突。
  • 為了安全地更新內容,使用 ECMAScript 的頁面需加入 <SharePoint:FormDigest runat="server" />。
  • 為減輕載入的資料量,可以指定要載入的欄位,例如 clientContext.load(this.web, 'Title', 'Id', 'Created')。這裡的屬性名稱沿用與 CAML 相同的體系,區分大小寫。
  • 為確保程式在 sp.js 載入完畢後才執行,請用 ExecuteOrDelayUntilScriptLoaded(myFunction, "sp.js") 包一層。

伺服器端與用戶端物件的對應關係

伺服器端 OM用戶端 OM
SPContextClientContext
SPSiteSite
SPWebWeb
SPListList
SPListItemListItem
SPFieldField

初步規劃的功能以清單的建立、查詢與管理為主,另外也涵蓋上傳檔案的情境。

其中的連結會呼叫 UI 層的 JavaScript 介面,開啟 SharePoint 2010 風格的彈出視窗,視窗背後的頁面位於 SitePages 文件庫中。要留意的是,這個做法僅適用於 WebPart 頁面;若非此類頁面,會出現錯誤:The Ribbon Tab with id: "Ribbon.Read" has not been made available for this page or does not exist。

建立清單

首先透過 SharePoint Designer 加入兩個 ScriptLink:

<SharePoint:ScriptLink Name="SP.js" runat="server" OnDemand="true" Localizable="false" />
<SharePoint:ScriptLink Name="SP.debug.js" runat="server" OnDemand="true" Localizable="false" />

ECMAScript OM 與 .NET Managed Client OM 異曲同工,但有三點差異需要記住:

  1. ClientContext 中不能使用伺服器端 URL
  2. 不支援 LINQ
  3. 本質上是非同步的

程式碼本身相當直觀。其中 SP.UI.Notify.addNotification 是個有趣的小東西,能讓目前頁面右上角浮現提示訊息,非常符合 SharePoint 的視覺語言。

實際操作是:在文字框輸入清單名稱後點擊「Create List」按鈕,建立成功後右上角會提示 List test1 created。本例使用 announcement 作為清單類型。

<script type="text/javascript">
var messageId;
function createList(listName) {
    var clientContext = new SP.ClientContext();
    var oWebSite = clientContext.get_web();
    var listCreationInfo = new SP.ListCreationInformation();
    listCreationInfo.set_title(listName);
    listCreationInfo.set_templateType(SP.ListTemplateType.announcements);
    listCreationInfo.set_quickLaunchOption(SP.QuickLaunchOptions.on);
    var oList = oWebSite.get_lists().add(listCreationInfo);
    clientContext.load(oList);
    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onQuerySucceeded),
        Function.createDelegate(this, this.onQueryFailed)
    );
}

function onQuerySucceeded() {
    if (messageId != null) {
        SP.UI.Notify.removeNotification(messageId);
    }
    messageId = SP.UI.Notify.addNotification("List <b>" + oList.get_title() + "</b> created...", false, "", null);
}

function onQueryFailed(sender, args) {
    if (messageId != null) {
        SP.UI.Notify.removeNotification(messageId);
    }
    messageId = SP.UI.Notify.addNotification("Operation was cancelled...", false, "", null);
}
</script>

取得所有清單

點擊「Get All List」會把目前站點下的所有清單讀取出來並設上超連結;點擊「Hide List」則將其隱藏(實際上就是控制一個 div 的顯示)。

程式碼相當直接,值得說明的是 getEnumerator() 搭配 moveNext() 與 get_current() 這組函式,為遍歷集合提供了很好的模式。

function getLists() {
    var clientContext = new SP.ClientContext();
    var oWebSite = clientContext.get_web();
    listCollection = oWebSite.get_lists();
    clientContext.load(listCollection);
    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onGetListsSucceeded),
        Function.createDelegate(this, this.onGetListsFailed)
    );
}

function onGetListsSucceeded() {
    var str = "";
    var listsEnumerator = listCollection.getEnumerator();
    while (listsEnumerator.moveNext()) {
        var objList = listsEnumerator.get_current();
        str += "<a href='https://localhost" + objList.get_parentWebUrl() + objList.get_defaultViewUrl()
             + "'>" + objList.get_title() + "</a><br/>";
    }
    document.getElementById("lists").innerHTML = str;
}

function onGetListsFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

CAML 查詢

範例提供兩種查詢方式,分別按 DueDate 與 Title 篩選。點擊 Search 即可查詢。

這裡有個實作上的小發現:使用 <asp:Calendar/> 控制項時,選好日期會導致頁面 postback。SharePoint 中至少有兩種解法:

  1. 把 Calendar 控制項獨立放在某個頁面,然後用彈出視窗回傳值:
    <input type="text" id="txtDate" name="txtDate" />
    <button value="lookup" onclick="document.all['txtDate'].value =
        window.showModalDialog('Calendar.aspx');">
  2. 直接使用 SharePoint 自帶的日期控制項:
    <SharePoint:DateTimeControl runat="server" id="DateTimeControl1" DateOnly="True"></SharePoint:DateTimeControl>

另外做了一段控制項顯示的切換邏輯:選擇 Date 時顯示日期輸入框,選擇 Title 時顯示標題輸入框。

<script type="text/javascript">
function changeQueryMethod() {
    var method = $("select[id='selectQueryMethod']").val();
    if (method == 'Title') {
        document.getElementById('querybytitle').style.display = "inline";
        document.getElementById('querybyDate').style.display = "none";
    } else {
        document.getElementById('querybytitle').style.display = "none";
        document.getElementById('querybyDate').style.display = "inline";
    }
}
</script>

幾個 CAML 查詢上必須注意的知識點:

  • 查詢中若有用到 field,要留意相關 API 的呼叫方式。
  • ClientContext 若同時操作多個結果集,必須分別呼叫 Load 進行載入:clientContext.load(fieldCollection); clientContext.load(listItemCollection);
  • 若有需要讀取的欄位值,必須在 CAML 查詢的 XML 中明確宣告,否則該欄位不會出現在結果集中——這也是出於效能考量。
function search() {
    var clientContext = new SP.ClientContext();
    var oWebSite = clientContext.get_web();
    var list = oWebSite.get_lists().getByTitle("Tasks");
    fieldCollection = list.get_fields();
    var camlQuery = new SP.CamlQuery();
    camlQuery.set_viewXml(
        "<View><Query><Where><Gt>" +
        "<FieldRef Name='DueDate' />" +
        "<Value Type='DateTime'>2008-01-1T00:00:00Z</Value>" +
        "</Gt></Where></Query><ViewFields>" +
        "<FieldRef Name=\"Title\" /><FieldRef Name=\"Body\" />" +
        "<FieldRef Name=\"DueDate\" />" +
        "</ViewFields></View>"
    );
    listItemCollection = list.getItems(camlQuery);
    clientContext.load(fieldCollection);
    clientContext.load(listItemCollection);
    clientContext.executeQueryAsync(
        Function.createDelegate(this, this.onSearchListSucceeded),
        Function.createDelegate(this, this.onSearchListFailed)
    );
}

function onSearchListSucceeded() {
    var str = "";
    var listItemEnumerator = listItemCollection.getEnumerator();
    var fieldsEnumerator = fieldCollection.getEnumerator();
    while (listItemEnumerator.moveNext()) {
        var oListItem = listItemEnumerator.get_current();
        str += "Item " + oListItem.get_id() + ":"
        while (fieldsEnumerator.moveNext()) {
            var oField = fieldsEnumerator.get_current();
            str += oField.get_staticName() + "<br/>";
        }
        str += "<br/>";
    }
    document.getElementById("lists").innerHTML = str;
}

function onSearchListFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

操作檔案

有個遺憾:ECMAScript 中無法上傳檔案。雖然存在 SP.File 物件,但它主要用於操作已取回的檔案物件,而非從瀏覽器端上傳。若確實需要上傳功能,得回到伺服器端程式碼或改用其他方式處理。

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