Introducing the C1WebTopicBar Control

Applies To:

WebMenus and WebBars for ASP.NET

Author:

John Juback

Published On:

4/4/2005

The 2004 v4 release of ComponentOne WebMenus and WebBars for ASP.NET introduces a new component, C1WebTopicBar, which allows you to implement elegant Windows XP-style or custom-designed navigation panels on your Web Pages. C1WebTopicBar provides complete control over its appearance, including the ability to host arbitrary Web controls within its panels. A single C1WebTopicBar component contains one or more item groups that users can expand and collapse. Depending on how the component is configured at design time, users can also reorder the groups by dragging and dropping their headers.

In the new ComponentOne Web site, you may have noticed the Resources and Purchase Options sidebars on individual product pages. These sidebars were implemented as a single C1WebTopicBar component with two collapsible groups.

Like the other components in C1WebCommand, C1WebTopicBar provides an Auto Format command at design time for selecting a predefined look and feel, such as Windows XP or Outlook 2003. The following figures illustrate the differences between the two formats. In each case, a single C1WebTopicBar control is configured entirely at design time to contain four groups, with the third group being a panel that hosts a calendar control.

The component on the left is formatted as Windows XP and is shown here with the first and last groups collapsed. The component on the right is formatted as Outlook 2003, which uses a "button bar" presentation model to display one group at a time, resulting in a more compact display.

A C1WebTopicBar component consists of one or more groups, of which there are two kinds:

  1. C1WebTopicBarItemsGroup, a collection of navigation items.
  2. C1WebTopicBarPanelGroup, a container for other controls dropped onto an associated Panel control at design time.

At design time, you can add and remove both kinds of groups by accessing the Groups collection property in the Properties window. Clicking the ellipsis button opens the C1WebTopicBarCustomGroup Collection Editor, which contains a list of groups, Add and Remove buttons, and a property browser for setting group properties and accessing their items. The Add button contains a dropdown arrow that opens a menu from which you can select one of the two group types (items or panel).

After adding a new group, change its Text property to the desired string. Generally, you can keep the default settings for the other group properties, but there are a few of them that you may want to change:

  • By default, groups are expanded when they are first displayed. To change the initial display state of a group to collapsed, set the Collapsed property to True.
  • By default, users can expand and collapse groups. To prevent this on a per-group basis, set the EnableExpandCollapse property to False.
  • To provide mouseover text for a group header, set the ToolTip property to the desired string.

To add items to a C1WebTopicBarItemsGroup, click the ellipsis button next to the Items collection property to open the C1WebTopicBarItem Collection Editor, which contains a list of items, Add and Remove buttons, and a property browser for setting item properties.

After adding a new item, change its Text property to the desired string, and optionally set its ImageUrl property to point to the image file to be associated with the item. To make the new item functional, you need to assign it an action using one of these three methods:

  1. Set the NavigateUrl property to create a navigation link.
  2. Set the Script property to execute client-side Javascript.
  3. Set the CommandName property to a string that you will handle in the component's ItemClicked event. You can optionally set the CommandArgument property to provide additional information for the event handling code.

To add controls to a C1WebTopicBarPanelGroup, drag and drop controls from the Toolbox onto the body of the panel group. If you need to adjust the panel's height, select the panel in the C1WebTopicBarCustomGroup Collection Editor and change its BodyHeight property to the desired value.

If the groups and items are not known in advance at design time, you can dynamically populate a C1WebTopicBar component in code. This is the technique used in the online Feature Tours on the ComponentOne Web site, as shown in the following illustration. Note also that the initial group header has a slightly different presentation than the other groups. This was done by modifying the group's ExpandedHeaderStyle and CollapsedHeaderStyle properties in code.

Here is a simplified version of the utility function used to create the item groups on-the-fly:

private C1WebTopicBarItemsGroup AddLeftTopicBarGroup(string name, bool header)  
{  
    C1WebTopicBarItemsGroup group = new C1WebTopicBarItemsGroup();  

    int pad = header ? 32: 5;  
    string div = String.Format("{1}", pad, name);  
    group.Text = div;  

    if (header)  
    {  
        group.ExpandedHeaderStyle.BackgroundImageUrl = "images/Components.jpg";  
        group.ExpandedHeaderStyle.BackColor = Color.FromArgb(172, 173, 191);  
        group.ExpandedHeaderStyle.ForeColor = Color.White;  
        group.ExpandedHeaderStyle.IndicatorUrl = "images/darkarrow_up.gif";  
        group.CollapsedHeaderStyle.BackgroundImageUrl = "images/Components.jpg";  
        group.CollapsedHeaderStyle.BackColor = Color.FromArgb(172, 173, 191);  
        group.CollapsedHeaderStyle.ForeColor = Color.White;  
        group.CollapsedHeaderStyle.IndicatorUrl = "images/darkarrow_down.gif";  
        group.MouseOverExpandedHeaderStyle.IndicatorUrl = "images/darkarrow_uphover.gif";  
        group.MouseOverCollapsedHeaderStyle.IndicatorUrl = "images/darkarrow_downhover.gif";  
    }  

    C1WebTopicBar1.Groups.Add(group);  
    return group;  
}

Notice that the group's Text property is set to a

tag instead of a plain string. This is a trick used to override the default behavior of the component, which is to center the group's text. The padding-left style attribute is also set to accommodate the width of the header's background image. Non-header groups have no background image, so they use a smaller offset (5 pixels).

This function is called once for each item group, as the following code demonstrates:

// Clear all of the groups  
C1WebTopicBar1.Groups.Clear();  

// Add the overview header group  
C1WebTopicBarItemsGroup group = AddLeftTopicBarGroup("FlexGrid for .NET", true);  

// Initialize its one and only item  
C1WebTopicBarItem item = new C1WebTopicBarItem();  
item.Text = "Overview";  
item.CommandName = "Select";  
item.CommandArgument = "some url";  
item.ImageUrl = "images/info_sm.gif";  
group.Items.Add(item);  

// Add the first non-header group  
group = AddLeftTopicBarGroup("Outlines and Summaries", false);  

// Create and initialize its items  
string[] names = {"Subtotals", "Data Analysis", "Hierarchical Views", "Tree Views"};  

for (int i = 0; i < names.Length; i  )  
{  
    item = new C1WebTopicBarItem();  
    item.Text = names[i];  
    item.CommandName = "Select";  
    item.CommandArgument = "some url";  
    item.ImageUrl = "images/webform_sm.gif";  
    group.Items.Add(item);  
}  

// Repeat for the remaining non-header groups...

Note that this code is for illustrative purposes only. In the actual application, the structure of the groups is derived by parsing a text file, not by examining hard-coded arrays.

You can view the C1WebTopicBar control in action by visiting the following link:

[ASP.NET Feature Tour](http://www.componentone.com/c1webdemo/?Platform=WebForms)

From there, you can also download the source code for the ASP.NET Feature Tour (also called the C1WebDemo application), which contains sample forms using C1WebTopicBar, including an advanced sample that implements a tree control by dynamically nesting C1WebTopicBar components populated entirely in code.

MESCIUS inc.

comments powered by Disqus