<asp:BulletedList> Control

The <asp:BulletedList> control creates a list of items prefixed with a bullet character. The items can be text lists, hyperlinks, or link buttons to activate subprograms. Items in the list can be coded as individual <asp:ListItem> elements or they can be bound from an external data source. The general format for the BulletedList is shown below.

<asp:BulletedList id="id" Runat="Server"
  BulletImageUrl="url"
  BulletStyle="Circle|CustomImage|Disc|LowerAlpha|LowerRoman|
               Numbered|Square|UpperAlpha|UpperRoman|NotSet"
  DataSourceID="id"
  DataTextField="field"
  DataTextFormatString="{string}"
  DataValueField="field"
  DisplayMode="HyperLink|LinkButton|Text"
  FirstBulletNumber="n"
  Target="_blank|_self|_search|_top|_parent|framename"
  OnClick="subprogram"
    property="value"...
>
	
  <asp:ListItem
    Selected="True|False"
    Text="label"
    Value="value"
  />
  ...
	
</asp:BulletedList>
Figure 6-53. General format for <asp:BulletedList> control.

Displaying Static List Items

A BulletedList can be coded to present a static list of indented, bulleted text items. In the following example, the list is produced by coding a default BulletedList with items coded as individual ListItem controls. A default Disc character prefixes the indented items.


  • Item 1
  • Item 2
  • Item 3
Figure 6-54. A default BulletedList.
<asp:BulletedList Runat="Server">
  <asp:ListItem Text="Item 1"/>
  <asp:ListItem Text="Item 2"/>
  <asp:ListItem Text="Item 3"/>
</asp:BulletedList>
Listing 6-44. Code for a static BulletedList.

Various bullet characters, letters, and numbers can prefix list items by coding the BulletStyle property of a BulletedList. Available characters are shown in the following table.

Circle
  • Item 1
  • Item 2
  • Item 3
 Disc
  • Item 1
  • Item 2
  • Item 3
 LowerAlpha
  1. Item 1
  2. Item 2
  3. Item 3
 LowerRoman
  1. Item 1
  2. Item 2
  3. Item 3
Numbered
  1. Item 1
  2. Item 2
  3. Item 3
 Square
  • Item 1
  • Item 2
  • Item 3
 UpperAlpha
  1. Item 1
  2. Item 2
  3. Item 3
 UpperRoman
  1. Item 1
  2. Item 2
  3. Item 3
Figure 6-55. BulletedLists with various bullet characters.

A BulletedList begins its alphabetic, numbered, or Roman numeral numbering with the first character in the numbering system. That is, an alphabetic list begins with "A", a numbered list begins with "1", and a Roman numeral list begins with "I", using appropriate upper- or lower-case characters. However, the beginnning character in a list can be changed with the FirstBulletNumber="n" property, where n is a decimal digit giving the starting position in the numbering system. For example, if FirstBulletNumber="5" is coded for a BulletedList, then a Numbered list begins with "5", a LowerAlpha list begins with "e", an UpperAlpha list begins with "E", a LowerRoman list begins with "v", and an UpperRoman list begins with "V".

Graphic images can be used for the bullets. In this case, BulletStyle is set to "CustomImage" and the URL for the image is given in the BulletedList's BulletImageUrl property.

Displaying HyperLinks

A BulletedList can display a list of hyperlinks by setting its DisplayMode="HyperLink" and supplying URLs for the ListItems' Value properties. The URL is used as the Text display property of the items unless a different text string is coded. The URLs can be targeted to a different browser window or frame with the Target property.

Search sites:

Figure 6-56. A BulletedList of hyperlinks.
<h4>Search sites:</h4>

<asp:BulletedList Runat="Server"
  BulletStyle="CustomImage"
  BulletImageUrl="Link.gif"
  DisplayMode="HyperLink" 
  Target="_blank">
    <asp:ListItem Text="AltaVista" Value="http://www.altavista.com"/>
    <asp:ListItem Text="Google" Value="http://www.google.com"/>
    <asp:ListItem Text="Yahoo" Value="http://www.yahoo.com"/>
</asp:BulletedList>
Listing 6-45. Code for a BulletedList of hyperlinks.

The above links are prefixed with a graphic image by coding BulletStyle="CustomImage" and giving the URL of the image in the BulletImageUrl property. In this case, the Link.gif image is in the same directory as the page.

Database Display

A BulletedList can be bound to a data source control to supply the items in the list. Also, it can operate like a series of LinkButton controls to call a subprogram when clicked. Therefore, a BulletedList can be created dynamically to produce database displays as shown in the following example.

View Book Types


BookIDBookTitleBookPriceBookQty
DB111Oracle Database$69.9910
DB222Databases in Depth$29.956
DB333Database Processing$136.6512
DB444Access Database Design$34.9525
DB555SQL Server 2005$29.990

Figure 6-57. Using a BulletedList to issue SQL statements for product displays.
<SCRIPT Runat="Server">

