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!

Using Pagelet Controls

The following example shows how a pagelet can define a data input subform that can be used on several pages or in several places on the same page. This example incorporates the pagelet control twice on an ASP+ order page, once for billing information and once for shipping information.

First, a simple standalone ASP+ name and address input form page will be created that includes several TextBox and Button controls, then the page will be modified to become a pagelet control.

The order subform contains six TextBox controls, a Submit button, a Clear button, and a Label control within the <Form> and </End Form> tags. VBScript in the event procedure btnSubmit_Click executes when the buttons are clicked to verify that data has been entered in all the TextBoxes. Script in the btnClear_Click event clears all the text boxes. The form is directed to run at the server and to post back to itself. If any text boxes are not completed, the name of the missing data item is concatenated to a string that will be used in an error message when the form is submitted. If this page were used on an actual Web site to gather name and address information, code would probably be placed in the btnSubmit_Click event to update a database or take some other action.

<%@ Page Description="Information input page" %>

<html>
   <script language=VB runat=server>
      Sub btnSubmit_Click(ByVal sender As Object, ByVal e As Eventargs)
         Dim sName As String, sCompany As String, sStreet As String
         Dim sCity As String, sState As String, sZip As String
         Dim sMessage As String

         sName =Trim(txtName.Text)
         sCompany=Trim(txtCompany.Text) 
         sStreet=Trim(txtStreet.Text)
         sCity=Trim(txtCity.Text)
         sState=Trim(txtState.Text)
         sZip=Trim(txtZip.Text)

         ' If text box is blank, add to error msg string.
         If sName="" Then sMessage = sMessage & "Name, "
         If sCompany="" Then sMessage = sMessage & "Company, "
         If sStreet="" Then sMessage = sMessage & "Street, "
         If sCity="" Then sMessage = sMessage & "City, "
         If sState="" Then sMessage = sMessage & "State, "
         If sZip="" Then sMessage = sMessage & "Zip, "

         ' Trim trailing comma.
         if sMessage<>"" Then
            lblMsg1.Text="Please enter your " & Mid(sMessage, 1, Len(sMessage)-2)
         else
            lblMsg1.Text="Thank you, " & sName & " for your information."
            btnSubmit.Text="ReSubmit"
         end if
      End Sub

      Sub btnClear_Click(ByVal sender As Object, ByVal e As Eventargs)
         lblMsg1.Text=""
         txtName.Text=""
         txtCompany.Text=""
         txtStreet.Text=""
         txtCity.Text=""
         txtState.Text=""
         txtZip.Text=""
         btnSubmit.Text="Submit"
      end sub
   </script>

   <p><h4>Please fill out the form:<h4></p>

   <Form method="Post" action="address.aspx" runat=server>
      <table width="250" bgcolor="#FFFF99">
         <tr>
            <td Align="Right"><b>Name:</b></td>
            <td><Asp:Textbox id="txtName" runat=server/></td>
         </tr>
         <tr>
            <h4><td Align="Right"><b>Company:</b></td></h4>
            <td><Asp:Textbox id="txtCompany" runat=server/></td>
         </tr>
         <tr>
            <td Align="Right"><b>Street:</b></td>
            <td><Asp:Textbox id="txtStreet" runat=server/></td>
         </tr>
         <tr>
            <td Align="Right"><b>City:</b></td>
            <td><Asp:Textbox id="txtCity" runat=server/></td>
         </tr>
         <tr>
            <td Align="Right"><b>State:</b></td>
            <td><Asp:Textbox id="txtState" runat=server/></td>
         </tr>
         <tr>
            <td Align="Right"><b>Zip:</b></td>
            <td><Asp:Textbox id="txtZip" runat=server/></td>
         </tr>
      </table><br>

      <asp:button id="btnSubmit" Text="Submit" OnClick="btnSubmit_Click" runat=server/>
      <asp:button id="btnClear" Text="Clear" OnClick="btnClear_Click" runat=server/>

      <h4><asp:Label id="lblMsg1" runat=server/><h4>
   </form>
</html>

