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 及以上