Chapter 5
Managing SharePoint Lists

IN THIS CHAPTER

• List Management Basics
• Enumerating Lists
• Enumerating List Contents
• Adding, Removing, and Updating Lists
• Manipulating List Items
• Using Lookup Types in Lists

Of all the different kinds of classes available to the developer within the SharePoint application programming interface (API), the ones that you will encounter most often will most likely be lists and list items (SPList and SPListItem, respectively). This chapter provides you with an introduction to the basics of reading and writing lists and list items. Knowing how to work with lists will give you the necessary foundation to move on to more advanced list topics as well as to more complex data types. The next two chapters provide more advanced list topics such as querying lists using CAML queries and creating event sinks and listeners for list events.

There are a lot of tables in this chapter showing the various properties and methods of some of the core, list-related classes. Lists are one of the keystones of SharePoint development and every SharePoint developer should have a firm grasp of how to work with lists.

List Management Basics

This section of the chapter provides you with an overview of the basics of list management, including sample code. When working with lists in SharePoint, you will be performing some or all of the following actions:

• Enumerating lists—Traversing, displaying, or filtering the collection of lists that belong to a given SPWeb class instance
• Enumerating list contents—Examining the list items that belong to a given list
• Adding and removing lists
• Adding or removing list items

Enumerating Lists

Enumerating lists is a simple task of enumerating through any SPListCollection instance. After you have the SPList instance, it’s just a matter of wading through the many properties on the SPList class. Some of the most commonly used properties of this class are described in Table 5.1.

Table 5.1. Major SPList Properties

The following code enumerates through all of the lists contained in a sample SharePoint site, displaying a few of the properties of each list:

The preceding code displays all the lists in the site found at the URL http://win2k3r2lab/Budget Test Site. If the list is hidden, an asterisk is displayed before the list title and the item count.

Keep in mind that a lot of things that you might not expect to be lists (such as the Calendar that comes with default Team Sites) are lists. SharePoint accomplishes virtually all data storage tasks with lists, so knowing how to find and manipulate them is key to being a successful SharePoint developer.

Enumerating List Contents

Getting the items that belong to a list is as simple as accessing the list’s Items property. This is a collection of SPListItem objects. What you do with the list item after you have a reference to it is limited only by the properties and methods on the list item. Table 5.2 shows some of the common properties of the SPListItem class.

Table 5.2. Common SPListItem Properties

If you want the full and complete list of properties for the SPListItem class as well as detailed reference information on each property, consult the Windows SharePoint Services v3 Software Development Kit (SDK), which you can download from Microsoft.

The following code is modified from the preceding example to enumerate the lists on a given site and (for each list) to display the title of every list item belonging to that list:

Note that if you run this code against a top-level site collection instead of a team site, you might run into some errors. (Many internal lists on top-level site collections have list items with null titles.)

This just displays the list item’s Title property. To check the completed status of a task list item, or the value of a custom column that you created on a list, you can use the [] accessor on the list item to directly access the values associated with that item, as shown in Listing 5.1. If you are unsure of which fields belong to which list, you can always inspect the list’s Fields property.

Listing 5.1. Accessing List Item Values

Adding, Removing, and Updating Lists

The pattern for adding and removing virtually any kind of object within SharePoint is fairly consistent. To add a new instance of something to the system, you generally need to call the Add() method on the container into which you will be placing the new item. Removing objects works the same way by calling the Remove() method on the source container.

When working with lists, that source container is any instance of SPListCollection. As you have already seen, there is a property called Lists on the SPWeb class that contains a collection of lists on that SharePoint web. When you call one of the Add() overloads, you will not only add the list to the collection (and, therefore, the website), but you will also get back an instance of SPList that you can manipulate if you choose.

The code in Listing 5.2 illustrates list manipulation by creating a new list, updating a list, and deleting a list.

Listing 5.2. List Manipulation

As shown in Figure 5.1, the preceding code created a new list called “Custom Task List,” and the one that was created and subsequently deleted does not appear.

Figure 5.1. Site content after list manipulation.

Table 5.3 shows most of the commonly used methods on the SPList class that will help you write code for creating and manipulating lists.

Table 5.3. Common SPList Methods

Manipulating List Items

Manipulating list items is just as easy as manipulating lists. The item indexer property that allows you to access the various fields (columns) in the list for displaying also allows modification.

The code in Listing 5.3 shows how to create new list items, update the items, and delete existing items.

Listing 5.3. Manipulating List Items

Note that when setting the DueDate field of the list, the CreateISO8601DateTimeFromSystemDateTime method of the SPUtility class was called to convert a System.DateTime value into a string recognizable by SharePoint as a valid date/time in the correct format.

Figure 5.2 shows the contents of the list “Custom Task List” after the preceding code is executed.

Figure 5.2. List item manipulation results.

Table 5.4 shows some of the most commonly used methods on the SPListItem class that provide the developer with a wide range of functionality and flexibility.

Table 5.4. Common SPListItem Methods

Using Lookup Types in Lists

Lookup data is slightly more difficult to deal with than standard data types in SharePoint lists. When you create a lookup column, you give the user the ability to select the value from a drop-down list provided by the contents of another list. For example, you might want to add a Project column to a custom task list to allow users to associate a task with a project.

When you examine the contents of a lookup column in a list, you might see a string that looks like this:

1;#Super-Important Project

This is the standard format of a lookup column and should look familiar to anyone who has done much list-based programming with SharePoint in the past.

To set the value of a lookup column, you need only supply the ID of the list item in the remote list to which you want to associate the item. For example, if “Super-Important Project” has an internal ID of 1, you would set the project of a custom task item to “Super-Important Project” as follows:

currentItem["Project"] = "1";

When reading the contents of a lookup column, you can separate the ID from the string value simply by splitting the string on the “;” character and stripping the leading “#” from the string. In the case where multiple values are allowed, multiple occurrences of the “ID;#string” phrase will appear—also separated with the “;#” character sequence.

Summary

When writing code for SharePoint, you will almost certainly encounter situations in which you need to read from or write to lists—either standard lists or custom lists. In either case, this chapter has provided you with a basic overview of the fundamentals of list enumeration, list item enumeration, list manipulation, and list content enumeration. You should be able to use this foundation to proceed to the next two chapters, which provide specialized and advanced list management topics—“Advanced List Management” and “Handling List Events.”