Sharepoint學習筆記—ECMAScript物件模型系列–1、ECMAScript物件模型的引入

    我們知道Microsoft SharePoint 2010 提供了三個新的用戶端 API，這些 API 允許您通過在瀏覽器中執行的指令碼、在 .NET 託管應用程式中執行的代碼（Microsoft .NET Framework 3.5 或更高版本）或在 Microsoft Silverlight 2.0 應用程式中執行的代碼與 SharePoint 網站進行互動。
   這裡我們來看看如何在Sharepoint網站中引入ECMAScript（JavaScript、JScript） 用戶端物件模型。
   首先是幾點說明:
   1、ECMAScript物件模型只能用於Sharepoint網站。也就是說你不能通過傳統的Asp.net網站使用ECMAScript物件模型來跨網站訪問Sharepoint網站資源。
   2、與上面類似，你也不能在一個Sharepoint網站上使用ECMAScript物件模型來跨網站訪問其它Sharepoint網站的資源。（如：從Sharepoint網站 url: MySite.MySharepoint.com通過ECMAScript物件模型去訪問另一個Sharepoint網站 url: YourSite.YourSharepoint.com上的資源）
   3、你可以把JQuery與ECMAScript物件模型直接結合使用而無需多餘的其它準備工作。你只需要在你的Sharepoint項目中引用JQuery.js就行了。
   4、當你在Sharepoint網站的Webpart頁面或者application頁面(aspx page)上使用ECMAScript物件模型時，你只需要引用SP.js就可以了。
   5、如果你打算通過ECMAScript物件模型來修改Sharepoint網站上的相關資源，你需要加入FormDigest標籤。
 

 下面談談如何讓你的Sharepoint項目具備使用ECMAScript物件模型的能力。

  我們以Sharepoint的Visual Web Part頁面為例:
  1、新建立一個Sharepoint項目，在此項目中建立一個Visual Web Part。如

             

    2、開啟此Visual Web Part下的使用者控制項的原始碼(WPEnableECMAscriptUserControl.ascx)，在裡面加入SP.js引用。(Sp.js還有一個debug版本：Sp.debug.js用於在開發時方便調試，但你不能把它部署到生產環境中) 

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

   這裡的 OnDemand意思就是按需要來載入sp.js檔案，而不是在每次Page Load時都載入Sp.js。
  

   3、如果要通過我們的Visual Web Part來更新Sharepoint網站上的資源內容，我們就需要加入FormDigest標籤。 

<SharePoint:FormDigest runat="server" /> 

   有了這個標籤，當你提交的修改資料的頁面回傳到後台伺服器時，目前使用者的seruity token也會隨著此頁面一同提交。這樣的安全機制能保證Sharepoint的相關資源被有效修改。 下面是有關此標籤的更多說明
   http://msdn.microsoft.com/en-us/library/microsoft.sharepoint.webcontrols.formdigest%28office.14%29.aspx
   http://msdn.microsoft.com/en-us/library/ms472879%28office.14%29.aspx

  

   4. 使用ECMAScript物件模型擷取Sharepoint資源資訊
   在WPEnableECMAscriptUserControl.ascx源檔案中加入如下代碼

 

<script type="text/javascript">
    //Get WebSite Information
    function retrieveWebSiteonQuerySucceeded(sender, args) {
        alert('Title: ' + this.oWebsite.get_title() + ' Decription: ' + this.oWebsite.get_description());
    }

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

    function retrieveWebSite() {
        var clientContext = new SP.ClientContext.get_current();
        this.oWebsite = clientContext.get_web();
        // clientContext.load(this.oWebsite);
        clientContext.load(this.oWebsite, 'Title', 'Description');
        clientContext.executeQueryAsync(Function.createDelegate(this, this.retrieveWebSiteonQuerySucceeded),
         Function.createDelegate(this, this.retrieveWebSiteonQueryFailed));
    }
