home *** CD-ROM | disk | FTP | other *** search
/ io Programmo 40 / IOPROG_40.ISO / SOFT / NETFrameworkSDK.exe / comsdk.cab / samples.exe / QuickStart / aspplus / doc / webpagelets.aspx < prev    next >
Encoding:
Text File  |  2000-06-08  |  8.8 KB  |  188 lines
  1.  
  2. <%@ Register TagPrefix="Acme" TagName="SourceRef" Src="/quickstart/util/SrcRef.aspx"%>
  3.  
  4. <!-- #include virtual="/quickstart/aspplus/include/header.inc" -->
  5.  
  6. <h4>Web Forms Pagelet Controls</h4>
  7. <p>
  8.  
  9. <!-- #include virtual="/quickstart/aspplus/include/wftoc4-2.inc" -->
  10. <p>
  11. <hr>
  12.  
  13.  
  14. <!--BEGIN SECTION-->
  15. <a name="intro">
  16. <span class="subhead">Introduction to Pagelets</span>
  17. <p>
  18. In addition to the built-in server controls provided by ASP+, you can easily define your own controls using the same programming 
  19. techniques you've already learned for writing Web Forms.  In fact, with just a few modifications, almost any Web Form
  20. can be re-used in another page as a server control (notice that tha base System.Web.UI.Page class inherits directly from 
  21. System.Web.UI.Control).  A Web Form used as a server control is named a <b>Pagelet</b>, 
  22. for short.  As a matter of convention, we use the <b>.aspc</b> extension to indicate such controls.  This ensures that the Pagelet's file cannot
  23. be executed as a standalone Web Form, if we so desire (we'll see a little later how there are a few, albiet important, differences between 
  24. a Pagelet and a Web Form).  Pagelets are included into another Web Form using a <b>Register</b>  directive:
  25.  
  26. <div class="code"><pre>
  27. <%@ Register TagPrefix="Acme" TagName="Message" Src="pagelet1.aspc" %>
  28. </pre></div>
  29.  
  30. <p>
  31. The TagPrefix determines a unique namespace for the Pagelet (so that multiple Pagelets with the same name can be differentiated from 
  32. each other).  The TagName is the unique name for the Pagelet (you can choose any name).  The Src attribute is the virtual path to the 
  33. Pagelet, for example "MyPagelet.aspc" or "/MyApp/Include/MyPagelet.aspc".  After registering the Pagelet, you may place the Pagelet 
  34. tag in the Web Form just as you would an ordinary server control (including the runat="server" attribute):
  35. <p>
  36.  
  37. <div class="code"><pre>
  38. <Acme:Message runat="server"/>
  39. </pre></div>
  40.  
  41. <p>
  42. The following example shows a Pagelet imported into another Web Form. Note that the Pagelet in this case is just a simple static file:
  43. <p>
  44.  
  45. <Acme:SourceRef 
  46.   RunSample="/quickstart/aspplus/samples/webforms/pagelets/Pagelet1.aspx" 
  47.   ViewSource="/quickstart/aspplus/samples/webforms/pagelets/Pagelet1.src"
  48.   Icon="/quickstart/aspplus/images/pagelet1.gif"
  49.   Caption="Pagelet1.aspx"
  50.   runat="server" />
  51.  
  52.  
  53. <!--BEGIN SECTION-->
  54. <br>
  55. <a name="properties">
  56. <br>
  57. <span class="subhead">Exposing Pagelet Properties</span>
  58. <p>
  59.  
  60. When we treat a Web Form as a control, the public fields and methods of that Web Form are promoted to public properties (i.e. tag 
  61. attributes) and methods of the control as well.  The following example shows an extension of the previous Pagelet example that adds 
  62. two public String fields.  Notice that these fields can be set either declaratively or programmatically in the containing page.
  63. <p>
  64.  
  65. <Acme:SourceRef 
  66.   RunSample="/quickstart/aspplus/samples/webforms/pagelets/Pagelet2.aspx" 
  67.   ViewSource="/quickstart/aspplus/samples/webforms/pagelets/Pagelet2.src"
  68.   Icon="/quickstart/aspplus/images/pagelet2.gif"
  69.   Caption="Pagelet2.aspx"
  70.   runat="server" />
  71.  
  72. <p>
  73. In addition to promoting public fields to control properties, the property syntax may be used.  Property syntax has the advantage 
  74. of being able to execute code when properties are set or retrieved.  In this next example, we've implemented an Address Pagelet that wraps the "Text"
  75. properties of TextBox controls within it.  The benefit of doing this is that we inherit the automatic state management of the TextBox control 
  76. for free!
  77. <p>
  78. Notice that we've placed two Address Pagelets on the containing Web Form, and differentiated between them by setting the 
  79. "caption" property to "Billing Address" and "Shipping Address" respectively.  The real power of Pagelets is in this type of reusability.
  80. <p>
  81.  
  82. <Acme:SourceRef 
  83.   RunSample="/quickstart/aspplus/samples/webforms/pagelets/Pagelet3.aspx" 
  84.   ViewSource="/quickstart/aspplus/samples/webforms/pagelets/Pagelet3.src"
  85.   Icon="/quickstart/aspplus/images/pagelet3.gif"
  86.   Caption="Pagelet3.aspx"
  87.   runat="server" />
  88.  
  89. <p>
  90. Another useful Pagelet is a Login control for collecting usernames and passwords:
  91. <p>
  92.  
  93. <Acme:SourceRef 
  94.   RunSample="/quickstart/aspplus/samples/webforms/pagelets/Pagelet4.aspx" 
  95.   ViewSource="/quickstart/aspplus/samples/webforms/pagelets/Pagelet4.src"
  96.   Icon="/quickstart/aspplus/images/pagelet4.gif"
  97.   Caption="Pagelet4.aspx"
  98.   runat="server" />
  99.  
  100. <p>
  101. Here we've added form validation controls to the Login Pagelet.
  102. <p>
  103.  
  104. <Acme:SourceRef 
  105.   RunSample="/quickstart/aspplus/samples/webforms/pagelets/Pagelet5.aspx" 
  106.   ViewSource="/quickstart/aspplus/samples/webforms/pagelets/Pagelet5.src"
  107.   Icon="/quickstart/aspplus/images/pagelet5.gif"
  108.   Caption="Pagelet5.aspx"
  109.   runat="server" />
  110.  
  111. <!--BEGIN SECTION-->
  112. <br>
  113. <a name="events">
  114. <br>
  115. <span class="subhead">Encapsulating Events in a Pagelet</span>
  116. <p>
  117.  
  118. Pagelets participate in the complete execution lifecycle of the request, much the way ordinary server controls do.  This means that
  119. a Pagelet can handle its own events, encapsulating some of the page logic from the containing Web Form.  In this next example,
  120. we've implemented a product listing Pagelet that internally handles its own post-backs.  One thing to notice is that the Pagelet itself
  121. has no wrapping <form runat="server"> control.  Because only one form control may be present on a page (ASP+ does not 
  122. allow nested server forms), we leave it to the containing Web Form to define this for us.
  123. <p>
  124.  
  125. <Acme:SourceRef 
  126.   RunSample="/quickstart/aspplus/samples/webforms/pagelets/Pagelet6.aspx" 
  127.   ViewSource="/quickstart/aspplus/samples/webforms/pagelets/Pagelet6.src"
  128.   Icon="/quickstart/aspplus/images/pagelet6.gif"
  129.   Caption="Pagelet6.aspx"
  130.   runat="server" />
  131.  
  132.  
  133. <!--BEGIN SECTION-->
  134. <br>
  135. <a name="program">
  136. <br>
  137. <span class="subhead">Creating Pagelets Programmatically</span>
  138. <p>
  139.  
  140. Just as ordinary server controls can be created programmatically, so too can Pagelets.  We use the Page's <b>LoadControl</b> method to
  141. load the Pagelet, passing the virtual path to the Pagelet's source file:
  142.  
  143. <div class="code"><pre>
  144. Control c1 = LoadControl("pagelet7.aspc");
  145. ((pagelet7_aspc)c1).Category = "business";
  146. Page.Controls.Add(c1);
  147. </pre></div>
  148.  
  149. The type of the Pagelet is determined by the ASP+ runtime, following the convention <i>filename</i>_<i>extension</i>.  
  150. For example, a Pagelet saved as filename "pagelet7.aspc" is assigned the strong type "pagelet7_aspc".  Because the LoadControl 
  151. method returns a type of System.Web.UI.Control, we need to cast to the appropriate strong type in order to set individual properties
  152. of the Pagelet control.  Finally, the Pagelet is added to the base Page's Controls collection.
  153. <p>
  154.  
  155. <Acme:SourceRef 
  156.   RunSample="/quickstart/aspplus/samples/webforms/pagelets/Pagelet7.aspx" 
  157.   ViewSource="/quickstart/aspplus/samples/webforms/pagelets/Pagelet7.src"
  158.   Icon="/quickstart/aspplus/images/pagelet7.gif"
  159.   Caption="Pagelet7.aspx"
  160.   runat="server" />
  161.  
  162. <p>
  163. <b>Important: </b>  The strong type for a Pagelet is available to the containing Web Form only if a Register directive is included for
  164. the Pagelet (even if there are no Pagelet tags actually declared).
  165.  
  166. <!--BEGIN SECTION-->
  167. <a name="endofsection">
  168.  
  169. <h4>Section Summary</h4>
  170. <ol>
  171. <li>Pagelets allow developers to easily define custom controls using the same programming techniques for writing Web Forms.
  172. <li>As a matter of convention, we use the <b>.aspc</b> extension to indicate such controls.  This ensures that the Pagelet's file cannot
  173. be executed as a standalone Web Form.
  174. <li>Pagelets are included into another Web Form using a <b>Register</b> directive, which specifies a TagPrefix, TagName, and Src location.
  175. <li>After registering the Pagelet, a Pagelet tag may be placed in a Web Form as an ordinary server control (including the runat="server" attribute).
  176. <li>The public fields, properties and methods of a Pagelet are promoted to public properties (i.e. tag attributes) and methods of the 
  177. control in the containing Web Form.
  178. <li>Pagelets participate in the complete execution lifecycle of every request and can handle their own events, encapsulating some of the 
  179. page logic from the containing Web Form.
  180. <li>Pagelets should not contain any form controls, but should instead rely on their containing Web Form to include one if necessary.
  181. <li>Pagelets may be created programmatically using the LoadControl method of the System.Web.UI.Page class.  The type of the Pagelet is 
  182. determined by the ASP+ runtime, following the convention <i>filename</i>_<i>extension</i>. 
  183. <li>The strong type for a Pagelet is available to the containing Web Form only if a Register directive is included for
  184. the Pagelet (even if there are no Pagelet tags actually declared).
  185. </ol>
  186. <p>
  187.  
  188. <!-- #include virtual="/quickstart/aspplus/include/footer.inc" -->