Sub Add_List_Item (Src As Object, Args As EventArgs)

  BookList.Items.Add(New ListItem("All Books"))

End Sub

Sub Show_Books (Src As Object, Args As BulletedListEventArgs)
	
  Dim SQLString As String
  If BookList.Items(Args.Index).Text = "All Books" Then
    SQLString = "SELECT BookID, BookTitle, BookPrice, BookQty FROM Books " & _
                "ORDER BY BookID" 
  Else
	  SQLString = "SELECT BookID, BookTitle, BookPrice, BookQty FROM Books " & _
                "WHERE BookType = '" & BookList.Items(Args.Index).Text & "' " & _
                "ORDER BY BookID"
  End If
  BookSource2.SelectCommand = SQLString

End Sub

</SCRIPT>

<form Runat="Server">

<h3>View Book Types</h3>

<asp:AccessDataSource id="BookSource1" Runat="Server"
  DataFile="../Databases/BooksDB.mdb"
  SelectCommand="SELECT DISTINCT BookType From Books ORDER By BookType"/>

<asp:BulletedList id="BookList" Runat="Server"
  BulletStyle="Circle"
  DisplayMode="LinkButton"
  DataSourceID="BookSource1"
  DataTextField="BookType"
  OnClick="Show_Books"
  OnDataBound="Add_List_Item"/>
<br/>

<asp:AccessDataSource id="BookSource2" Runat="Server"
  DataFile="../Databases/BooksDB.mdb"
  SelectCommand="SELECT BookID, BookTitle, BookPrice, BookQty FROM Books
                 WHERE BookType = 'DataBase' ORDER BY BookID"/>

<asp:GridView id="BookGrid" DataSourceID="BookSource2" Runat="Server"/>

</form>
Listing 6-46. Using a BulletedList to populate a GridView.

The BulletedList has its DisplayMode set to "LinkButton" in order to create a set of links that call a subprogram given by its OnClick event handler. The list is initially built by binding to an AccessDataSource that returns book types from the BooksDB.mdb database. This BookType field from the database is bound to items in the list through its DataTextField property, thereby displaying these types in the list. The text displays in the list can be formatted differently by supply a DataTextFormatString.

In addition to displaying item types from the database, the list includes an "All Books" item that displays all books from the database when clicked. Since this item is not produced by data binding to the database, it must be added programmatically to the BulletedList. Also, it must be added after the list is bound to its data source—after the list is created—by including an OnDataBound event handler in the BulletedList. After the BulletedList is bound from the data source, subprogram Add_List_Item is called to add the new item.

Like other kinds of list controls, a BulletedList has an Items collections representing all of the items in the list. Subprogram Add_List_Item simply appends the "All Books" item to this collection with the following statement.

BookList.Items.Add(New ListItem("All Books"))
Listing 6-47. Code to add an item to a BulletedList.

The text string "All Books" becomes the Text property of the new item in the same way that book types from the database become Text properties through the BulletedList's DataTextField binding expression.

The OnClick event handler of the BulletedList calls subprogram Show_Books when clicked. This subprogram determines which item in the list was clicked and issues an appropriate SQL command for the AccessDataSource bound to the GridView. Note that this subprogram has the special BulletedListEventArgs argument necessary for a call from a clicked item in a BulletedList.

Two types of SQL statements are formatted by the subprogram. If the "All Books" item is clicked, then all records from the database are retrieved. Otherwise, a WHERE clause is added to the statement to select the book type given by the Text property of the clicked link.

Dim SQLString As String
If BookList.Items(Args.Index).Text = "All Books" Then
  SQLString = "SELECT BookID, BookTitle, BookPrice, BookQty FROM Books " & _
              "ORDER BY BookID" 
Else
  SQLString = "SELECT BookID, BookTitle, BookPrice, BookQty FROM Books " & _
              "WHERE BookType = '" & BookList.Items(Args.Index).Text & "' " & _
              "ORDER BY BookID"
End If
Listing 6-48. Code to compose an appropriate SELECT statement for selections from a BulletedList.

The only data value passed to and available through the subprogram argument list is the Index of the clicked item in the list (the Args.Index argument), numbered beginning with 0. This value is used to reference the Text property—the name of a book type—of the clicked item. If, for instance, the first item in the BulletedList is clicked, then Arg.Index is 0 and the Text property BookList.Items(0).Text ("Database" in this instance) is added to the WHERE clause. One of the two versions of the SELECT statement is issued through the GridView's AccessDataSource by assignment to its SelectCommand property.

It is mentioned above that a BulletedList works like a series of LinkButton controls. The difference is that LinkButtons cannot be bound to an external data source. Individual buttons must be coded to produce the items in the list. The BulletedList, in contrast, is a bindable control that automatically produces a list from an external source. It is the only control that creates a clickable list of text links without having to explicitly code individual items.