InputFormCheckBox, InputFormCheckBoxList and InputFormCheckBoxListValidator

The InputFormCheckBox control can be used to place a single check box on a SharePoint web part or application page. If you want to offer to the user a set of different options, you can use the InputFormCheckBoxList. The InputFormCheckBoxValidator is destined to validate an InputFormCheckBox or InputCheckBoxList.

All three controls are located in the Microsoft.SharePoint.WebControls namespace of the Microsoft.SharePoint.dll.

 

The InputFormCheckBox control

You can declare an InputFormCheckBox control on an application page using the following syntax:

<spuc:InputFormCheckBox ID="SampleInputFormCheckBox" runat="server" LabelText="Single Option" ButtonSpacing="20" />

Don’t forget to add the page directive:

<%@ Register TagPrefix="spuc" Namespace="Microsoft.SharePoint.WebControls"
             Assembly="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>

In code this would look as follows:

InputFormCheckBox checkbox = new InputFormCheckBox();
checkbox.ID = "inputFormCheckBox1";
checkbox.Text = "Single Option";
checkbox.AutoPostBack = true;
checkbox.CheckedChanged += new EventHandler(checkbox_CheckedChanged);

The InputFormCheckBoxList inherits from the ASP.NET CheckBoxList, located in the System.Web.UI.WebControls namespace of the System.Web.dll and has no additional properties, methods or events. There are a number of properties/attributes that you can set on the InputFormCheckBox:

• AutoPostBack: set this property to true if you want the page to post back when this option is checked or unchecked. In that case you have to implement the CheckedChanged event.
• ButtonSpacing: specify the number of pixels you want to be added between the check box and the following control.
• Checked: set this property to true if you want the check box to appear selected.
• Text: you can set the text property to appear next to the check box, but in that case you also have to set the width property. If you want a label to appear next to the check box, you can better use the LabelText property.
• LabelText: specify the text that you want to appear next to the check box.
• ToggleChildren: if the check box has child controls, they will also be selected when the check box is selected or unselected when the check box is unselected.
• InputAttributes: this property comes from the normal ASP.NET attribute. It is the collection of attributes for the check box itself.
• LabelAttributes: also this property is inherited from the normal ASP.NET attribute. It is the collection of attributes that belongs to the label element of the check box.

As with a normal ASP.NET CheckBox, you can add an event handler to the CheckedChanged event to handle the user choice.

 

The InputFormCheckBoxList control

If you want to use an InputFormCheckBoxList control on an application page, declare it as follows:

<spuc:InputFormCheckBoxList ID="SampleInputFormCheckBoxList" runat="server" class="ms-authoringcontrols">
      <asp:ListItem Text="Option 1" Value="1" />
      <asp:ListItem Text="Option 2" Value="2" />
      <asp:ListItem Text="Option 3" Selected="True" Value="3" />
      <asp:ListItem Text="Option 4" Value="4" />
</spuc:InputFormCheckBoxList>

Use the same page directive as for the InputFormCheckBox control.

The InputFormCheckBoxList inherits from the ASP.NET CheckBoxList, located in the System.Web.UI.WebControls namespace of the System.Web.dll and has no additional properties, methods or events. Don’t forget to set the class attribute on the InputFormCheckBoxList element or the ListItem elements will be rendered differently.

 

The InputFormCheckBoxList control using a data source

You can bind an InputFormCheckBoxList to a SharePoint data source. This type of data source can retrieve data from a list or site. A SharePoint data source can be defined as follows:

<spuc:SPDataSource runat="server" ID="SkillsDataSource"
      DataSourceMode="List"  
      SelectCommand="<Query><OrderBy><FieldRef Name='Title' Ascending='true' /></OrderBy></Query>" >
      <SelectParameters>     
         <asp:Parameter Name="ListName" DefaultValue="Skills" /> 
      </SelectParameters>
</spuc:SPDataSource>                       

The data source in this sample retrieves al list items from the Skills list.

Set the DataSourceID property from the InputFormCheckBoxList control to the SPDataSource control. The DataTextField property indicates the field that will be displayed as the options. The DataValueField property indicates the field that will be used as the value for the option.

<spuc:InputFormCheckBoxList ID="SkillsInputFormCheckBoxList" runat="server" class="ms-authoringcontrols"
      DataSourceID="SkillsDataSource" DataTextField="Title" DataValueField="ID" />

 

The InputFormCheckBoxValidator control

This validator control can only be used against an InputFormCheckBoxList control (and not an InputFormCheckBox control).  It works as a required field validator: if no options are selected when clicking the OK button, the specified error message will appear:

<spuc:InputFormCheckBoxList ID="SampleInputFormCheckBoxList" runat="server" class="ms-authoringcontrols">
      <asp:ListItem Text="Option 1" Value="1" />
      <asp:ListItem Text="Option 2" Value="2" />
      <asp:ListItem Text="Option 3" Selected="True" Value="3" />
      <asp:ListItem Text="Option 4" Value="4" />
</spuc:InputFormCheckBoxList>
<spuc:InputFormCheckBoxListValidator ID="SampleCheckBoxValidator" runat="server"
      ControlToValidate="SampleInputFormCheckBoxList"  ErrorMessage="This is a sample error message." />

If you try to use it in combination with a InputFormCheckBox  control, you will get an unclear error message (not informing you about the real problem) but when looking with Reflector into the code, it learns you that the control referenced in the ControlToValidate property is casted to an InputFormCheckBoxList  control.