Before the existence of pagelet controls, if you wanted to put two of these data input forms on an ASP+ Web page, you would have to copy all the preceding code and paste it in two places on the containing page, then rename several text boxes to avoid name conflicts. A better solution is to convert the input subform code to a custom pagelet control and use it from any ASP+ page that needs the visual interface and functionality of a name and address input form.

To convert the page to a pagelet control, the <html> and <Form> tags are removed along with the button click events. These items are supplied by the page that uses the new control. After deleting the code and controls that are not needed, the ASP+ page looks like this:

<%@ Page Description="Address input control" %>

<html>
   <table width="250" bgcolor="#FFFF99">
      <tr>
         <td Align="Right"><b>Name:</b></td>
         <td><Asp:Textbox id="txtName" runat=server/></td>
         </tr>
         <tr>
            <h4><td Align="Right"><b>Company:</b></td></h4>
            <td><Asp:Textbox id="txtCompany" runat=server/></td>
         </tr>
         <tr>
            <td Align="Right"><b>Street:</b></td>
            <td><Asp:Textbox id="txtStreet" runat=server/></td>
         </tr>
         <tr>
            <td Align="Right"><b>City:</b></td>
            <td><Asp:Textbox id="txtCity" runat=server/></td>
         </tr>
         <tr>
            <td Align="Right"><b>State:</b></td>
            <td><Asp:Textbox id="txtState" runat=server/></td>
         </tr>
         <tr>
            <td Align="Right"><b>Zip:</b></td>
            <td><Asp:Textbox id="txtZip" runat=server/></td>
         </tr>
   </table>
</html>

If the file is named InputControl.aspc, all that is needed to use this control on another page is this declarative line on the calling page:

<%@ Register TagPrefix="InputControl" TagName="AddressInfo" src="inputcontrol.aspc" %>

and this tag where the sub-form should appear:

<InputControl:AddressInfo id="ShipAddress" runat=server />

At this stage, the Input control would appear on the page that incorporates it but it would not be able to actually do anything. More code must be added to the control and to the calling page to accept and verify input and perform some useful work. A means of accessing the values of the text boxes and a means of clearing the text boxes from the calling page must be added.

Here is the pagelet control with the additional code:

<%@ Page Description="Address input declarative control" %>

<html>
   <script language=vb runat=server>
      public property get pName() As String
         pName=txtName.Text
      end property
      
      public property let pName(sValue As String)
         txtName.Text=sValue
      end property

      public property get pCompany() As String
         pCompany=txtCompany.Text
      end property

      public property let pCompany(sValue As String)
         txtCompany.Text=sValue
      end property

      public property get pStreet() As String
         pStreet=txtStreet.Text
      end property

      public property let pStreet(sValue As String)
         txtStreet.Text=sValue
      end property

      public property get pCity() As String
         pCity=txtCity.Text
      end property

      public property let pCity(sValue As String)
         txtCity.Text=sValue
      end property

      public property get pState() As String
         pState=txtState.Text
      end property

      public property let pState(sValue As String)
         txtState.Text=sValue
      end property

      public property get pZip() As String
         pZip=txtZip.Text
      end property

      public property let pZip(sValue As String)
         txtZip.Text=sValue
      end property

      public property let pHeader(sValue As String)
         lblHeader.Text=sValue
      end property

      public sub ClearFields
         ' Clear all text boxes.
         txtName.Text=""
         txtCompany.Text=""
         txtStreet.Text=""
         txtCity.Text=""
         txtState.Text=""
         txtZip.Text=""
      End Sub
   </script>

   <h4><asp:Label id=lblHeader runat=server/></h4>
   <table width="250" bgcolor="#FFFF99">
      <tr>
         <td Align="Right"><b>Name:</b></td>
         <td><Asp:Textbox id="txtName" runat=server/></td>
      </tr>
      <tr>
         <h4><td Align="Right"><b>Company:</b></td></h4>
         <td><Asp:Textbox id="txtCompany" runat=server/></td>
      </tr>
      <tr>
         <td Align="Right"><b>Street:</b></td>
         <td><Asp:Textbox id="txtStreet" runat=server/></td>
      </tr>
      <tr>
         <td Align="Right"><b>City:</b></td>
         <td><Asp:Textbox id="txtCity" runat=server/></td>
      </tr>
      <tr>
         <td Align="Right"><b>State:</b></td>
         <td><Asp:Textbox id="txtState" runat=server/></td>
      </tr>
      <tr>
         <td Align="Right"><b>Zip:</b></td>
         <td><Asp:Textbox id="txtZip" runat=server/></td>
      </tr>
   </table>
