How to add custom drop-down button to toolbar of WebHtmlEditor

Alex Kartavov / Wednesday, August 25, 2010

In order to add another ToolbarDropDown to WebHtmlEditor, the Type="Custom" should be used. The toolbar items expose property Key and if that property is set, then action on client is defined not by Type property, but by the Key. It means that if Key is set to the "Insert", then WebHtmlEditor on client will automatically perform "insert" action for items of custom drop-down list and not extra codes is required.
Another item can be added within aspx at visual design, or it can be added on any server event. Below are examples for both cases:

aspx:

<ighedit:WebHtmlEditor ID="WebHtmlEditor1" runat="server" ...>
<Toolbar>
...
<ighedit:ToolbarDropDown runat="server" Type="Custom" Key="Insert" Title="MyInsert2">
       <Items>
         <ighedit:ToolbarDropDownItem runat="server" Value="Text to insert 2-1" Text="Item1" />
         <ighedit:ToolbarDropDownItem runat="server" Value="Text to insert 2-2" Text="Item2" />
      </Items>
    </ighedit:ToolbarDropDown>
    <ighedit:ToolbarDropDown runat="server" Type="Custom" Key="Insert" Title="MyInsert3" >
       <Items>
          <ighedit:ToolbarDropDownItem runat="server" Value="Text to insert 3-1" Text="Item1" />
          <ighedit:ToolbarDropDownItem runat="server" Value="Text to insert 3-2" Text="Item2" />
       </Items>
    </ighedit:ToolbarDropDown>
...
</Toolbar>
</ighedit:WebHtmlEditor>

aspx.cs

protected void Page_Load(object sender, System.EventArgs e)
{
if(this.IsPostBack)
return;
ToolbarDropDown dd = new ToolbarDropDown(ToolbarDropDownType.Custom);
dd.Key = "Insert";
dd.Title = "My links";
this.WebHtmlEditor1.Toolbar.Items.Add(dd);
ToolbarDropDownItem item = new ToolbarDropDownItem("Link1", "<a href='http://www.google.com'>Go google</a>");
dd.Items.Add(item);
item = new ToolbarDropDownItem("Link2", "<br/><a href='http://www.msdn.com'>MSDN</a>");
dd.Items.Add(item);
}

If application needs to find reference to custom item on server (in order to remove or modify it), then it has several options. The most straight forward, is to search all items within Toolbar.Items property until a match for a property is found. For example, if(item.Title=="MyInsert2"). Below is example for that:

ToolbarDropDown myInsert2 = null;
foreach(object item in this.WebHtmlEditor1.Toolbar.Items)
{
if(item is ToolbarDropDown && ((ToolbarDropDown)item).Title.Equals("MyInsert2"))
{
myInsert3 = (ToolbarDropDown)item;
break;
}
}

On another hand the WebHtmlEditor and WebHtmlEditor.Toolbar also have search method FindByKeyOrAction. Using that method will make codes much cleaner. However, in situation when Type is Custom and Key is Insert all 3 insert buttons (aspx example) will get match and the first found item will be returned. To get around that situation, an application may set the Key property for any ToolbarDropDownItem used in custom drop-down and pass that value into FindByKeyOrAction method. In this case the reference to the parent ToolbarDropDown will be returned, but not to ToolbarDropDownItem.
Note: the Key of ToobarDropDownItem is not used for any purpose not on server not on client.
Below is example:

aspx:

    ...
    <ighedit:ToolbarDropDown runat="server" Type="Custom" Key="Insert" Title="MyInsert3" >
       <Items>
          <ighedit:ToolbarDropDownItem runat="server" Key="MyKeyItem" Value="Text to insert 3-1" Text="Item1" />
          <ighedit:ToolbarDropDownItem runat="server" Value="Text to insert 3-2" Text="Item2" />
       </Items>
    </ighedit:ToolbarDropDown>
    ...

aspx.cs:

ToolbarDropDown myInsert3 = this.WebHtmlEditor1.FindByKeyOrAction("MyKeyItem") as ToolbarDropDown;

Advanced configuration:
If application needs a specific/strict/custom identifier for a button on server, then it may set the Key property to any value. That Key will identify a custom button and not need in explicit search or usage of Key for a subitem.
However, in this case in order to perform desired built-in "insert" action on client, application should process ClientSideEvents.BeforeAction. It can check for action (actID and/or act params) coming from toolbar button and implement it.
If application wants to perform a built-in action like "insert", then it may use the "oEvent.act" member. If that member is set, then that has priority over Type and Key actions. Below is example:

aspx:

<ighedit:WebHtmlEditor ID="WebHtmlEditor1" runat="server" ...>
<Toolbar>
...
<ighedit:ToolbarDropDown runat="server" Type="Custom" Key="MyInsertKey" Title="MyInsert4">
       <Items>
         <ighedit:ToolbarDropDownItem runat="server" Value="Text to insert 4-1" Text="Item1" />
         <ighedit:ToolbarDropDownItem runat="server" Value="Text to insert 4-2" Text="Item2" />
      </Items>
    </ighedit:ToolbarDropDown>
...
</Toolbar>
</ighedit:WebHtmlEditor>

ASP.NET Team