Pages

Sunday, February 21, 2010

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 <SharePoint:ScriptLink Name=”sp.js” ………. />. 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.

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 <form>…</form> tag, as shown 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.

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.

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:

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 <deployment retail="false" /> in the <system.web> 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.

Tuesday, February 16, 2010

The client Object Model for Managed .net application allows any .net managed application to communicate with SharePoint server without using any web service reference. Say you have a WPF application and from that WPF application you need to get data from SharePoint calendar. In the days of SharePoint 2007 you could read the calendar data from SharePoint through web service. If the out of box web service could not meet your demand then you needed to develop your custom web services. But with Client OM you can now program against SharePoint on the client side. In my first post on Client OM I had gone through the some basics. In this post I’ll cover how to use Client OM in managed .net applications (like windows, web, console etc).

Steps to use Client OM with Managed .net application

1. Create a new project (like console, wpf, web etc) in Visual Studio 2010. During creating the project make sure you have selected the target framework to 3.5. By default VS2010 uses .net framework 4 but Client OM will not function with .net framework. The following figure shows the “Add New Project” window with targeted framework selected as 3.5.

Figure 1: New Project dialog

2. To use Client OM with your project add reference to two following DLLs to the project from the directory C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\ISAPI.

Microsoft.SharePoint.Client.dll

Microsoft.SharePoint.Client.Runtime.dll

3. Now you can use Client OM. The core object in the client OM is ClientContext. You’ll need to initialize the ClientContext with the SharePoint site url. Let’s dig dipper inside Client OM.

Few points to notice about the code snippet that uses Client OM above:

a) The ClientContext is needed to initialize with SharePoint site’s url.

b) ClientContext.Load takes the SharePoint object to load as first parameter. The next parameters are the properties to be loaded for the object. As shown in the code snippet the load method is invoked asking only one attribute to load (Create Date).

c) To optimize data retrieval, the Client OM queue all requests to the SharePoint server till an invocation to the ExecuteQuery is made. So no data will be available from the server till the ExecuteQuery method is invoked. After finishing the ExecuteQuery method invocation the properties asked to load in the Load method is populated.

d) If you want to use a property that you are not asked to load in the ClientContext.Load method, you’ll get PropertyOrFieldNotInitializedException is thrown. The same exception will be thrown if you want to use any property of the Client object before calling the ExecuteQuery method.

In the above code snippet, if I tried to use web.Created property before context.ExecuteQuery, I would get PropertyOrFieldNotInitializedException. Even after calling ExecuteQuery, if you try to use any other properties that you have specified in load method (like web.Id or web.Title in above code snippet), you’ll get the same exception. To get more properties of web you need to provide the property/field name in the load method. For example, to load Title and Id you need to modify the load method as shown below:

context.Load(web, w => w.Created,w=>w.Title,w=>w.Id);

Similarly you can specify as much property as you need. However if you don’ t provide any second parameter to the load method as shown below, then all properties of the object will be loaded. The following load method will populate all fields of web object.

context.Load(web);

In real life scenario, we will barely need to use the above load method as it’ll send a large amount data to the client which is waste of network bandwidth and server resources.

Load properties/Fields selectively

As I have specified before, in Client OM you can specify the fields/properties to load. The load method of ClientContext works two ways:

1. For single item: For a single item the load methods take a series of arguments that specify the property to load for the item. For example the following few statements load one two and three properties correspondingly.

2. For List of items: To specify properties/fields to load for each item of the list, an extension method ‘include’ is used. As the following code snippet shows, a caml query is used to filter data from list. Then in the load method I have used ‘include’ extension method to specify the properties to be loaded.

Update List with Client OM

With Client OM, you can update list items. As shown in Code Snippet 3, you can get the data as soon as the first clientContext.ExecuteQuery is invoked. After that you can loop through all the list items and update the list item. To send back changes to the server again you need invoke ExecuteQuery method again. The following code snippet show how a list is filtered and then updated.

The important thing to notice in the above code snippet is that the ClientContext.ExecuteQuery is invoked twice. Once to get list items from server. Then after modifying list item on the client side, we need to invoke the ExecuteQuery again to send data back to the server. To delete a list item you need to call the DeleteObject method of the list item. The following code snippet shows how you can delete an item.

foreach (ListItem item in listItems)
{
item.DeleteObject();
}

Authentication with Client OM

