NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Custom Server Control Syntax

Custom server controls enable you to create reusable components that encapsulate common programmatic functionality. You can create your own custom server controls, or use the Web Controls shipped with the NGWS frameworks.

Server Control Declaration Syntax

You can instantiate a control by specifying declarative tags in an .aspx file. These tags must include a runat=server attribute/value pair. If you want to enable programmatic referencing on the control, specify a unique id attribute.

Custom server control tags insert rich server controls (including user-authored controls and all Web Controls.

<tagprefix:tagname id=”OptionalID runat=server />
OR
<tagprefix:tagname id=”OptionalID runat=server >  </tagprefix:tagname>

Parameters

tagprefix
An alias for the fully qualified namespace of the control. The alias for Web Controls is ASP. Aliases for user-authored controls are declared with the @ Register Directive.
tagname
The name of the class that encapsulates the control.
OptionalID
A unique identifier to enable programmatic references to the control.

Remarks

Custom server controls are reusable components that encapsulate common programmatic functionality. Page developers use custom server controls by specifying declarative tags that have a runat="server" attribute. The optional id attribute defines a unique identifier for programmatic reference.

Example

The following code fragment inserts a TextBox Web Control:

<ASP:TextBox id="MyTextBox" runat="server" />

Server Control Property Syntax

Custom server control properties are specified using declarative attribute/value pair syntax. The case-insensitive attribute name represents the property name, and the value represents the property value to assign.

<tagprefix:tagname id="OptionalID" propertyname="propertyvalue" runat=server />

Parameters

tagprefix
An alias for the fully qualified namespace of the control. The alias for Web Controls is asp. Aliases for user-authored controls are declared with the @ Register Directive.
tagname
The name of the class that encapsulates the control.
OptionalID
A unique identifier to enable programmatic references to the control.
propertyname
The name of the property.
propertyvalue
The value to assign to propertyname.

Example

The following code fragment inserts a TextBox Web Control and sets its maxlength property to 55.

<ASP:TextBox id="MyTextBox" maxlength="55" runat="server" />

Supported Types

You can declaratively set all of the standard primitive datatypes directly. You can also specify properties represented using an enumeration (where ASP+ will treat the attribute value of the control as the enumeration value name).

Supported Property Data Types
String Integer Double
Byte Char Boolean
DateTime TimeSpan Decimal
Variant Currency  
Note   You can also specifiy properties represented using enumerators. The parser will treat the attibute value of the control as the enumerator value name.

To set properties on member objects, see "Complex Property Syntax" below.

Subproperty Syntax

Custom server controls may have properties that are objects, and those objects may in turn have their own properties. To specify properties for objects that are themselves properties, use a name/value pair where subproperties are identified by a hyphen:

<tagprefix:tagname propertyname-subpropertyname="subpropertyvalue"
   runat=server />

Parameters

tagprefix
An alias for the fully qualified namespace of the control. The alias for Web Controls is asp. Aliases for user-authored controls are declared with the @ Register Directive.
tagname
The name of the class that encapsulates the control.
propertyname
The name of the property that contains properties to be defined.
subpropertyname
The name of the property being defined.
propertyvalue
The value to assign to subpropertyname.

Example

<ASP:Label font-name="Arial" font-size="14" runat="server">
   ...some literal text...
</ASP:Label>

Server Control Event Binding Syntax

Event bindings on server controls are specified using declarative attribute name/value pairs, where the attribute name represents the control’s event name and the value represents the method on the page that should be called when the event is fired.

<tagprefix:tagname EventName=EventHandlerMethodName” runat="server" />

Parameters

tagprefix
An alias for the fully qualified namespace of the control. The alias for Web Controls is asp. Aliases for user-authored controls are declared with the @ Register Directive.
tagname
The name of the class that encapsulates the control.
EventName
The event name of the control.
EventHandlerMethodName
The name of the method that will handle EventName.

Remarks

At runtime, ASP+ will dynamically configure the appropriate (type-safe) NGWS delegate object between the control event adder method and the target method. The target method can be defined either declaratively within a <script runat=server></script> block or in the page’s superclass.

Example

The following code fragment declares MyButton_Click as an event handler for the button's OnClick event:

<html>
   <script runat=server>
      Sub MyButton_Click (Sender as Object, Evt as EventArgs)
         ‘Do something when someone clicks the button
      End Sub
   </script>
   <body>
      <form action="default.aspx" method="post" runat=server>
         <ASP:Button text="Hello" OnClick="MyButton_Click" runat=server/>
      </form>
   </body>
</html>

Server Control Inline Template Syntax

As a control developer, you can include template properties in the design of custom server controls to separate control behavior from appearance. Control consumers (page developers) can use those template properties to customize the appearance of server controls on their pages.

< tagprefix:tagname [id=”OptionalName] [attribute=value ...] runat=server/>
   <template name="templatepropertyname">
      inline template values
   </template>
</ tagprefix:tagname >

Parameters

tagprefix
An alias for the fully-qualified namespace of the control. The alias for Web Controls is ASP. Aliases for user-authored controls are declared with the @ Register Directive.
tagname
The name of the class that encapsulates the control.
OptionalName
A unique identifier to enable programmatic references to the control.
attribute
The name(s) of control properties or event bindings to be assigned to the control.
value
The value of each attribute.
templatepropertyname
The name of the server control template property.

The Web Forms page framework interprets this syntax at parse time to dynamically bind an appropriate ITemplate instance to the template property of the parent server control.

Example

The following code fragment shows how a page developer could customize the header and each cell of a Repeater control:

<ASP:Repeater id="myrepeater" runat=server>
   <template name="headertemplate">
      Header content goes here...
   </template>
   <template name="itemtemplate">
      Cell content goes here...
   </template>
</ASP:Repeater>

See also

ASP+ Page Syntax