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.zip


Applies to:

Kentico CMS v3.x

Share this article on   LinkedIn Google+

Jaroslav Kordula

Jaroslav joined Kentico in 2006. He is a Technical Leader in a development team whose main focus is content management. This includes Documents, Custom tables, Media libraries and other related functionality.

Comments