How to: Work with Websites Using JavaScript

Applies to: SharePoint Foundation 2010

To work with websites using ECMAScript (JavaScript, JScript), start by using the ClientContext(serverRelativeUrl) constructor and pass a URL or URI to return a specific request context.

Retrieving the Properties of a Website Using JavaScript

Use the web property of the ClientContext class to specify the properties of the website object that is located at the specified context URL. After you load the website object through the load(clientObject) method and then call executeQueryAsync(succeededCallback, failedCallback), you acquire access to all the properties of that website. The following example displays the title and description of the root website in a specified site collection, although all other properties that are returned by default become available after you load the website object and execute the query. For a list of properties that are not available by default when you retrieve specific client objects, see Data Retrieval Overview.

var siteUrl = '/sites/MySiteCollection ';
    
function retrieveWebSite() {
    var clientContext = new SP.ClientContext(siteUrl);
    this.oWebsite = clientContext.get_web();

    clientContext.load(this.oWebsite);

    clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded(sender, args) {
    alert('Title: ' + this.oWebsite.get_title() + ' Decription: ' + this.oWebsite.get_description());
}
    
function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

Retrieving Only Specified Properties of a Website Using JavaScript

To reduce unnecessary data transference between client and server, you might want to return only specified properties of the website object, not all of its properties. In this case, use LINQ query or lambda expression syntax with the load(clientObject) method to specify which properties to return from the server. In the following example, only the title and creation date of the website object become available after executeQueryAsync(succeededCallback, failedCallback) is called. If you try to write, for example, oWebsite.Description to the console, you receive a PropertyOrFieldNotInitializedException.

var siteUrl = '/sites/MySiteCollection ';
    
function retrieveWebSiteProperties() {
    var clientContext = new SP.ClientContext(siteUrl);
    this.oWebsite = clientContext.get_web();

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

    clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded(sender, args) {
    alert('Title: ' + this.oWebsite.get_title() + ' Created: ' + this.oWebsite.get_created());
}
    
function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

Notice that the ClientContext(serverRelativeUrl) constructor takes a server-relative URL, and the load(clientObject) method accepts strings instead of actual LINQ objects. This differs from the managed client object model, which accepts actual LINQ objects.

Updating the Title and Description of a Website Using JavaScript

To modify a website, you set its properties and call the update()) method, similarly to how the server object model functions. However, in the client object model, you must call executeQuery(succeededCallback, failedCallback) to request batch processing of all commands that you specify. The following example changes the title and description of a specified website.

var siteUrl = '/sites/MySiteCollection ';
    
function updateWebSite() {
    var clientContext = new SP.ClientContext(siteUrl);
    this.oWebsite = clientContext.get_web();

    this.oWebsite.set_title('Updated Web Site');
    this.oWebsite.set_description('This is an updated Web site.');
    this.oWebsite.update();

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

    clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded(sender, args) {
    alert('Title: ' + this.oWebsite.get_title() + ' Decription: ' + this.oWebsite.get_description());
}
    
function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

Creating a Website

To create a website object, use the WebCreationInformation class to define its properties, and then pass this object to the add(parameters) method of the WebCollection class. The following example creates a new blog website within a site collection.

var siteUrl = '/sites/MySiteCollection ';
    
function createWebSite() {
    var blogDescription = 'A new Blog Web site.';
    var blogLanguage = 1033;
    var blogTitle = 'Blog Web Site';
    var blogUrl = 'blogwebsite';
    var blogPermissions = false;
    var webTemplate = 'BLOG#0';

    var clientContext = new SP.ClientContext(siteUrl);
    this.oWebsite = clientContext.get_web();

    var webCreateInfo = new SP.WebCreationInformation();
    webCreateInfo.set_description(blogDescription);
    webCreateInfo.set_language(blogLanguage);
    webCreateInfo.set_title(blogTitle);
    webCreateInfo.set_url(blogUrl);
    webCreateInfo.set_useSamePermissionsAsParentSite(blogPermissions);
    webCreateInfo.set_webTemplate(webTemplate);

    this.oNewWebsite = this.oWebsite.get_webs().add(webCreateInfo);

    clientContext.load(this.oNewWebsite, 'ServerRelativeUrl', 'Created');

    clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded(sender, args) {
    alert('Title: ' + this.oWebsite.get_title() + ' Description: ' + this.oWebsite.get_description());
}
    
function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

The previous example uses a LINQ query expression to return the serverRelativeUrl and created properties, whose values are not available for display unless you explicitly ask for them.

Note

When you use LINQ to create queries against the client object model, you are using LINQ to Objects, not the LINQ to SharePoint provider, which can be used only when you write code against the server object model.

See Also

Concepts

Data Retrieval Overview

SharePoint Client Object Creation

SharePoint 2010 Client Object Model Guidelines

Common Programming Tasks in the JavaScript Object Model

Other Resources

JavaScript Class Library