Integrating 3rd party components in Kentico CMS
Example of integrating ComponentArt menu. This article describes how to add a 3rd party menu control in Kentico CMS. In this example we will add a menu control from ComponentArt.
At first, you will need to download and install Web.UI 2008.1 for ASP.Net from http://www.componentart.com/webui/ (registration required). You can use the trial mode or you can buy the components from ComponentArt.
After the installation you can find (typically) in c:\Program Files\ComponentArt\Web.UI 2008.1 for ASP.NET 2.0\ this DLL file ComponentArt.Web.UI.dll. Please copy this file to you web project’s BIN folder. Now you are ready to develop custom menu web part (control) using the ComponentArt. Please follow these steps:
Open the web project in Visual Studio and follow this description how to create new web part - http://www.kentico.com/docs/devguide/developing_web_parts.htm (please do not forget to change the inherited class to CMSAbstractWebPart).
In the Toolbox you can find added new controls from ComponentArt. Please drag the Menu control and drop it to the ascx code of your control. Switch to the code behind.
It is recommended to create properties object, so the control will be able to handle some properties:
//MenuProperties object - ensures the data integrity and provides GroupedDataSource
CMSMenuProperties prop = new CMSMenuProperties();
Now you can add to your control some common and recommended properties like ClassNames (document types), CombineWithDefaultCulture, CultureCode, MaxRelativeLevel, OrderBy, Path, SelectOnlyPublished, SiteName and WhereCondition. For example:
///<summary>
/// Gets or sets the site name
///</summary>
public string SiteName
{
get
{
return DataHelper.GetNotEmpty(ValidationHelper.GetString(this.GetValue("SiteName"), this.prop.SiteName), this.prop.SiteName);
}
set
{
this.SetValue("SiteName", value);
this.prop.SiteName = value;
}
}
The main logic of the control is performed in SetupControl() method. If you have defined the properties, you need to initialize them in this method:
protected void SetupControl()
{
if (this.StopProcessing)
{
this.prop.StopProcessing = true;
}
else
{
// Initialize the CMSMenuProperties object
prop.ParentControl = this;
prop.Path = this.Path;
prop.WhereCondition = this.WhereCondition;
prop.SiteName = this.SiteName;
prop.SelectOnlyPublished = this.SelectOnlyPublished;
prop.OrderBy = this.OrderBy;
prop.CultureCode = this.CultureCode;
prop.CombineWithDefaultCulture = this.CombineWithDefaultCulture;
prop.ClassNames = this.ClassNames;
prop.MaxRelativeLevel = this.MaxRelativeLevel;
prop.DataSource = prop.GetDataSource();
Now, you will need to create new methods which will help with creating and populating the items. For example:
///<summary>
/// Creates new Instance of MenuItem from node DataRow
///</summary>
///<param name="dr">DataRow with node data</param>
///<returns>New instance of MenuItem</returns>
private ComponentArt.Web.UI.MenuItem CreateItem(DataRow dr)
{
ComponentArt.Web.UI.MenuItem mnuItem = new ComponentArt.Web.UI.MenuItem();
// Set menu caption
mnuItem.Text = GetMenuText(dr);
// Set URL
string url = GetURL(dr);
if (String.IsNullOrEmpty(GetURL(dr)))
{
// Disable item if there is no URL
mnuItem.Enabled = false;
}
else
{
mnuItem.NavigateUrl = url;
}
// Set images
mnuItem.Look.ImageUrl = GetImageURL(dr, "", false, false);
mnuItem.Look.LeftIconUrl = GetImageURL(dr, "left", false, false);
mnuItem.Look.RightIconUrl = GetImageURL(dr, "right", false, false);
// Set hover images
mnuItem.Look.HoverImageUrl = GetImageURL(dr, "", true, false);
mnuItem.Look.HoverLeftIconUrl = GetImageURL(dr, "left", true, false);
mnuItem.Look.HoverRightIconUrl = GetImageURL(dr, "right", true, false);
// Set highlighted images
mnuItem.Look.ActiveImageUrl = GetImageURL(dr, "", false, true);
mnuItem.Look.ActiveLeftIconUrl = GetImageURL(dr, "left", false, true);
mnuItem.Look.ActiveRightIconUrl = GetImageURL(dr, "right", false, true);
// Set CSS classes
mnuItem.Look.ActiveCssClass = GetCSSClass(dr, false, true);
mnuItem.Look.CssClass = GetCSSClass(dr, false, false);
mnuItem.Look.HoverCssClass = GetCSSClass(dr, true, false);
return mnuItem;
}
and
///<summary>
/// Populates (recursively) the specified menu item with its subitems
///</summary>
///<param name="parentNodeId">NodeID of the menu item to be populated</param>
///<param name="parent">MenuItem to be populated with subitems</param>
private void PopulateMenuItem(int parentNodeId, ComponentArt.Web.UI.MenuItem parent)
{
// Get child items from GroupedDataSource object
ArrayList items = prop.GroupedDS.GetGroup(parentNodeId);
if (items != null)
{
// Append all childs
foreach (DataRow dr in items)
{
// Get menu item nodeid (to get the child items)
int nodeId = ValidationHelper.GetInteger(dr["NodeID"], 0);
// Create menu item, add it to menu and populate it with subitems
ComponentArt.Web.UI.MenuItem child = CreateItem(dr);
PopulateMenuItem(nodeId, child);
parent.Items.Add(child);
}
}
}
As you can see, second method is recursively calling itself and also the CreateItem method. This ensures that all items are populated.
Now you need to call these two methods in the SetupControl() by adding this code behind the initialization of properties:
…
// Get top node level
int topNodeLevel = ValidationHelper.GetInteger(prop.DataSource.Tables[0].Rows[0]["NodeLevel"], 0);
// Get all the items in the top level
foreach (DataRow dr in prop.DataSource.Tables[0].Rows)
{
if (ValidationHelper.GetInteger(dr["NodeLevel"], 0) == topNodeLevel)
{
// Get menu item nodeid (to get the child items)
int nodeId = ValidationHelper.GetInteger(dr["NodeID"], 0);
// Create menu item, add it to menu and populate it with subitems
ComponentArt.Web.UI.MenuItem child = CreateItem(dr);
menuMain.Items.Add(child);
PopulateMenuItem(nodeId, child);
}
else
{
break;
}
}
You can download the complete code example from here (link is below). In the zip package are placed two other zip packages. Both of them are exported objects, so you can import it to your CMS (recommended is the 3.1 version) and then use it in your site and view the code in Visual Studio. The controls are imported to the Navigation folder under CMSWeparts.
See also: kentico.com/downloads/samples/3rdPartyMenu.zipApplies to: Kentico CMS v3.x