Tuesday, August 10, 2010

SharePoint 2010: Client Object Model for JavaScript (ECMAScript)

Copyright from: Sohel_Rana
As I said in my first post on Client Object Model (OM), there are three sets of Client OM: Managed .net client, Silverlight and ECMAScript. Lately I have posted an article on how to use Client OM from Managed .Net Client.Today I’ll go through Client OM for JavaScript.  ECMAScript Client OM is SharePoint 2010 client object model extension for using with JavaScript or JScript. Few points to notice about ECMAScript Client OM:
  • ECMAScript object model can only be used in SharePoint sites. So you can’t use this object model in an asp.net site to access SharePoint resources deployed in another url as this is cross-site scripting and not allowed.
  • You can’t use this object model in a SharePoint site to access resources in different SharePoint sites(i.e., different urls). For example, from mysite.mysp.com you can access resources in yoursite.yoursp.com using ECMAScript client OM. This is also cross-site scripting.
  • You can use JQuery with ECMAScript Client OM and for this you don’t need to do some extra work. All you need to do to use JQuery is to add reference to JQuery.js file and start using JQuery.
  • You can use this ECMAScript Client OM in web part pages or application pages (aspx pages) by referencing a javascript file (SP.js). You don’t need to add reference to the file manually rather use . The file is located on the path “Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS”
  • To update with JavaScript, you need to add a FormDigest tag in your page for security purpose. I’ll explain it later in details.

Use ECMAScript Library

At first use Visual Studio 2010 to create a SharePoint web part project. As a result, VS2010 will open a ascx control for you on the designer. 

1. Add reference to js file:

To use Client OM, add an entry like below in your web part ascx control. For your information, there’s an debug version of the sp.js called sp.debug.js which you can use for debugging but should not be used in production.
Collapse
<SharePoint:ScriptLink Name="SP.js" runat="server" OnDemand="true" 
    Localizable="false" />
Here, OnDemand means whether the sp.js file need to be loaded on demand (not in page load) or not.

2. Add FormDigest tag:

If your code modifies SharePoint content add a FormDigest control inside your page. The FormDigest add a security token inside your page based on user, site and time. Once the page is posted back the security token is validated. Once the security token is generated it’s valid for a configurable amount of time. Add the FormDigest inside
tag, as shown below:
Collapse
<SharePoint:FormDigest runat="server" />
For more information on FormDigest follow the links below:

3. Use Client OM to retrieve data:

Now you can use SharePoint ECMAScript library. Lets dissect the code snippet below. The first thing in using this library is that you need to get the ClientContext (just like SPContext). Then the context.get_web returns the current web (just like SPContext.Current.Web). Then client context’s load method is invoked passing the web object. Then the executequery method is invoked asynchronously passing two functions: onSuccess and OnFailed which will be called on success and fail correspondingly.
Collapse
<script type="text/javascript">
    function getWebProperties() {
        var ctx = new SP.ClientContext.get_current();
        this.web = ctx.get_web();
        ctx.load(this.web);
        ctx.executeQueryAsync(Function.createDelegate(this, this.onSuccess),
            Function.createDelegate(this, this.onFail));
    }
    function onSuccess(sender, args) {
        alert('web title:' + this.web.get_title() + '\n ID:' + this.web.get_id() +             '\n Created Date:' + this.web.get_created());    }
    function onFail(sender, args) {
        alert('failed to get list. Error:'+args.get_message());    }
script>
By calling getWebProperties method from any web part, you can get the current web’s title, id and creation date.

4. Load minimal data you need:

In the above code snippet, the Ctx.load method is invoked with only one parameter (web). The load method will load all properties of the web object. But we are only using Id, Title and Created Date properties. If you know which properties you are interested in, you can pass the properties names in the load method and only those properties will be loaded. For example the following load method will return only ID, Title and Created Date.
Collapse
ctx.load(this.web,'Title','Id','Created');
Remember, here the properties names are properties of SPWeb. You need to pass Title instead of title. The properties name uses CAML casing. You can get the full lists of ECMAScript namespaces, object, properties following the link on MSDN. The document is not final yet and may be changed. You can also look into the sp.debug.js file in the folder “Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS”, to get an idea of objects, properties and methods of ECMAScript Client OM.

5. Execute your JavaScript function after sp.js is loaded:

