Command Control

Article
09/14/2006

The Command control provides a way to invoke ASP.NET event handlers from UI elements, thus posting user input from UI elements back to the server. The Command control implements the IPostBackDataHandler interface so that it can handle the postback event created by clicking an image.

Mobile Controls Syntax

Required properties, defaults, and code-featured elements are noted in bold type.

<mobile:Command
   runat="server"
   id="id"
   Font-Name="fontName"
   Font-Size="{NotSet|Normal|Small|Large}"
   Font-Bold="{NotSet|False|True}"
   Font-Italic="{NotSet|False|True}"
   ForeColor="foregroundColor"
   BackColor="backgroundColor"
   Alignment="{NotSet|Left|Center|Right}"
   BreakAfter="{True|False}"
   EnableViewState="{True|False}"
   StyleReference="styleReference"
   Text="text"
   Visible="{True|False}"
   Wrapping="{NotSet|Wrap|NoWrap}"

   CausesValidation="{NotSet|False|True}"
   CommandArgument="commandArgument"
   CommandName="commandName"
   Format="Button|Link"
   ImageUrl="imageUrl"
   OnClick="clickEventHandler"
   OnItemCommand="commandEventHandler"
   SoftkeyLabel="softkeyLabel">
innerText
</mobile:Command>

Containment Rules

The following controls can contain a Command control.

Control	Comments
System.Web.UI.MobileControls.Form	Can contain any number of Command controls.
System.Web.UI.MobileControls.Panel	Can contain any number of Command controls.

The text controls cannot contain any other controls.

Device Templates

None.

Device-Specific Behavior

The style with which a command is rendered will differ based on the device, but the text of the command will appear on all devices. You can invoke the Command control from all devices.

Device language Description of behavior

HTML

Device language	Description of behavior
HTML	The Command control is rendered as an <input> tag as a button followed by a <br/> If there are multiple commands on the same form and a submit action occurs, the first command will receive the Click event. On some HTML forms, ENTER has no effect however, if ENTER is pressed with a Command control on the page, the first command receive the Click event.
WML	A Command control generates WML in the following format. `<anchor>TextProperty<go href="postbackinfo"/> </go></anchor> <br/>` Note You must avoid the use of special characters in ASP.NET mobile Web Forms page URLs. HREF tags generated for posting command events back to the server are not strictly validated. A URL that includes spaces results in the generation of WML that some WML browsers cannot handle. In certain circumstances, such as form submission, the Command control is rendered to WML as a <do> element instead of as an anchor. In these cases, the FontSize, FontStyle, and Wrapping properties are ignored.

The Command control is rendered as an <input> tag as a button followed by a <br/>

If there are multiple commands on the same form and a submit action occurs, the first command will receive the Click event. On some HTML forms, ENTER has no effect however, if ENTER is pressed with a Command control on the page, the first command receive the Click event.

WML

A Command control generates WML in the following format.

<anchor>TextProperty<go href="postbackinfo"/> </go></anchor>
<br/>

Note You must avoid the use of special characters in ASP.NET mobile Web Forms page URLs. HREF tags generated for posting command events back to the server are not strictly validated. A URL that includes spaces results in the generation of WML that some WML browsers cannot handle.

In certain circumstances, such as form submission, the Command control is rendered to WML as a <do> element instead of as an anchor. In these cases, the FontSize, FontStyle, and Wrapping properties are ignored.

Example

The following example uses two labels — one on each form. The first label is not modified, and thus does not require an ID value. The ID value for the second label is WelcomeMessage and its text value is set in the Button_OnClick ** event handler.

<%@ Page Inherits=
   "System.Web.UI.MobileControls.MobilePage" Language="VB" %>
<%@ Register TagPrefix="mobile"
    Namespace="System.Web.UI.MobileControls"
    Assembly="System.Web.Mobile" %>

<script language="vb" runat="server">
protected Sub Button_OnClick(sender As Object, e As EventArgs) 
   WelcomeMessage.Text = "Welcome to my app, " + NameEdit.Text
   ActiveForm = SecondPanel
End Sub
</script>

<mobile:Form runat="server">
   <mobile:Label runat="server">Enter your name</mobile:Label>
   <mobile:TextBox runat="server" id="NameEdit" />
   <mobile:Command runat="server" id="Button" OnClick="Button_OnClick">
      OK
   </mobile:Command>
</mobile:Form>

<mobile:Form runat="server" id="SecondPanel">
   <mobile:Label runat="server" id="WelcomeMessage" />
</mobile:Form> 
[C#]
<%@ Page Inherits=
   "System.Web.UI.MobileControls.MobilePage" Language="C#" %>
<%@ Register TagPrefix="mobile"
    Namespace="System.Web.UI.MobileControls"
    Assembly="System.Web.Mobile" %>

<script language="c#" runat="server">
protected void Button_OnClick(Object sender, EventArgs e) 
{
   WelcomeMessage.Text = "Welcome to my app, " + NameEdit.Text;
   ActiveForm = SecondPanel;
}
</script>

<mobile:Form runat="server">
   <mobile:Label runat="server">Enter your name</mobile:Label>
   <mobile:TextBox runat="server" id="NameEdit" />
   <mobile:Command runat="server" id="Button" OnClick="Button_OnClick">
      OK
   </mobile:Command>
</mobile:Form>

<mobile:Form runat="server" id="SecondPanel">
   <mobile:Label runat="server" id="WelcomeMessage" />
</mobile:Form>