SPDataSource.SelectParameters property
Gets the parameters collection that contains parameters for selecting data.
Namespace: Microsoft.SharePoint.WebControls
Assembly: Microsoft.SharePoint (in Microsoft.SharePoint.dll)
Syntax
'Declaration
<PersistenceModeAttribute(PersistenceMode.InnerProperty)> _
Public ReadOnly Property SelectParameters As ParameterCollection
Get
'Usage
Dim instance As SPDataSource
Dim value As ParameterCollection
value = instance.SelectParameters
[PersistenceModeAttribute(PersistenceMode.InnerProperty)]
public ParameterCollection SelectParameters { get; }
Property value
Type: System.Web.UI.WebControls.ParameterCollection
A System.Web.UI.WebControls.ParameterCollection object that contains any parameters that will be used to select data.
Remarks
The parameters in the SelectParameters collection depend on the data in the data-bound control, the parameters that are specified declaratively, and the parameters that are added programmatically. The entire collection is used by the associated SPDataSourceView object to select data.
Note
The SelectParameters property is read-only. However, this does not mean that you cannot add or remove parameters from the ParameterCollection object that is returned by the property. To add a parameter to the colllection, call the Add method. To remove a parameter, call the Remove method.
Among other uses, select parameters can help the control identify and locate the data source that it will query. In general, the control understands certain well-known parameter names and values as data context identifiers. The following table lists the names of these parameters and describes what you can assign as default values. The parameter names are not case-sensitive.
Name |
Description |
|---|---|
WebID |
”RootWeb” for the root Web site or “SubWeb” for the child Web site in which the page resides. (The attribute is case insensitive, so “rootweb” and “subweb” also work.) Otherwise, a string representation of a GUID such as the value of the SPWeb.ID property. |
WebURL |
An empty string for the root Web site. Otherwise, a string containing a server-relative URL. |
ListID |
A string representation of a GUID such as the value of the SPList.ID property. You can also specify the list by setting the List property. |
ListName |
The value of the SPList.Title property. You can also specify the list by setting the List property |
ListItemGUID |
A string representation of a GUID such as the value of the SPListItem.UniqueId property. |
ListItemID |
A string representation of an integer such as the value of the SPListItem.ID property. |
RootFolder |
The value of the SPFolder.Name property. |
FolderID |
A string representation of a GUID such as the value of the SPFolder.UniqueId property. |
The type of data that the control will query determines which of these select parameters are required. For example, if you want the SPDataSource control to retrieve data from the Tasks list in the root Web site of a site collection, you must first set the DataSourceMode property to specify List mode, and then you must set parameters that identify the list and the Web site where it can be found. All of this work can be accomplished declaratively in page markup, as illustrated by following example.
<SharePoint:SPDataSource
ID="SPDataSource1"
runat="server"
DataSourceMode="List"
UseInternalName="true"
SelectCommand="<View></View>">
<SelectParameters>
<asp:Parameter Name="ListName" DefaultValue="Tasks" />
<asp:Parameter Name="WebID" DefaultValue="RootWeb" />
</SelectParameters>
</SharePoint:SPDataSource>
Examples
The following example shows page markup that links a data-bound grid control to an SPDataSource control that is configured to query the Contacts list in the root Web site of a site collection.
Notice that the SelectCommand has a Where clause that defines a filter based on the value of the Company field, and the value is specified by a substitution parameter. The SPDataSource control uses curly braces around substitution parameter names: {parametername}. In this case, the substitution parameter {CompanyName} corresponds to a QueryStringParameter that is named "CompanyName." When the page is rendered, the value of the CompanyName parameter is taken from a QueryString field on the URL and then passed to the substitution parameter in the Where clause.
<SharePoint:SPDataSource ID="SPDataSource1" runat="server"
DataSourceMode="List" UseInternalName="true"
SelectCommand="<View><Query><Where><Eq><FieldRef Name='Company'/><Value Type='Text'>{CompanyName} </Value></Eq></Where></Query></View>" >
<SelectParameters>
<asp:Parameter Name="WebID" DefaultValue="RootWeb" />
<asp:Parameter Name="ListName" DefaultValue="Contacts" />
<asp:QueryStringParameter Name="CompanyName" QueryStringField="Company" DefaultValue="Contoso" />
</SelectParameters>
</SharePoint:SPDataSource>
<asp:GridView ID="GridView1" runat="server"
DataSourceID="SPDataSource1"
AutoGenerateColumns="false">
<Columns>
<asp:BoundField HeaderText="First Name" DataField="FirstName" />
<asp:BoundField HeaderText="Last Name" DataField="Title" />
<asp:BoundField HeaderText="Job Title" DataField="JobTitle" />
</Columns>
</asp:GridView>
The next example is almost identical, except that rather than using a QueryStringParameter, it uses an instance of the ControlParameter class. As in the previous example, the query string contains a Where clause with a substitution parameter, {CompanyName}. The difference here is that the value for substitution is provided by a DropDownList control. Notice that the AutoPostBack property of the drop-down list control is set to true so that postback to the server occurs whenever the user changes the list selection. Similarly, the EnableViewState property of the GridView control is set to false so that the control is forced to get fresh data from the SPDataSource control when the page is rendered on postback.
<SharePoint:SPDataSource ID="SPDataSource1" runat="server"
DataSourceMode="List"
UseInternalName="true"
SelectCommand="<View><Query><Where><Eq><FieldRef Name='Company'/><Value Type='Text'>{CompanyName} </Value></Eq></Where></Query></View>">
<SelectParameters>
<asp:Parameter Name="WebID" DefaultValue="RootWeb" />
<asp:Parameter Name="ListName" DefaultValue="Contacts" />
<asp:ControlParameter Name="CompanyName" ControlID="DropDownList1" PropertyName="SelectedValue" />
</SelectParameters>
</SharePoint:SPDataSource>
<asp:DropDownList ID="DropDownList1" runat="server" AutoPostBack="true">
<asp:ListItem Selected="True">Adventure Works</asp:ListItem>
<asp:ListItem>Contoso</asp:ListItem>
</asp:DropDownList>
<br />
<br />
<asp:GridView ID="GridView1" runat="server" EnableViewState="false"
DataSourceID="SPDataSource1"
AutoGenerateColumns="false">
<Columns>
<asp:BoundField HeaderText="First Name" DataField="FirstName" />
<asp:BoundField HeaderText="Last Name" DataField="Title" />
<asp:BoundField HeaderText="Job Title" DataField="JobTitle" />
</Columns>
</asp:GridView>