Sometimes you may need to execute your JavaScript (that uses ECMAScript Client OM) on page load in the browser. But since your JavaScript is using sp.js file and if the sp.js file is not loaded yet (since to lazy loading nature of sp.js), when your custom JavaScript will be executing, you’ll get your JavaScript function not executed. In this case you need to make sure your JavaScript code runs after sp.js finishes loading. You can do so by putting your JavaScript method call inside a js function as shown below:
Collapse
ExecuteOrDelayUntilScriptLoaded(myjsfucntion, "sp.js");
Putting your JavaScript function (i.e., myjsfunction) inside the ExecuteOrDelyUntilScriptLoaded method delays your method call until the sp.js file is loaded.

6. Update with ECMAScript Library:

You can use the Client OM to update SharePoint contents. The following code snippet shows how to update web title.
Collapse
<script type="text/javascript">
    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>
By calling the updateTitle method from any web part or SharePoint application pages, you can change the title of current web site (where the web part or application page is deployed). For your information, in ECMAScript Client OM, to get an property use get_propertyName and to set a property use set_propertyName. To update list with ECMAScript library you need to add FormDigest tag.

Use JQuery with ECMAScript

You can use JQuery with ECMAScript without any conflict. As usual, you need to add jquery.js file reference to your page/web part or in master page. Then you can use JQuery as like normal asp.net applications. But make sure that if you need to execute any JavaScript function on page load event, you put this inside ExecuteOrDelayUntilScriptLoaded function.

Deployment Consideration

SharePoint provides two sets of JavaScript file: minified and unminified/debug version. For example sp.js file is minified and sp.debug is minified and debug version. The default master page in SharePoint has a scriptmanager in the page and whose ScriptMode is set to auto, as a result the minified version of js file loaded. If you want to use debug version you can add the in the section of the web.config. In the production you need to remove this entry to make sure minified version is used. The ECMAScript supported in the following browsers:
  • Microsoft Internet Explorer 7.0 or greater.
  • Firefox 3.5 or greater
  • Safari 4.0 or greater

More Information

To get the full list of namespaces and Classes, you can download the SharePoint 2010 SDK or you can follow the link on MSDN.

SharePoint 2010: Client Object Model – an Introduction

Copyright from: Sohel's Blog

SharePoint 2007 allows using its Object model to run against server running SharePoint. For clients (not running SharePoint in the box) the simplest way to communicate with SharePoint server is web services. SharePoint Client Object Model (OM) can be run on client PC (where SharePoint is not installed) to communicate with SharePoint server. So whereas SharePoint (Server) Object Model runs in a SharePoint server and can manipulate SharePoint objects, Client OM can run in client PC and communicate with SharePoint server remotely.
SharePoint 2010 introduces three new client APIs which can be used to interact with SharePoint sites. The three APIs are targeted for three different types of clients:
1. For .net Managed applications (for example, console applications, window applications, web applications etc, which are not running inside SharePoint Context).
2. For Silverlight applications.
3. For using with JavaScript (called ECMAScript). This API is only available for applications hosted inside SharePoint (for example, web part deployed in SharePoint site can use this JavaScript API for accessing SharePoint from browser using JavaScript).
I’ll explain all of these API sets gradually. In this post I’ll explain some basic problems SharePoint developers faced during development with SharePoint 2007 in absence of Client Object Model.

Why Client Object Model (OM)?

SharePoint 2007 had no Client Object model available. So you may ask why this is introduced in SharePoint 2010? We had no problem without Client OM and millions of sites are running smoothly without having Client OM. The main reason is that Microsoft has found lot of requests from SharePoint users to introduce more and more web services to get data out of SharePoint in the last couple of years. But introducing web services will not fix the issues, as Microsoft found, because then the request for more functionality in the web services will continue. Even if Microsoft provides a good numbers of web services with SharePoint, customization in web services will be required for different clients and this will make the out of the box web services unusable. Also introducing a large number of web services will be a waste as not all companies will use all the web services functionalities.
In response to add more web services from users, Microsoft has taken a different approach called Client Object Model (OM). This SharePoint Client OM will allow getting data out of SharePoint from PCs that are not hosting SharePoint. Also Client OM provides complete API to interact with SharePoint Server which is more intuitive and useful and very much similar with SharePoint Object Model.

Similarity with SharePoint Object Model

