Share via


SPDataSource.DataSourceMode Property

Gets or sets a value that specifies the type of data to query.

Namespace:  Microsoft.SharePoint.WebControls
Assembly:  Microsoft.SharePoint (in Microsoft.SharePoint.dll)
Available in Sandboxed Solutions: No

Syntax

'Declaration
Public Property DataSourceMode As SPDataSourceMode
    Get
    Set
'Usage
Dim instance As SPDataSource
Dim value As SPDataSourceMode

value = instance.DataSourceMode

instance.DataSourceMode = value
public SPDataSourceMode DataSourceMode { get; set; }

Property Value

Type: Microsoft.SharePoint.WebControls.SPDataSourceMode
An SPDataSourceMode value. The default value is SPDataSourceMode.List.

Remarks

The value of the DataSourceMode property specifies the type of data to query. Possible values are defined in the SPDataSourceMode enumeration and include List, ListItem, CrossList, ListOfLists, and Webs.

Examples

DataSourceMode.List

In List mode, the underlying data source is a SharePoint Foundation list. In the following example, the SPDataSource control is used to retrieve data from the Tasks list in the root Web site. Notice that the list and the Web site are identified by ListName and WebID parameters. The control also recognizes the parameter names ListID and WebURL. For more information, see the SelectParameters property.

In the example, the data source control is linked to a data-bound GridView control by assigning the value of the SPDataSource control's ID property to the bound control's DataSourceID property.

<SharePoint:SPDataSource
    ID="SPDataSource1" 
    runat="server" 
    DataSourceMode="List"
    UseInternalName="true" 
    SelectCommand="<Query><OrderBy><FieldRef Name='DueDate' Ascending='true' /></OrderBy></Query>"> 
    <SelectParameters>
        <asp:Parameter Name="ListName" DefaultValue="Tasks" />
        <asp:Parameter Name="WebID" DefaultValue="RootWeb" />
    </SelectParameters>
</SharePoint:SPDataSource>

<asp:GridView 
    ID="GridView1" 
    runat="server" 
    DataSourceID="SPDataSource1" 
    AutoGenerateColumns="false">
    <Columns>
        <asp:BoundField HeaderText="Due Date" DataField="DueDate" />
        <asp:BoundField HeaderText="Priority" DataField="Priority" />
        <asp:BoundField HeaderText="Title" DataField="Title" />
        <asp:BoundField HeaderText="Status" DataField="Status" />
   </Columns>
</asp:GridView>

When the page that contains this markup is rendered, the SPDataSource control automatically populates the grid with the requested list data. The control returns one row of data for each list item.

DataSourceMode.ListItem

In ListItem mode, the control retrieves data from a single list item. The target item must be identified in SelectParameters with a parameter that identifies the Web site, a parameter that identifies the list, and a parameter that identifies the list item. In the following example, the ListItemID parameter specifies the first item in the Announcements list.

<SharePoint:SPDataSource  
    ID="SPDataSource1" 
    runat="server" 
    DataSourceMode="ListItem"
    UseInternalName="true" >
    <SelectParameters>
        <asp:Parameter Name="WebID" DefaultValue="RootWeb" />
        <asp:Parameter Name="ListName" DefaultValue="Announcements" />
        <asp:Parameter Name="ListItemID" DefaultValue="1" />
    </SelectParameters>
</SharePoint:SPDataSource>

<asp:GridView 
    ID="GridView1" 
    runat="server" 
    DataSourceID="SPDataSource1" 
    AutoGenerateColumns="false">
    <Columns>
        <asp:BoundField HeaderText="Title" DataField="Title" />
        <asp:BoundField HeaderText="Expires" DataField="Expires" />
   </Columns>
</asp:GridView>

When the page that contains this markup is rendered, the GridView control is automatically populated with one row of data that contains the requested field values.

DataSourceMode.CrossList

In CrossList mode, you can query items in multiple lists in multiple Web sites in the same site collection. The effect is similar to using an instance of the SPSiteDataQuery class against lists in a site collection.

The following example queries Calendar lists (list type 106), asking for appointments where the location is “Your office” and the date is today. The result of the query automatically populates the data-bound GridView control, which displays the data.

Note

The SelectCommand string in the example has been modified to make it easier to read. On an actual ASP.NET page the string should be on a single line.

<SharePoint:SPDataSource ID="SPDataSource1" runat="server"
    DataSourceMode="CrossList"
    UseInternalName="true" 
    SelectCommand="<Webs Scope='Recursive'></Webs>
                   <Lists ServerTemplate='106'></Lists>
                   <View>
                      <ViewFields>
                         <FieldRef Name='EventDate'/>
                         <FieldRef Name='Title'/>
                         <FieldRef Name='Location'/
                      </ViewFields>
                      <Query>
                         <Where>
                            <And>
                               <Eq>
                                 <FieldRef Name='Location'/>
                                 <Value Type='Text'>Your office</Value>
                               </Eq>
                               <Eq>
                                 <FieldRef Name='EventDate'/>
                                 <Value Type='DateTime'><Today/></Value>
                               </Eq>
                            </And>
                         </Where>
                      </Query>
                   </View>" >
