Class diagram

Introduction

One of the more influential groups of controls included in EPiServer CMS are the Data Source controls. One of the major benefits of using these controls is that they minimize the need of codebehind for day to day operations involving reading data and populating various lists, trees etc.
The new controls supports all or a few of the select, insert, update and delete operations.

Some benefits of using the controls are:

Data Source controls in EPiServer CMS:

The marked class is the base class for all Data Source controls. Inherit from this class when designing your own Data Source controls.

The Data Source controls can be categorized as Hierarchical and Tabular or both depending on how they can deliver data. Hierarchical data source controls expose data in a hierarchical fashion (parent - child) and can be used for tree views such as the TreeView and Menu controls in ASP.NET. Most controls though, serve data in tablular fashion which can be used for listing controls such as the Repeater, DataList, GridView etc. An important differense between hierarchical and tabular data sources are that hierarchical data sources are read only whereas the tabular data sources can support inserting, updating and deleting as well. The following controls implement the IHierarchicalDataSource interface and can generate data for tree view controls or menus:

To create your own tabular Data Source controls you are advised to use the base class GenericDataSource.

How do I use an EPiServer Data Source Control?

The controls shipped with the latest EPiServer release are built and designed with ease of use in mind. There should be very little need of adding your own code behind to these classes as they are intended to be used in markup rather than coded against or inherited from.

If you do need additional functionality we recommend that you inherit from the GenericDataSource control and create your own classes that suit your needs.

The Data Source controls work as any standard control in an .aspx page. Please refer to the Public Templates package Search.aspx and EPiServer World for Data Source controls examples and information on how to implement the different controls shipped with EPiServer.

Element attribute versus query parameter

When populating a Data Source you will usually use a QueryStringParameter to read a selection of objects from the database (there is also a base class for reading objects from the ObjectStore i.e. ObjectStoreDataSource). It is possible to define a value for a member of the object both as an attribute in the asp element and as a parameter in the query string. In this case the query string definition will take precedence over the asp attribute.

Consider the following example:

Copy 
<EPiServer:CategoryDataSource 
    runat="server"   
    ID="CategoryData" 
    IncludeRootCategory="true">
    <SelectParameters>
        <asp:QueryStringParameter 
            Name="ID" 
            QueryStringField="ID" 
            Type="Int32" />
        <asp:QueryStringParameter 
            Name="IncludeRootCategory" 
            QueryStringField="IncludeRootCategory" 
            Type="Boolean" 
            DefaultValue="false" />
    </SelectParameters>
</EPiServer:CategoryDataSource>

Since IncludeRootCategory is defined twice (being set to true in the tag definition and false in the QueryStringParameter), the value set in the query string parameter will be used. If no query string parameter named "IncludeRootCategry" is specified, it's default value will be used, in this case "false".

For more information on how to use parameters with Data Source Controls, please read Microsoft's article Using Parameters with Data Source Controls.

Note:

Certain words are not recommended to use as parameter names for http requests. Consider the word "ID". If you try to use this as a parameter name for one of your http requests it will cause a conflict since the word "ID" is used to identify aspx pages in EPiServer.

A line like this:

Copy 
<asp:QueryStringParameter Name="ID" QueryStringField="ID" type="Int32" />

would conflict with the page ID. If the page for example had an ID of 200, every call to the CategoryDataSource would try to fetch categories with a parent ID of 200.

Changing the line to the following would solve this issue:

Copy 
<asp:QueryStringParameter Name="ID" QueryStringField="CategoryID" type="Int32" />

Creating your own Data Source controls

Designing your own Data Source controls is simply a matter of inheriting from the class GenericDataSource. The following lines of code show how the TabDefinitionDataSource is defined. Note that there is very little code involved to get access to the basic functionality.

CopyC#
public class TabDefinitionDataSource : 
GenericDataSource<TabDefinition, TabDefinitionCollection, int>
{
    protected override TabDefinition CreateItem(List<TabDefinition> items)
    {
        return new TabDefinition();
    }

    protected override List<TabDefinition> ListItems()
    {
        return ToList(TabDefinition.List());
    }

    protected override TabDefinition LoadItem(int key)
    {
        return TabDefinition.Load(key);
    }

    protected override void SaveItem(TabDefinition item)
    {
        item.Save();
    }

    protected override void DeleteItem(TabDefinition item)
    {
        item.Delete();
    }
}

As you can see, GenericDataSource<TObject, TCollection, TKey> is a class with three type parameters:

Name Explanation Example
TObject The business object type TabDefinition
TCollection A collection type that holds objects of type TObject TabDefinitionCollection or List<TabDefinition>
TKey The data type of the primary key int

Business Objects
Before you can create your Data Source control type, you need to have a class, your business object, that handles the data that you wish to present. In the sample above the class used for this is TabDefinition. This class is responsible for reading and saving data from the database.

If you have no need to implement any specialized behavior in your collection of business objects, you can use the generic List provided by the .NET Framework as described in the short sample below:

CopyC#
...
...
public class MyObjectDataSource : 
GenericDataSource<MyObject, List<MyObject>, int>
{

... 
...

Mapping between Control Properties and Data Source Parameters

A common way to limit a result set of a data source control is to provide it parameters in the SelectParameters collection (see Parameter). This is supported by most of the EPiServer data source controls by allowing certain control properties to be overridden by a parameter value. The properties that can be specified using Parameters for a given EPiServer data source control are listed below.

Note: that the parameter name must correspond to the property name.

Following is a list of data source controls and the corresponding properties:

See also the following Microsoft links
System.Web.UI.WebControls.Parameter
QueryStringParameter
Using Parameters with Data Source Controls