After you've referenced the assembly and registered the control within application you may add its' markup to .aspx pages (see introduction post about how to add the control to the project).
From development point of view programming the control is no way different from using standard CheckBoxList control. It has same events (in fact only one is of interest - OnSelectedIndexChanged) and members (except those relevant to new rendering and client side behavior).
Example to start with
Let's have a look at an example and comment it. Bellow is a markup snippet from .aspx file:
...
<asp:DropDownCheckBoxes ID="yearsDropDownCheckBoxes" runat="server"
OnSelectedIndexChanged="checkBoxes_SelcetedIndexChanged"
AddJQueryReference="True" UseButtons="True" UseSelectAllNode="True">
<Style SelectBoxWidth="160" DropDownBoxBoxWidth="160" DropDownBoxBoxHeight="80" />
<Texts SelectBoxCaption="Year" />
</asp:DropDownCheckBoxes>
...
<div style="padding-top: 20px;">
<h1>
Selected items (updated whenever postback from any of the controls occurs)
</h1>
<asp:Panel ID="selectedItemsPanel" runat="server">
</asp:Panel>
</div>
Code snippet from the corresponding code-behind file:
protected void Page_Load(object sender, EventArgs e)
{
if (!IsPostBack)
{
var years = new int[20];
var currentYear = DateTime.Now.Year;
for (int i = 0; i < years.Length; i++)
years[i] = currentYear--;
yearsDropDownCheckBoxes.DataSource = years;
yearsDropDownCheckBoxes.DataBind();
}
}
protected void checkBoxes_SelcetedIndexChanged(object sender, EventArgs e)
{
selectedItemsPanel.Controls.Clear();
foreach (ListItem item in (sender as ListControl).Items)
{
if (item.Selected)
selectedItemsPanel.Controls.Add(
new Literal()
{ Text = item.Text + " : " + item.Value + newLineConst } // HTML line break
);
}
}
The page contains a drop down check boxes for selecting years and a panel bellow which displays checked items whenever a postback from the control occurs (code for other controls from the picture was cut above):
From the example we see that a control yearsDropDownCheckBoxes is added to a page, the event handler checkBoxes_SelcetedIndexChanged for SelcetedIndexChanged event is assigned and the page load handler performs data binding for the control. Whenever a user clicks 'OK' button in the drop down list a postback goes to server and panel in the bottom of the page is filled with all checked items. Everything is straightforward and no different from using controls inherited from ListControl(including CheckBoxList).
Postback options & behavior
Properties DropDownCheckBoxes.AutoPostBack (default value is 'false') and DropDownCheckBoxes.UseButtons (default value is 'true') control the way postbacks from the control arise:
1. AutoPostBack == false && UseButtons == false - in this case no 'OK/Cancel' buttons are displayed in the bottom of the drop down box, no postback occurs when a user clicks outside control and drop down gets hidden. The server side event will be fired (if there's a handler specified) during postback from any other control from the page (in case selection change is detected). The behavior in this case is similar to other ASP.NET controls with AutoPostBack set to false;
2. AutoPostBack == true && UseButtons == false - no action buttons ( 'OK/Cancel' ) are displayed, postback occurs whenever a user leaves the expanded drop down by clicking outside it.
3. UseButtons == true (AutoPostBack value doesn't matter) - in this case there're action buttons displayed in the bottom of the drop down box. Postback is triggered only when a user clicks 'OK' button. Clicking 'Cancel' or outside the control collapses the drop down and restores the check box selection prior to opening the control.
JQuery dependency
JQuery library is delivered within the control assembly and the reference to it is automatically added to the page by the control. In case you have JQuery referenced on the page (e.g. in a master page) script errors may occur.
In order to turn off automatic reference adding set DropDownCheckBoxes.AddJQueryReference to 'false'.
Other control properties
- DropDownCheckBoxes.UseSelectAllNode - if 'true' then there's a 'Select all' check box added on top of other check boxes in the drop down. Clicking the check box changes all other check boxes' to corresponding state.
- DropDownCheckBoxes.Texts - a complex property that allow to change default texts of the control elements (caption, button names, 'Select all' check box), e.g. for localization.
- DropDownCheckBoxes.CssClass - specifies CSS class name applied to the control (specifically the DIV element which wraps all the contents). Setting this peoperty has the same effect as using DropDownCheckBoxes.Style.SelectBoxCssClass property.
- DropDownCheckBoxes.Style - a complex property that allows applying CSS classes to the control and also directly specify sizes of the control elements (height of the select box, width and height of drop down box).
NOTE: The control can work within update panel without any adjustments.
The project page at Codeplex can be found here.