</script>

   此代碼做的第一件事就是擷取ClientContext（如同擷取SPContext對象一樣）
   然後通過context.get_web來擷取當前的Web(如同擷取SPContext.Current.Web一樣)
   然後再通過load方法來載入相關的對象(web object)，此處我們載入WebSite對象。並將在後續步驟中提取此對象裡的有關資訊。
   接下來通過executeQueryAsync方法來啟用非同步作業,並定義了非同步作業的兩種情況及對應的處理方法 retrieveWebSiteonQuerySucceeded與retrieveWebSiteonQueryFailed.
   在retrieveWebSiteonQuerySucceeded方法中我們提供了Website對象的Title與Description屬性，並在快顯視窗中顯示出來。

   而如果非同步作業失敗，我們會在retrieveWebSiteonQueryFailed方法中提示出錯資訊。
  

   5.關於按需載入相關資訊。
     在上面的代碼中，clientContext.load(this.oWebsite);這個方法只使用了oWebsite參數，也就是說，此Load方法會載入有關oWebSite對象的所有屬性。但是，在此例中，我們並不需要關心那麼多屬性（我們只關心Title,Description屬性），所以我們可以明確我們需要載入的對象屬性，以此來減少系統資訊交換的負擔，提高資訊交換效率。我們可以通過如下代碼

 clientContext.load(this.oWebsite, 'Title', 'Description');

  關於擷取資訊的代碼執行效果如下:

 
6、在sp.js被載入後才執行你的JavaScript代碼。
  有時你想要執行的Javascript代碼功能會基於sp.js檔案，如果sp.js沒有載入，你所定義的Javascript代碼就會報錯。因此，我們需要人為介入，保證sp.js在我們定義的Javascript功能之前先行載入。 為達到此目的，我們需要使用ExecuteOrDelayUntilScriptLoaded功能。代碼如下

ExecuteOrDelayUntilScriptLoaded(myjsfucntion, "sp.js");

  其中myjsfucntion就是你所定義的Javascript功能代碼（如：上面定義的retrieveWebSite）。

 

 7. 通過ECMAScript物件模型完成對網站標題的更新
通過ECMAScript物件模型我們可以修改Sharepoint網站中的相關資源，這裡，我們使用它來修改當前網站的Title。

 

<script type="text/javascript">
    //Update WebSite Title
    function updateTitle() {
        var ctx = new SP.ClientContext.get_current();
        this.web = ctx.get_web();
        web.set_title('UpdatedTitle');
        this.web.update();
        ctx.executeQueryAsync(Function.createDelegate(this, this.onUpdate),
               Function.createDelegate(this, this.onFail));

    }
    function onUpdate(sender, args) {
        alert('title updated');
    }
    function onFail(sender, args) {
        alert('failed to update title. Error:' + args.get_message());
    }
</script>

   在ECMAScript物件模型中，使用get_propertyName來擷取相應屬性的值，

   使用set_propertyName來設定相應屬性的值。

   當然，不要忘了加入FormDigest標籤以使更新操作正常進行。

  執行效果如下:

 

 

 

8、在ECMAScript物件模型中使用JQuery
  ECMAScript物件模型與JQuery沒有任何衝突，你只需要加入JQuery的引用即可，唯一需要注意的就是如果你想要在Page Load Event中執行Javascript，你必須把這個 Javascript的功能段放置到ExecuteOrDelayUntilScriptLoaded中（如上面所示）

  如果添加JQuery可以參考Sharepoint學習筆記—Delegate Control--在Sharepoint頁面添加jQuery

9、部署時需要注意的
 Sharepoint提供了兩個版本的Sp.js (即：Sp.js與Sp.debug.js)。它們通過Sharepoint網站的MasterPage裡的scriptmanager來載入。預設情況下Scriptmanager的ScriptMode設定為auto，即自動載入Sp.js。如果你想要載入Debug版本，你需要修改web.config中的<system.web> 節下的<deployment retail="false" /> 。
  當然，當你部署到生產機時，你必須載入Sp.js而不是Sp.debug.js。
  ECMAScript物件模型支援下面的瀏覽器:
  Microsoft Internet Explorer 7.0及以上.
  Firefox 3.5 及以上
  Safari 4.0 及以上