Developing Data source web parts

When developing custom data source web parts, you need to create two separate user controls:

1.The first control ensures the loading of the data that will be provided by the data source. This control must inherit from CMSBaseDataSource (found in the CMS.Controls namespace).

2.The second user control contains the first control in its markup and serves as the source file for the actual web part. Must inherit from CMSAbstractWebPart.

Example

This example shows how to create a custom data source web part that provides user data from the CMS.

Open your web project in Visual Studio and create two user controls according to the sections below.

InfoBox_Exclamation

Warning

The code is only for demonstrational purposes. Set the values of the Inherits attribute in the user control declarations and the class names according to the name and location of your controls.

DataSourceControl.ascx

Leave the ASCX markup of the first user control empty.

DataSourceControl.ascx.cs

The OnInit override and DataFilter_OnFilterChanged handler method are needed to manage connected filters. If you are not planning to use filters with the data source web part, you do not need to implement these methods.

[C#]

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Data;

using CMS.Controls;
using CMS.SiteProvider;

/// <summary>
/// User data source. Loads all users according to a specified where condition.
/// </summary>
public partial class CMSGlobalFiles_DataSourceControl : CMSBaseDataSource
{
#region "Properties"

/// <summary>
/// Gets or sets the data source.
/// </summary>
public override object DataSource
{
get
{
return mDataSource ?? (mDataSource = base.GetDataSource());
}
set
{
mDataSource = (DataSet)value;
}
}

#endregion

#region "Methods"

/// <summary>
/// Assigns a handler for the 'OnFilterChanged' event if there is a filter attached to the data source.
/// </summary>
protected override void OnInit(EventArgs e)
{
if (SourceFilterControl != null)
{
SourceFilterControl.OnFilterChanged += new ActionEventHandler(DataFilter_OnFilterChanged);
}

base.OnInit(e);
}

/// <summary>
/// Handles the OnFilterChanged event.
/// </summary>
void DataFilter_OnFilterChanged()
{
// Clears the old data
InvalidateLoadedData();

// Raises the change event.
this.RaiseOnFilterChanged();
}

/// <summary>
/// Loads the data provided by the datasource.
/// </summary>
protected override object GetDataSourceFromDB()
{
// Initializes the data properties according to the filter settings.
if (SourceFilterControl != null)
{
SourceFilterControl.InitDataProperties(this);
}

// Loads the data. The WhereCondition and OrderBy properties are inherited from the parent class.
DataSource = UserInfoProvider.GetFullUsers(WhereCondition, OrderBy);
return DataSource;
}

#endregion
}

DataSourceWebPart.ascx

Warning: If your Kentico CMS project was installed as a web application, you need to rename the CodeFile property on the first line to Codebehind.

<%@ Control Language="C#" AutoEventWireup="true" CodeFile="DataSourceWebPart.ascx.cs" Inherits="CMSTestingSite_APIExamples_Controls_DataSourceWebPart" %>

<%@ Register src="DataSourceControl.ascx" tagname="DataSourceControl" tagprefix="cms" %>

<cms:DataSourceControl ID="srcUsers" runat="server" />

DataSourceWebPart.ascx.cs

[C#]

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

using CMS.PortalControls;
using CMS.GlobalHelper;

public partial class CMSGlobalFiles_DataSourceWebPart : CMSAbstractWebPart
{
/// <summary>
/// Gets or sets the value of the WhereCondition web part property.
/// </summary>
public string WhereCondition
{
get
{
return ValidationHelper.GetString(this.GetValue("WhereCondition"), "");
}
set
{
this.SetValue("WhereCondition", value);
srcUsers.WhereCondition = value;
}
}

/// <summary>
/// Gets or sets the value of the OrderBy web part property.
/// </summary>
public string OrderBy
{
get
{
return ValidationHelper.GetString(this.GetValue("OrderBy"), "");
}
set
{
this.SetValue("OrderBy", value);
srcUsers.OrderBy = value;
}
}

/// <summary>
/// Gets or sets the value of the FilterName web part property.
/// </summary>
public string FilterName
{
get
{
return ValidationHelper.GetString(this.GetValue("FilterName"), "");
}
set
{
this.SetValue("FilterName", value);
srcUsers.SourceFilterName = value;
}
}

/// <summary>
/// Content loaded event handler.
/// </summary>
public override void OnContentLoaded()
{
base.OnContentLoaded();
SetupControl();
}

/// <summary>
/// Initializes the properties of the internal data source control.
/// </summary>
protected void SetupControl()
{
if (this.StopProcessing)
{
// Does nothing if the web part is disabled
}
else
{
this.srcUsers.WhereCondition = this.WhereCondition;
this.srcUsers.OrderBy = this.OrderBy;

// Sets the inner data source's name according to the web part's 'Web part control ID' property.
// This allows listing web parts to connect to the inner control.
// The identifier property is named 'FilterName' because data sources inherit the property from
// a base class shared with filter objects.
this.srcUsers.FilterName = (string)this.GetValue("WebPartControlID");

// Connects the attached filter, as specified by the 'Filter name' property of the web part
this.srcUsers.SourceFilterName = this.FilterName;
}
}
}

If your Kentico CMS project was installed as a web application, you must Build the project.

Registering the web part

Register the DataSourceWebPart.ascx control as a new web part in Kentico CMS via the Site Manager -> Development -> Web parts interface. For details about this process, see the Developing web parts topic.

1. Type Custom user data source as the web part's Display name.

2. Set the Type of the web part to Data source on the General tab.

3. On the Properties tab, define the following properties for the web part:

•Column name: OrderBy

•Attribute type: Text

•Attribute size: 500

•Allow empty value: yes (checked)

•Field caption: SQL Order by clause

•Form control: Order by

•Column name: WhereCondition

•Attribute type: Text

•Attribute size: 500

•Allow empty value: yes (checked)

•Field caption: SQL Where condition

•Form control: Where condition

•Column name: FilterName

•Attribute type: Text

•Attribute size: 200

•Allow empty value: yes (checked)

•Field caption: Filter name

•Form control: Text box

Result

The custom data source web part is now ready and you can try out its functionality.

Go to CMS Desk, create a new page and place the following web parts into its design:

Web part	Instructions
Custom user data source	Type UsersFilter into the Filter name property.
Users filter	Leave the default property values. The Web part control ID is set to UsersFilter by default, which connects the filter to the custom data source.
Basic repeater	1.Enter the ID of the Custom user data source web part into the Data source name property: CustomUserDataSource 2.Set an appropriate Transformation name for displaying users, for example: Community.Transformations.MembersList

The page display a list of all users in the system. You can modify the list by configuring the SQL Where condition and SQL Order by clause properties of the data source. Visitors can dynamically narrow down the list directly on the page using the connected filter.

Help URL: http://devnet.kentico.com/docs/7_0/devguide/index.html?developing_datasource_web_parts.htm