ASP.NET Cross-Browser Toolbar

• Download source and demo project - 100 Kb

Horizontal Toolbar in Mozilla. The selected item displays a rollover image.

Contents

• Introduction
• Building Toolbars in the designer
• Toolbar Items
• Using the code
• Troubleshooting
• Newsletter, Acknowledgements, History

Introduction

A working online demo of the component is available here.

Building Toolbars in the designer

To create a Toolbar, no coding is required. If you have added the control to your IDE's toolbox, just drag it on your webform. As there is nothing to preview yet, it will display a grey rectangle:

All the control's properties are accessible via the Toolbar section of the property grid. They are pretty self-explanatory:

To add items to the toolbar, simply click on the button of the Items property (see above) which opens a new designer window. Below is a screenshot of the toolbar settings I used for the project sample. As you can see, the Toolbar contains six different items. New items can easily be added through the dropdown list in the bottom left corner:

Setting up Toolbar and Toolbar items is pretty straightforward as you get a proper preview of the Toolbar at design time. So the best way to get to know the component is to play around with the different settings, in your IDE...

Toolbar Items

The Toolbar comes with built-in support for various item types. Furthermore, arbitrary controls can be plugged into the Toolbar by using an empty container item. (BTW - you can also use the items without a Toolbar. If you just need a single image button with rollovers on your page - just drag the control directly on your web form and you're done.)

ToolbarImage

This item renders a simple image with optional rollovers. An additional DisabledImageUrl can be specified which is rendered if the item's RenderDisabled property is true. An additional label (LabelText property) can be specified which is rendered next to the image.

ToolbarButton

This item renders an image button which posts back to the server and raises an ItemSubmitted event on the toolbar. Like the ToolbarImage control, this item supports rollover and disabled images. If the item's RenderDisabled property is set to true, a normal image is rendered rather than an image button.

An additional label (LabelText property) can be specified which is rendered next to the image button. In a future release, I will replace this label through a LinkButton that also posts back to the server.

ToolbarLink

This item renders a hyperlinked image. Like the ToolbarImage control, this item supports rollover and disabled images. If the item's RenderDisabled property is set to true, a normal image is rendered rather than a link. An additional label (LabelText property) can be specified which is rendered as part of the hyperlink (see vertical Toolbar sample image above).

ToolbarTextBox

This item renders an ASP.NET TextBox. You can get/set the text of the item through the Text property of the item. To format the textbox, use the properties of the item itself (CssClass, Width, Height etc.). If text was changed, this item raises an ItemSubmitted event on the toolbar. Like the standard ASP.NET TextBox, it provides an AutoPostBack property which causes an automatic postback to the server if text was changed.

ToolbarLabel

Renders a simple text, enclosed in HTML span tags. Can be used to render text in its own item cell. This is a safe way to assign text to the toolbar without getting formatting issues (see Troubleshooting for more info).

ToolbarSeparator

Renders a separator item. Separators are very simple controls which are configured via the Toolbar's properties. This enables you to conveniently configure all your Toolbar's separators at once. If you want to separate your items with more flexibility, just use ToolbarImage items instead.

ControlContainerItem

This class is an empty container for arbitrary controls. This enables you to plug arbitrary controls into the toolbar at runtime.

Say you want to add an ASP.NET DropDown control to the Toolbar:

• Add a ControlContainerItem to your Toolbar using the designer (don't forget the ItemId - you need it to reference the item at runtime!).
• At runtime, you can assign the DropDown control with only two lines of code:

private void Page_Load(object sender, System.EventArgs e)
{  
  //get the container item
  ToolbarItem item = this.Toolbar1.Items["DropdownItem"];
  //add the dropdown to the container's Controls collection
  item.Controls.Add(this.MyDropDownList);
}

The sample project contains a web form (containeritem.aspx) which adds a CheckBox control at runtime.

Using the code

PostBack event handling

You can register event handlers for toolbar items that post back through the Toolbar's ItemPostBack event. If an event occurs, the Toolbar submits the item that caused the postback to the event handler. If there are several items that post back to the server, you will probably use the ItemId property to determine how to respond to the event.

A typical event handler looks like this:

/// <summary>
/// Handles the toolbar's button events.
/// </summary>
/// <param name="item">Clicked toolbar button.</param>
private void Toolbar1_ItemPostBack(ToolbarItem item)
{
  if (item.ItemId == "SAVE")
  {
      //save something
  }
  else if (item.ItemId == "DELETE")
  {
      //delete something
  }
}

Processing Toolbar items at runtime

You can easily customize your Toolbar at runtime. The Toolbar's Items collection provides everything you need to find, add or remove items:

As an example: the Edit button of the sample project is being created at runtime. In the code below, a new ToolbarButton object is being created. Afterwards, the index of the Save button is being determined and used to add the new Edit button right after the Save button.

/// <summary>
/// Creates an additional toolbar button and adds it to
/// the toolbar's <c>Items</c> collection.
/// </summary>
private void CreateEditButton()
{
  //create an "edit" button
  ToolbarButton editItem = new ToolbarButton();
  editItem.ID = "EditItem";
  editItem.ImageUrl = "images/edit.gif";
  editItem.RollOverImageUrl = "images/edit_ro.gif";
  editItem.ItemId = "Edit";
  editItem.ToolTip = "Click to enable save button";
  editItem.ItemCellWidth = Unit.Pixel(100);
  //get the index of the save button and insert the
  //edit button right after this one
  int index = this.Toolbar1.Items.IndexOf("Save");
  this.Toolbar1.Items.Insert(index + 1, editItem);
}

Note that dynamically created toolbar item controls are not being stored in ViewState, so you will have to recreate them on postback!

Troubleshooting

Rollovers don't work

The rollover JavaScript uses the id attribute of the HTML element that contains the image (an HTML image or an image button) to exchange rollover images.

<img src="save.gif" id="saveitem" /> 

However, this attribute is only available if the ID (not ItemId!) property of the ASP.NET ToolbarItem object was set properly. So if rollovers don't work, check the IDs of your controls (right after having checked your image URLs, of course ;-).

If you configure your Toolbar in the designer, IDs are automatically generated. However, if you add your items at runtime through code, you need to specify an ID yourself:

//create an "edit" button
ToolbarButton editItem = new ToolbarButton();
editItem.ID = "EditItem";

General formatting troubles with Non-IE browsers

Per default, ASP.NET renders down-level output for all non-IE browsers (pathetic...) which prevents the rendering of CSS styles for the Toolbar. As an example, your toolbar could look bad if you use labels for image items:

To properly identify Firefox & Co., it's important to have an updated browserCaps configuration (stands for "Brower Capabilities"). Rob Everhardt did a great job here. You can find an introduction to browserCaps, links and downloads at his site.

If you can't update your browserCaps for some reason, you can also fix the Toolbar layout with a declaration in an external stylesheet (the sample assumes the CSS class of the Toolbar is mytoolbar).

/* adjust images and image buttons via external CSS */
.mytoolbar img, .mytoolbar input
{
  vertical-align:middle;
  border: none;
}

The sample looks like crap on Netscape 4.x

Yes, it does, and I can perfectly live with that. I had to choose between deprecated HTML tags (align, border etc.) and proper CSS skinning. I chose the latter which works perfectly with all major browsers I tested.

However, if you need a down-level version of this control, you should be able to get it with very little effort (but don't expect me to do it for you ;-). Have a look at the rendering methods of the Toolbar and ImageItem classes and exchange the CSS rendering with the corresponding HTML attributes.

Acknowledgements and Licensing

To output JavaScript for the rollover links, I started with a procedure from MetaBuilders' RollOverLink which I adapted to my needs. MetaBuilders offer a nice variety of controls on their site - check it out.

The background theme of the horizontal Toolbar sample was taken from the great PHPBB2 bulletin board. Graphics of the vertical Toolbar example are mine, feel free to use them.

This control is released under the less restrictive GNU Lesser General Public License (LGPL). While you can't slap your name on it and claim it to be yours (or even sell it), you are free to adapt it to your needs and use it in both free and commercial applications. Have fun!

Newsletter

This is the first release and I'm pretty sure there will be bug fixes and enhancements. If you don't want to check back for updates, you can subscribe to a newsletter at my site.

History

• V 1.0: Initial release (Jan 22, 2005)
• V 1.01: Updated properties with 'Localizable' attributes to support i18n.
• V 1.02: Made library CLS compliant (thanks to Jorge Castellanos)