</html>

Property Let and Property Get statements have been added to expose the values of the text boxes as properties of the control. The pHeader property has been added to provide a line of text above the control. Also, a public method named ClearFields has been added to clear the contents of all the text boxes with one external method call.

Here is an ASP+ page that uses two instances of the Input control, one for a billing address and one for a shipping address. The subprocedure Init, is used to set the heading (pHeader property) of each control instance. A different "id" is given to each instance of the control so that they can be addressed separately on the calling page.

<%@ Register TagPrefix="InputControl" TagName="AddressInfo" src="inputformcontrol.aspc"%>

<html>
   <script language=vbscript runat=server>
      Dim sBillName as String, sBillCompany as String, sBillStreet As String
      Dim sBillCity As String, sBillState As String, sBillZip As String
      Dim sShipName as String, sShipCompany as String, sShipStreet As String
      Dim sShipCity As String, sShipState As String, sShipZip As String
      Dim sMessage As String

      Overrides Sub Init()
         BillAddress.pHeader="Please enter your billing information:"
         ShipAddress.pHeader="Please enter your shipping information (if different):"
      End Sub

      Private Sub btnSubmit_Click(ByVal sender as Object, ByVal e As EventArgs)
         sBillName=Trim(BillAddress.pName)
         sBillCompany=Trim(BillAddress.pCompany)
         sBillStreet=Trim(BillAddress.pStreet)
         sBillCity=Trim(BillAddress.pCity)
         sBillState=Trim(BillAddress.pState)
         sBillZip=Trim(BillAddress.pZip)

         sShipName=Trim(ShipAddress.pName)
         sShipCompany=Trim(ShipAddress.pCompany)
         sShipStreet=Trim(ShipAddress.pStreet)
         sShipCity=Trim(ShipAddress.pCity)
         sShipState=Trim(ShipAddress.pState)
         sShipZip=Trim(ShipAddress.pZip)

         If sBillName="" Then sMessage = sMessage & "Billing Name, "
         If sBillCompany="" Then sMessage = sMessage & "Billing Company, "
         If sBillStreet="" Then sMessage = sMessage & "Billing Street, "
         If sBillCity="" Then sMessage = sMessage & "Billing City, "
         If sBillState="" Then sMessage = sMessage & "Billing State, "
         If sBillZip="" Then sMessage = sMessage & "Billing Zip, "

         If sMessage<>"" Then
            lblMessage.Text="Oops! Please enter your " & Mid(sMessage, 1, Len(sMessage)-2)
         Else
            lblMessage.Text="Thank you, " & sBillName & ", for your information."
            btnSubmit.Text="ReSubmit"      
            ' Code to update database goes here.
         End if
      end sub

      Private Sub btnClear_Click(ByVal sender as Object, ByVal e As EventArgs)
      ' Call method to clear all fields in BillAddress and ShipAddress controls.
         BillAddress.ClearFields
         ShipAddress.ClearFields
         ' Clear label control.
         lblMessage.Text=""
         btnSubmit.Text="Submit"
      end sub
   </script>

   <body>
      <form method="POST" action="AddressTest.aspx" runat=server>
      <InputControl:AddressInfo id=BillAddress runat=server/><br>
      <InputControl:AddressInfo id=ShipAddress runat=server/><br>
          <asp:button id=btnSubmit text="submit order" OnClick="btnSubmit_Click" runat=server/>
          <asp:button id=btnClear text="Clear All" OnClick="btnClear_Click" runat=server/><br>
          <h4><asp:label id="lblMessage" runat=server/></h4>
      </form>
   </body>
</html>