Hide menu Last updated: Sep 21 2015

Note: This topic is applicable for sites using Web Forms.

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 code-behind for day-to-day operations involving reading data and populating various lists, trees, and so on. The new controls supports all or a few of the select, insert, update and delete operations.

Some benefits of using the controls are:

  • Minimized need of plumbing code in code-behind.
  • Built-in support for select, insert, update and delete.
  • A contract that fits many of the built-in .NET controls and third-party controls.

You can categorize the data source controls as Hierarchical, Tabular, or both depending on how they can deliver data.

  • Hierarchical data source controls expose data in a hierarchical fashion (parent – child), which you can use for tree views such as the TreeView and Menu controls in ASP.NET.
  • Most controls serve data in tabular fashion, which you can use to list controls such as the Repeater, DataList, GridView, and so on.

Note: An important difference 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.

The following controls implement the IHierarchicalDataSource interface and can generate data for tree view controls or menus:

  • PageDataSource
  • CategoryDataSource
  • FileSystemDataSource

To create your own tabular data source controls, use the base class GenericDataSource.

Using an Episerver data source control

The data source classes are intended to be used in markup rather than coded against or inherited from, so you should have little need to add your own code-behind. If you do need additional functionality, you should inherit from the GenericDataSource control and create classes that suit your needs.

The data source controls work as any standard control in an .aspx page. See the templates and demo site packages available from EPiServer World for examples and information about implementing the controls shipped with Episerver CMS.

Element attribute versus query parameter

When you populate a data source you usually use a QueryStringParameter to read a selection of objects from the database.  You can define a value for a member of the object as an attribute in the asp element and as a parameter in the query string. In this case, the query string definition takes precedence over the asp attribute. Consider the following example:

XML
<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>

Because 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 IncludeRootCategory is specified, it is default value will be used, in this case false. For information about using parameters with Data Source Controls, see Microsoft’s article Using Parameters with Data Source Controls.

Note: You should not use certain words to use as parameter names for http requests. For example, ID causes a conflict if you try to use it as a parameter name for one of your http requests, because ID is used to identify aspx pages in Episerver. If the page had an ID of 200, every call to the CategoryDataSource would try to fetch categories with a parent ID of 200. You can solve the issue by adding text to certain words, such as changing ID to CategoryID.

Creating your own data source controls

Designing your own data source controls is a matter of inheriting from the GenericDataSource class. The following lines of code show how the TabDefinitionDataSource is defined. There is very little code involved to get access to the basic functionality.

C#
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();
    }
}

GenericDataSource<TObject, TCollection, TKey> has the following type parameters:

NameExplanationExample
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 want 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 do not need to implement a specialized behavior in your collection of business objects, you can use the generic List provided by the .NET Framework as described in the following short sample:

C#
...
...
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. You can specify the following properties using Parameters for a given Episerver data source control. The parameter name must correspond to the property name.

  • PageDataSource
    PropertyType
    AccessLevel EPiServer.Security.AccessLevel
    PageLink EPiServer.Core.PageReference
    PageLinkProperty String
    IncludeRootPage Bool
  • SearchDataSource
    PropertyType
    AccessLevel EPiServer.Security.AccessLevel
    PageLink EPiServer.Core.PageReference
    PageLinkProperty String
    IncludeRootPage Bool
    OnlyWholeWords Bool
    SearchQuery String
    SearchFiles Bool
    SearchLocations String
    MainCatalog String
    MainScope String
    MaxAllowHits Integer
  • CategoryDataSource
    PropertyType
    IncludeRootCategory Bool
  • FileSystemDataSource
    PropertyType
  • LanguageDataSource
    PropertyType
  • PageDefinitionDataSource
    PropertyType
    Dynamic Bool
    PageTypeID Integer
  • PageDefinitionTypeDataSource
    PropertyType
    ID Integer
  • PageVersionDataSource
    PropertyType
    PageLink EPiServer.Core.PageReference
    LanguageBranch String
  • TabDefinitionDataSource
    PropertyType
    ID Integer
  • MembershipUserDataSource
    PropertyType
    UserName string
  • SoftLinkDataSource
    PropertyType
    PageLink EPiServer.Core.PageReference
    ListReferencing Bool

Related topics

Comments