How to: Create, Update, and Delete Lists Using JavaScript

Applies to: SharePoint Foundation 2010

Creating, updating, and deleting lists through the client object model works similarly to how you perform these tasks using the server object model, although client operations do not complete until you call the executeQueryAsync(succeededCallback, failedCallback) function.

Creating and Updating a List Using JavaScript

To create a list object using ECMAScript (JavaScript, JScript), use the ListCreationInformation object to define its properties, and then pass this object to the add(parameters) function of the ListCollection object. The following example creates a new announcements list.

var siteUrl = '/sites/MySiteCollection';

function createList() {
    var clientContext = new SP.ClientContext(siteUrl);
    var oWebsite = clientContext.get_web();
    
    var listCreationInfo = new SP.ListCreationInformation();
    listCreationInfo.set_title('My Announcements List');
    listCreationInfo.set_templateType(SP.ListTemplateType.announcements);

    this.oList = oWebsite.get_lists().add(listCreationInfo);

    clientContext.load(oList);

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

function onQuerySucceeded() {
    var result = oList.get_title() + ' created.';
    alert(result);
}

function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

If you need to update the list after the list has been added, you can set list properties and call the update() function before calling executeQueryAsync(succeededCallback, failedCallback), as shown in the following modifications of the previous example.

            .
            .
            .
            .
            this.oList = oWebsite.get_lists().add(listCreationInfo);

            oList.set_description('New Announcements List');

            oList.update();

            clientContext.load(oList);

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

Adding a Field to a List Using JavaScript

Use the add(field) or addFieldAsXml(schemaXml, addToDefaultView, options) function of the FieldCollection object to add a field to the field collection of a list. The following example creates a field and then updates it before calling executeQueryAsync(succeededCallback, failedCallback).

var siteUrl = '/sites/MySiteCollection';

function addFieldToList() {
    var clientContext = new SP.ClientContext(siteUrl);

    var oList = clientContext.get_web().get_lists().getByTitle('Announcements');

    this.oField = oList.get_fields().addFieldAsXml('<Field DisplayName=\'MyField\' Type=\'Number\' />', true, SP.AddFieldOptions.defaultValue);

    var fieldNumber = clientContext.castTo(oField,SP.FieldNumber);
    fieldNumber.set_maximumValue(100);
    fieldNumber.set_minimumValue(35);

    fieldNumber.update();

    clientContext.load(oField);

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

function onQuerySucceeded() {
    var result = oField.get_title() + ' added.';
    alert(result);
}

function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

The previous example uses the castTo(obj, type) function of the client context object to cast the field as a FieldNumber object, which you must do before executing the query. Otherwise, the client object model does not know the real type of the returned object oField and, by default, uses Field as the object type.

Deleting a List Using JavaScript

To delete a list, call the deleteObject() function of the list object, as shown in the following example.

var siteUrl = '/sites/MySiteCollection';

function deleteList() {
    var clientContext = new SP.ClientContext(siteUrl);
    var oWebsite = clientContext.get_web();
    this.listTitle = 'My Announcements List';

    this.oList = oWebsite.get_lists().getByTitle(listTitle);

    oList.deleteObject();

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

function onQuerySucceeded() {
    var result = listTitle + ' deleted.';
    alert(result);
}

function onQueryFailed(sender, args) {
    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

See Also

Concepts

SharePoint Client Object Creation

SharePoint 2010 Client Object Model Guidelines

Data Retrieval Overview

How to: Retrieve Lists Using JavaScript

Common Programming Tasks in the JavaScript Object Model

Other Resources

JavaScript Class Library