ASP.NET ComboBox Control - Defining the Structure

APNSoft ComboBox uses XML for defining the structure since XML is the most convenient and widespread format for structured data. The XML Structure consists of elements (items and separators):

<ComboBox>
    <item title="AltaVista" />
    <item title="Google" />
    <item title="Yahoo" />
    <separator />
    <item title="AlltheWeb" />
    <item title="dmoz" />
    <item title="Excite" />
    <item title="GO" />
    <item title="HotBot" />
    <item title="MSN" />
    <item title="Overture" />
</ComboBox>

The code above creates the following ComboBox:

Structure elements:

<ComboBox /> - the root element for entire ComboBox Structure File. Does not include attributes.
<item /> - one ComboBox element in DropDown List. Available attributes:
- AutoPostBackOnItemClick - specifies a value indicating whether the control causes a postback to the server when the item is clicked.
- ClientSideOnItemClick - specifies the client-side code to be launched when the item is clicked. Can include variables $ComponentID$, $ItemID$ and $Title$. Each variable is replaced to the corresponding value.
- href, target - the URL and target the browser is directed to when a user clicks the Item. The href attribute can include variables $ComponentID$, $ItemID$ and $Rnd$. Each variable is replaced to the corresponding value. The $Rnd$ displays a random number. It can be used as an additional parameter to avoid page caching in browser.
- icon - specifies the name of item's icon image. The icon image displayed at the left side of the item. The icon images must be located in the Skin Folder as specified by the SkinFolder property.
- iconOver - specifies the name of the icon for hovered item.
- iconWidth, iconHeight - one Item's icon image width and height. Attributes are optional. Control automatically calculates Width and Height of each icon.
- id - specifies a unique identifier for the element. The attribute is required. If the id attribute is not specified, the component will automatically set it for each item (id="itm1", id="itm2", etc.).
- leftSpan - specifies the blank space in pixels at the left side of the current Item.
- selected - specifies a value indicating whether the item is selected.
- title - specifies the text (caption) displayed for the item.

<separator /> - element for horizontal separator. Available attributes:
- id - specifies a unique identifier for the element. The attribute is required. If the id attribute is not specified, the component will automatically set it for each separator (id="spr1", id="spr2", etc.).

ComboBox element examples:

<item id="i1" title="Home" href="~/Default.aspx?ItemID=$ItemID$&amp;Rnd=$Rnd$" />
<item title="Local Disk" icon="IconDisk.gif" iconOver="IconDiskActive.gif" />
<item title="Google" href="http://www.google.com" target="_blank" />
<item title="Yahoo" selected="true" leftSpan="16" />
<item title="JavaScript" ClientSideOnItemClick="alert('The $Title$ ($ItemID$) is clicked!');" />

Attention! Element names and attributes are case-sensitive. Be careful when you're typing in your data.

Applying the XML Structure or Data Source:

You can save the XML definition structure as a file and bind the ComboBox by specifying the StructureFileURL property.

<APNSoft:APNSoftComboBox id="myComboBox" runat="server"
    StructureFileURL = "~/Structures/ComboBox.xml" />

You can also apply the XML Document with structure by using the DataSource property. If the control loads structure from the database, you should set the DataSource property to specify a source of data and call the DataBind() method. To create an appropriate table in the SQL Server, use the following SQL command:

CREATE TABLE [dbo].[Items](
    [id] [nvarchar](20) NOT NULL,
    [Type] [nvarchar](10) NOT NULL CONSTRAINT [DF_Items_Type] DEFAULT ('item'),
    [title] [nvarchar](250) NULL,
    [href] [nvarchar](250) NULL,
    [target] [nvarchar](100) NULL,
    [icon] [nvarchar](100) NULL,
    [iconOver] [nvarchar](100) NULL,
    [iconWidth] [tinyint] NULL,
    [iconHeight] [tinyint] NULL,
    [AutoPostBackOnItemClick] [bit] 
        NOT NULL CONSTRAINT [DF_Items_AutoPostBackOnItemClick] DEFAULT ((0)),
    [ClientSideOnItemClick] [nvarchar](250) NULL,
    [selected] [bit] NOT NULL CONSTRAINT [DF_Items_selected] DEFAULT ((0)),
    [leftSpan] [smallint] NULL
)

You can also build up ComboBox at runtime. APNSoft ComboBox provides an extremely rich and powerful server-side API allowing developer to add, remove or edit elements and element collections. You can programmatically control any item at runtime by using two classes ComboBoxElement and ComboBoxElementCollection.