To specify authentication in the client context you need to set the context.AuthenticationMode Property with either default, anonymous or forms. For forms authentication you also need to set a instance of FormsAuthenticationLoginInfo object to the property FormsAuthenticationLoginInfo. The following code snippet shows how to use form authentication with Client OM.

Optimization in Client OM

Two methods play important roles in optimizing the Client OM. One is ClientContext.Load method. This method helps us to specify the properties of an object we want to retrieve. If this option would not be available then whenever we needed to load the Web object, a lot of unnecessary properties would be sent to the client. This would case heavy unnecessary traffic to the system. This would also cause the server to load too much unnecessary data and process it.

Another optimization is done with ExecuteQuery. Since all operations against ClientContext are queued till this method is called the number of round-trip to the server is reduced significantly. But with the introduction of ExecuteQuery, developers need to change their mindset as we can’t just call any field or property as we want rather we need to call ExecuteQuery first.

Deployment Consideration

When you use .net Managed Client OM you only need two extra assemblies (Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Runtime.dll). So your code will have no web services reference.

Friday, February 12, 2010

You can create a document library with several document templates for example, excel, word, webpart page etc. If you need to create a document library with ‘web part page’ document template programmatically then you can do it without enabling publishing feature. Most of the examples on the web uses publishing feature.

Create a new document library with ‘web part page’ document template

The following code snippet shows how to Create the web part page document library.

In the CreateWebPartPageLibrary method, the first line get the template for document library. Then the GetWebPartPageDocTemplate return the document template for “web part page”. Finally I have called web.lists.add method to add our new list to the list collection.

Add a web part page in Web Part page library

Once you have web part page library, you need to add web part page in the library. You can do so programmatically. To add the page you need to prepare an xml command and execute with with ProcessBatchData method.

In the above code snippet a command is prepared to generate a web part page. In the command the Type is WebPartPage. WebPartPageTemplate is for different page layout that we can find in the sharepoint UI. The page title is only title without aspx.

Add web part to webpart page

You have created a ‘web part page’ library and added a webpart page. Now you need to add your web part in that page. First of all you need to create a web part instance. The following code Snippet shows how to create a web part programmatically.

The web part name in the above method GetWebPart() is like “employeeviewer.webpart”. The webpart collection exists in the rootweb. So I have check the IsRootWeb to make sure I run the caml query against the root web.

Once you have got the web part instance created by Activator.CreateInstance you can add it in the page.

The code snippet above call the GetWebPart() method to get the instance of the web part. Then using LimitedWebPartManager it get the page’s web part manager. Then it check if the web par already exists in the page by checking title. And finally add the web part if it doesn’t exists. FYI, be careful to dispose webpart and SPLimtiedWebPartManager.

Monday, February 8, 2010

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:

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.

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).

Thursday, February 4, 2010

When you navigate to Site Settings –> create page you’ll be directed to the create.aspx page as shown below:

Figure 1: create page

Now if you want to hide some options in the create page, then how will you do that? Say you don’t want to show the “Document Library” option or you want to hide this option for a particular user or group.

Hide option for all users

Say you want to hide “Document Library” option for all users. The following steps will guide you how to do so. But before you proceed with the steps please backup your original create.aspx page.

1. Locate the create.aspx page on your disk: If you take a look at the url of the create page you’ll find it something like “http://server:port/_layouts/create.aspx”. So the create page is from layout folder which is from “Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\template\layouts”. You can open the Create.aspx page in Visual Studio. In the page you’ll find a code block as shown below:

The above code block actually add create options in the page. So if you modify the code block you can filter the options to show on the page.

2. Find the feature id of the create option you want to hide: In order to hide the option you need to know the feature id associated with this create option. To do so move your mouse over the “Document Library” and you’ll find the feature id as shown below:

Figure 2: Find feature ID from create page

3. Modify the Create.aspx page to hide option: From step 2 we have found the feature id (of Document Library). Now we need to modify the code in the page to hide the option.

Make sure the hide/show change doesn’t affect other sites

If you make changes to the original create.aspx page then all the sites in that web serve will be affected as the file is shared across all sites. To make sure that only your site gets affected for the changes you need to follow the following steps:

2. Go to IIS and expand the site and navigate to the _layouts tree node. Then open the _layouts properties window and change the local path to the place where you have copied folder on step 1(in my case 80_layouts). This is shown below:

Figure 3: Change the _layouts virtual directory location

3. Now you can modify the create.aspx page following the steps described on step “hide option for all users” or “hide options based on user/group”.