</SharePoint:SPDataSource>
      
<asp:GridView ID="GridView1" runat="server" 
    DataSourceID="SPDataSource1" 
    AutoGenerateColumns="false" Width="75%" HeaderStyle-HorizontalAlign="Left" >
    <Columns>
        <asp:BoundField HeaderText="Date" DataField="EventDate" />
        <asp:BoundField HeaderText="Title" DataField="Title" />
        <asp:BoundField HeaderText="Location" DataField="Location" />
    </Columns>
</asp:GridView>

Notice that the markup for the SPDataSource control has no SelectParameters component. All of the work is done by the Collaborative Application Markup Language (CAML) fragment assigned to the SelectCommand property. This fragment contains two somewhat unusual elements: Webs and Lists.

  • Webs element

    This element specifies the scope of the query. “Recursive” scope covers all subsites of the current Web site. “SiteCollection” scope covers all Web sites in the site collection. For more information, see the Webs property.

    When you use the Webs element with the SPDataSource control, the tag cannot be self-closing, as in <Webs />. You must use separate opening and closing tags, <Webs></Webs>.

  • Lists element

    This element limits the query to particular lists or to a particular type of list. Attributes on the Lists element can specify a ServerTemplate or BaseType. In the example, the Lists element limits the query to Calendar lists by setting the value of the ServerTemplate attribute to 106. In addition, one or more List subelements can limit the query to lists identified by ID or to lists that have a specified indexed field. For more information, see the Lists property.

DataSourceMode.ListOfLists

In ListOfLists mode, the control retrieves properties of lists in a specified Web site. If no Web site is specified, the Web site in the current context is used. The data source control returns one row of data for each list. Fields in each row correspond to properties of an SPList object.

In the following example, the markup for the GridView control binds selected data fields to columns of the grid. Note that the markup references a data field by using an SPList object property name prefixed with the value of the SystemPropertyPrefix field, "__sp". For example, the markup uses the name "__spTitle" to refer to the Title property.

<SharePoint:SPDataSource 
    ID="SPDataSource1" 
    runat="server"
    DataSourceMode="ListOfLists" >
    <SelectParameters>
        <asp:Parameter Name="WebUrl" DefaultValue="/" />
    </SelectParameters>
</SharePoint:SPDataSource>

<asp:GridView 
    ID="GridView1" 
    runat="server" 
    DataSourceID="SPDataSource1" 
    AutoGenerateColumns="false" >
    <Columns>
        <asp:BoundField HeaderText="List Title" DataField="__spTitle" />
        <asp:BoundField HeaderText="Description" DataField="__spDescription" />
        <asp:BoundField HeaderText="URL" DataField="__spDefaultViewUrl" />
    </Columns>
</asp:GridView>

DataSourceMode.Webs

In Webs mode, the control retrieves properties of subsites of the current Web site. The data source control returns one row of data for each subsite. Fields in each row of data correspond to properties of an SPWeb object.

In the following example, the markup for the GridView control binds selected data fields to columns of the grid. Note that the markup references a data field by using an SPWeb object property name prefixed with "__sp". For example, the markup uses the name "__spUrl" to refer to the Url property.

<SharePoint:SPDataSource 
    ID="SPDataSource1" 
    runat="server" 
    DataSourceMode="Webs" 
    IncludeHidden="true"> 
    <SelectParameters>
        <asp:Parameter Name="WebId" DefaultValue="RootWeb" />
    </SelectParameters>
</SharePoint:SPDataSource>

<asp:GridView 
    ID="GridView1" 
    runat="server" 
    DataSourceID="SPDataSource1" 
    AutoGenerateColumns="false">
    <Columns>
        <asp:BoundField HeaderText="Site Title" DataField="__spTitle" />
        <asp:BoundField HeaderText="URL" DataField="__spUrl" />
        <asp:BoundField HeaderText="ID" DataField="__spID" />
        <asp:BoundField HeaderText="Web Template" DataField="__spWebTemplate" />
        <asp:BoundField HeaderText="Web Template Id" DataField="__spWebTemplateId" />
    </Columns>
</asp:GridView>

The SPDataSource control automatically populates the grid with data. You could achieve a similar result by calling the GetSubwebsForCurrentUser() method and then enumerating the collection of SPWeb objects that the method returns, capturing property values for each object.

See Also

Reference

SPDataSource Class

SPDataSource Members

Microsoft.SharePoint.WebControls Namespace

DataFormParameter