Kentico CMS 7.0 Developer's Guide

Developing Data source web parts

Developing Data source web parts

Previous topic Next topic Mail us feedback on this topic!  

Developing Data source web parts

Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

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.