Now SharePoint developers will fear that the Client Object Model will introduce new burden for them to get used to it. But SharePoint team provided great efforts to keep the Client OM familiar with SharePoint Object Model. The following table shows the equivalent objects in Client and SharePoint Object Model.
Server (Microsoft.SharePoint)
Client Object Model
SPContext
ClientContext
SPSite
Site
SPWeb
Web
SPList
List
SPListItem
ListItem
SPField
Field
So the class names in Client OM are similar as like SharePoint Object Model. However the way client OM will be used a bit different than usual SharePoint Object Model that we will explore in the upcoming posts.

How Client OM is developed and work under the hood?

It’s interesting how SharePoint team has developed the same set of classes for three different sets of applications (Managed, Silverlight and ECMAScript). There is same class ListItem for three different set of applications. As shown in the following table, three different assemblies/files are used for three different types of applications.
Client Type
Assembly/File
Managed Client
Microsoft.SharePoint.Client
Silverlight
Microsoft.SharePoint.Client.Silverlight
ECMAScript
SP.js
To ensure the same class object (say ListItem) behaves similarly in three different types of applications SharePoint team followed the steps described below:
a) SharePoint team first set attributes to the SharePoint classes and methods and properties that need to be exposed in Client OM.
b) Then a code generator is run against the SharePoint object model to generate client OM automatically.
This automated code generation has ensured maximum compatibility between these three sets of APIs. As the following figure shows client communicate to the server thorough Client OM which under the hood uses Client.svc WCF service to communicate with SharePoint Server. Client.svc service uses Server OM as per client request and return result to the client in JSON format.


image
Figure: How Client Object model works with Server
With this new Client OM, we almost don’t need to use web service to communicate with SharePoint server. However, the client OM just released and we will find its shortcomings as well use it more and more in live projects. In my next posts I’ll go through three differents kinds of Client OM (Managed .net, Silverlight and ECMAScript).

Tuesday, August 3, 2010

Editing contents of a WSP (SharePoint)

  1. Rename the WSP to CAB
  2. Extract all contents to a folder – using Windows Explorer, or WinZip, WinRAR, or whatever
  3. Change the items you want, ie. MANIFEST.XML and remove a DLL (in my case)
  4. Create a new CAB file with the updated contents, using IZARC 
  5. Rename the newly created CAB to WSP
  6. Install to SharePoint 
PS: using IZARC
  1. Open IZArc as a ‘program’
  2. Create a new archive
  3. Choose a CAB file type
  4. Add the files – and check the box for “subfolders”

Monday, August 2, 2010

Referencing Javascript Files with SharePoint 2010 Custom Actions using SciptSrc

copy right from: Jan Tielens' Bloggings
If you’re an avid reader of this blog, you are probably aware of the fact that using Javascript plus SharePoint is a very powerful combination. In SharePoint 2007 there were a couple of techniques you could use to make sure your Javascript files would be referenced by SharePoint pages:
  1. Add the Script reference to the Master Page
  2. Use a Delegate Control (e.g. the AdditionalPageHead)
  3. Dynamically through code, e.g. in a Web Part
Although all those techniques work, and will still work in SharePoint 2010, they all have some limitations. The first technique requires you to build a custom Master Page, which may be a little overkill just to get a Javascript file referenced. Additionally, your custom Master Page is not used on Application Pages (unless you use the Superbranding trick). The second is my favorite one in SharePoint 2007, but the requirement is that the Master Page you’re using has the corresponding Delegate Control, and you need to have either a Server Control or Web User Control that generates HTML to reference the script. The third technique is nice if you only want to use the script when the Web Part is on the page, otherwise you’ll have to put the Web Part on every page where you’d like to reference the script.
SharePoint 2010 is adding another very interesting technique to this list; using the ScriptSrc attribute of the CustomAction element in a Feature. Check the following Feature Elements file:
http://schemas.microsoft.com/sharepoint/">
 
      ScriptSrc="
JSDemo/jquery-1.4.2.js"
      Location="ScriptLink"
      Sequence="100"
      >
 
 
The first important thing to notice is that the CustomAction element contains the ScrptSrc attribute that points in this example to the jQuery Javascript library. The jQuery library is added to the /_layouts folder in the SharePoint Root, in a folder called JSDemo (the /_layouts/ prefix is added automatically). By the way, adding files to the /_layouts folder is very easy in a SharePoint project in Visual Studio 2010, using a Mapped Folder.  The second important attribute is the Location; it must be set to ScriptLink so the Javascript file is referenced in the head element of the page. Optionally you can specify a Sequence attribute to determine the in which order the script references will be added (if you have multiple). When Feature is activated, it results in the following HTML:
document.write('