This documentation is archived and is not being maintained.

SP.List object

SharePoint 2013

Represents a list on a SharePoint Web site.

Last modified: March 09, 2015

Applies to: apps for SharePoint | SharePoint Foundation 2013 | SharePoint Server 2013

var object = new SP.List()

Members

The List object has the following members.

Constructor

The List object has the following constructor.

Constructor	Description
List	Initializes a new instance of the SP.List object.

Methods

The List object has the following methods.

Method	Description
addItem	Creates a new list item in the list.
deleteObject	Deletes the list.
getChanges	Returns the collection of changes from the change log that have occurred within the list, based on the specified query.
getItemById	Returns the list item with the specified list item identifier.
getItems	Returns a collection of items from the list based on the specified query.
getListItemChangesSinceToken
getRelatedFields	Returns a collection of lookup fields that use this list as a data source and that have FieldLookup.IsRelationship set to true.
getRelatedFieldsExtendedData	This member is reserved for internal use and is not intended to be used directly from your code.
getUserEffectivePermissions
getView	Returns the list view with the specified view identifier.
recycle	Moves the list to the Recycle Bin and returns the identifier of the new Recycle Bin item.
renderListData
renderListFormData
reserveListItemId
saveAsNewView
update	Updates the database with changes that are made to the list.

Properties

The List object has the following properties.

Property	Description
allowContentTypes	Gets a value that specifies whether the list supports content types.
baseTemplate	Gets the list definition type on which the list is based.
baseType	Gets the base type for the list.
browserFileHandling	Gets a value that specifies the override of the web application's BrowserFileHandling property at the list level.
contentTypes	Gets the content types that are associated with the list.
contentTypesEnabled	Gets or sets a value that specifies whether content types are enabled for the list.
created	Gets a value that specifies when the list was created.
dataSource	Gets the data source associated with the list, or null if the list is not a virtual list.
defaultContentApprovalWorkflowId	Gets or sets a value that specifies the default workflow identifier for content approval on the list.
defaultDisplayFormUrl	Gets or sets a value that specifies the location of the default display form for the list.
defaultEditFormUrl	Gets or sets a value that specifies the URL of the edit form to use for list items in the list.
defaultNewFormUrl	Gets or sets a value that specifies the location of the default new form for the list.
defaultView
defaultViewUrl	Gets the URL of the default view for the list.
description	Gets or sets a value that specifies the description of the list.
direction	Gets or sets a value that specifies the reading order of the list.
documentTemplateUrl	Gets or sets a value that specifies the server-relative URL of the document template for the list.
draftVersionVisibility	Gets or sets a value that specifies the minimum permission required to view minor versions and drafts within the list.
effectiveBasePermissions	Gets a value that specifies the effective permissions on the list that are assigned to the current user.
effectiveBasePermissionsForUI
enableAttachments	Gets or sets a value that specifies whether list item attachments are enabled for the list.
enableFolderCreation	Gets or sets a value that specifies whether new list folders can be added to the list.
enableMinorVersions	Gets or sets a value that specifies whether minor versions are enabled for the list.
enableModeration	Gets or sets a value that specifies whether content approval is enabled for the list.
enableVersioning	Gets or sets a value that specifies whether historical versions of list items and documents can be created in the list.
entityTypeName
eventReceivers
fields	Gets a value that specifies the collection of all fields in the list.
forceCheckout	Gets or sets a value that indicates whether forced checkout is enabled for the document library.
forms	Gets a value that specifies the collection of all list forms in the list.
hasExternalDataSource	Gets a value that specifies whether the list is an external list.
hidden	Gets or sets a Boolean value that specifies whether the list is hidden.
id	Gets the GUID that identifies the list in the database.
imageUrl	Gets a value that specifies the URI for the icon of the list.
informationRightsManagementSettings
irmEnabled
irmExpire
irmReject
isApplicationList	Gets or sets a value that specifies a flag that a client application can use to determine whether to display the list.
isCatalog	Gets a value that specifies whether the list is a gallery.
isPrivate
isSiteAssetsLibrary	Gets a value that indicates whether the list is designated as a default asset location for images or other files which the users upload to their wiki pages.
itemCount	Gets a value that specifies the number of list items in the list.
lastItemDeletedDate	Gets a value that specifies the last time a list item was deleted from the list.
lastItemModifiedDate	Gets a value that specifies the last time a list item, field, or property of the list was modified.
listItemEntityTypeFullName
multipleDataList	Gets or sets a value that indicates whether the list in a Meeting Workspace site contains data for multiple meeting instances within the site.
noCrawl	Gets or sets a value that specifies that the crawler must not crawl the list.
onQuickLaunch	Gets or sets a value that specifies whether the list appears on the Quick Launch of the site.
parentWeb	Gets a value that specifies the site that contains the list.
parentWebUrl	Gets a value that specifies the server-relative URL of the site that contains the list.
rootFolder	Gets the root folder that contains the files in the list and any related files.
schemaXml	Gets a value that specifies the list schema of the list.
serverTemplateCanCreateFolders	Gets a value that indicates whether folders can be created within the list.
templateFeatureId	Gets a value that specifies the feature identifier of the feature that contains the list schema for the list.
title	Gets or sets the displayed title for the list.
userCustomActions	Gets a value that specifies the collection of all user custom actions for the list.
validationFormula	Gets or sets a value that specifies the data validation criteria for a list item.
validationMessage	Gets or sets a value that specifies the error message returned when data validation fails for a list item.
views	Gets a value that specifies the collection of all public views on the list and personal views of the current user on the list.
workflowAssociations	Gets a value that specifies the collection of all workflow associations for the list.

The BrowserFileHandling, DataSource, EffectiveBasePermissions, HasUniqueRoleAssignments, IsAttachmentLibrary, OnQuickLaunch, SchemaXml, ValidationFormula and ValidationMessage properties are not included in the default scalar property set for this type.

Example

The following example creates an input button on an application page that creates a new discussion board list on the current web site.

JScript

<asp:Content ID="Main" ContentPlaceHolderID="PlaceHolderMain" runat="server">
<script type="text/ecmascript" language="ecmascript">

    var list;
    function runCode() {
        var clientContext = new SP.ClientContext.get_current();

        if (clientContext != undefined && clientContext != null) {
            var web = clientContext.get_web();

            // Specify the properties of the new list.
            var listCreationInfo = new SP.ListCreationInformation();
            listCreationInfo.set_title('New Discussion Board');
            listCreationInfo.set_templateType(SP.ListTemplateType.discussionBoard);

            this.list = web.get_lists().add(listCreationInfo);

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

    function onQuerySucceeded() {
        var result = ' Added Discussion Board: ' + this.list.get_title();
        alert(result);
    }

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

</script>

    <input id="Button1" type="button" value="Run Code" onclick="runCode()" />

</asp:Content>

REST resource endpoint

See List resource for more information.

Endpoint URI structure

http://<sitecollection>/<site>/_api/web/lists(listid)

HTTP requests

This resource supports the following HTTP commands:

DELETE

DELETE syntax

DELETE http://<sitecollection>/<site>/_api/web/lists(listid)

MERGE syntax

MERGE http://<sitecollection>/<site>/_api/web/lists(listid)

POST syntax

POST http://<sitecollection>/<site>/_api/web/lists(listid)

PUT syntax

PUT http://<sitecollection>/<site>/_api/web/lists(listid)