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