Kentico CMS 6.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!  

The code example below shows the creation of a sample custom DataSource web part for providing data from the CMS. The web part consists of two controls, so you need to take the following two steps when developing your custom DataSource web part:

 

1. Create a user control that inherits from CMSBaseDataSource. This will be the control that gets the data.

 

The OnInit and DataFilter_OnFilterChanged methods are necessary for handling a connected filter. If you are not planning to use a filter with the data source web part, you do not need to implement these methods.

The GetDataSourceFromDB method ensures the loading of the actual data.

 

DataSourceControl.ascx

 

Please keep in mind that the following code is only an example, the actual values of the CodeFile and Inherits attributes will be different according to the name and location of the user control.

 

Please note: If you installed the Kentico CMS project as a web application, you need to rename the CodeFile property on the first line to Codebehind for the code example to be functional.

 

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

 

DataSourceControl.ascx.cs

 

Please be aware that the name of the class will be different according to the name and location of the newly created user control.

 
[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 CMSTestingSite_APIExamples_Controls_DataSource : 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 filter change 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>

  /// Gets the datasource data.

  /// </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
}

 

2. Create another user control and insert the first control into it. This control will become the actual web part.

 

The control must inherit from CMSAbstractWebPart.

The line of the SetupControl method beginning with this.srcUsers.FilterName ensures that the inner datasource's name is set the same as the Web part control ID property of this web part. Don't get perplexed by the property being called FilterName. This is by design, because datasources use the same objects as filters.

 

DataSourceWebPart.ascx

 

Please note: If you installed the Kentico CMS project as a web application, you need to rename the CodeFile property on the first line to Codebehind for the code example to be functional.

 

<%@ 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 CMSTestingSite_APIExamples_Controls_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)

       {

          // Do nothing.

       }

      else

       {

          this.srcUsers.WhereCondition = this.WhereCondition;

          this.srcUsers.OrderBy = this.OrderBy;

         

          // Sets the current web part name as the datasource name.

          this.srcUsers.FilterName = ValidationHelper.GetString(this.GetValue("WebPartControlID"), this.ClientID);

          // Sets the name of 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.

 

You can now register this control as a web part in Kentico CMS via the Site Manager -> Development -> Web parts interface (as described in the Developing web parts topic). Remember to set the Type of the web part to Data source on the General tab.