Wrox Professional Web Parts and Custom Controls with ASP.NET 2.0 phần 8 ppt

298 Chapter 9 Private _ChildControls As ArrayList Public Property ChildControls() As ArrayList Get Return _ChildControls End Get Set(ByVal value As ArrayList) _ChildControls = value End Set End Property In C#: private ArrayList _ChildControls; public ArrayList ChildControls { get { return _ChildControls; } set { _ChildControls = value; } } On the class declaration, you must specify this “repository” property as the default property for your control, as this Visual Basic 2005 code does: <ParseChildren(True, “ChildControls”), _ ToolboxData(“<{0}:BookInfo runat=server></{0}:BookInfo>”)> _ Public Class BookInfo In C#: [ParseChildren(true, “ChildControls”)] [ToolboxData(“<{0}:BookInfo runat=server></{0}:BookInfo>”)] public class BookInfo In your Render method, you could iterate through the ChildControls collection, having each control ren- der itself by calling its RenderControl method. In Visual Basic 2005, the code looks like this: Protected Overrides Sub Render(ByVal writer As System.Web.UI.HtmlTextWriter) For Each ctl As Control In Me.ChildControls ctl.RenderControl(writer) Next End Sub In C#: protected override void Render(System.Web.UI.HtmlTextWriter writer) { foreach(Control ctl in this.ChildControls) 15_57860x ch09.qxd 10/4/05 9:22 PM Page 298 299 Adding Advanced Functionality { ctl.RenderControl(writer); } } While this provides a simple mechanism for generating constituent controls, it doesn’t really address the issue of handling multiple properties with complex datatypes. Instead, it creates a single property to hold all complex objects. It is better to have a dedicated property for each object. It is also better to have some mechanism that allows you to manage the processing of the tags nested in the custom control rather than just blindly rendering them. Handling Complex Content The next step is to handle multiple complex properties on a single control and provide a mechanism for managing those elements as they are added. As the example for this section, the BookInfo control is extended to support the following nested tags: ❑ The Author tag with a first name and a last name ❑ The Titles tag with the main title and the subtitle ❑ An ASP.NET Label tag that will be added to the Controls collection of the BookInfo tag and ren- dered with the control ❑ A Description tag containing a description of the book As a result, the BookInfo tag with all of these nested elements looks like this: <cc1:BookInfo ID=”BookInfo1” runat=”server” > <cc1:Author runat=”server” FirstName=”Peter” LastName=”Vogel” /> <cc1:Titles runat=”server” MainTitle=”Custom Controls and Web Parts” SubTitle=”ASP.NET 2.0” /> <asp:Label ID=”Label1” runat=”server” Text=”Your book”></asp:Label> <cc1:Description runat=”server”> Comprehensive coverage of ASP.NET 2.0 custom controls and web parts. </cc1:Description> </cc1:BookInfo> This design adds a new type of tag to the mix: the Description element, which has no attributes but, instead, has content nested inside the element’s open and close tags. To handle multiple nested tags with complex datatypes and nested controls—and do it reliably—you must override your control’s AddParsedSubObject method. The AddParsedSubObject method is called each time a new nested tag is processed. The method is passed the object created from the tag being To use this mechanism, it’s essential that all the controls have prefixes that tie to the Register tag in the page that associates the tag with an assembly and namespace combination that holds the corresponding custom control. The controls must also have the runat attribute. 15_57860x ch09.qxd 10/4/05 9:22 PM Page 299 300 Chapter 9 processed. It is your responsibility, as the control developer, both to define the classes to support those tags and to add the code to the AddParsedSubObject method to handle the objects correctly. If, during processing no object is found in the assembly for any tag, the AddParsedSubObject method is passed an ASP.NET LiteralControl containing the text for the tag. Before looking at the AddParsedSubObject method, then, you need to add the code to define the Author, Titles, Label, and Description objects to the BookInfo control. To simplify the example, I’ll just support the Titles and Description tags in the sample code. To handle the Titles element, you need to define a Titles class so that ASP.NET can create a Titles object from the data in the Titles element. The Titles class has two properties: MainTitle and SubTitle, corresponding to the attributes on the Title element. In Visual Basic 2005, the Title class looks like this: Public Class Titles Private _MainTitle As String Private _SubTitle As String Public Property Main() As String Get Return _MainTitle End Get Set(ByVal value As String) _MainTitle = value End Set End Property Public Property SubTitle() As String Get Return _SubTitle End Get Set(ByVal value As String) _SubTitle = value End Set End Property End Class In C#: public class Titles { private string _MainTitle; private string _SubTitle; public string Main { get { return _MainTitle; } set { _MainTitle = value; } 15_57860x ch09.qxd 10/4/05 9:22 PM Page 300 301 Adding Advanced Functionality } public string SubTitle { get { return _SubTitle; } set { _SubTitle = value; } } } Because there will be only one Titles element for the BookInfo control, it isn’t necessary to create a collection property (as was done for the Authors element). However, you will want to access the values from the Titles tag from within your custom control. A simple solution is to create a MainTitle and SubTitle property and set those properties from the corresponding properties in the Titles object as the Titles objects are processed in the AddParsedSubObject. You can then read those properties from the code in your custom control. In Visual Basic 2005, the properties to add to the BookInfo custom control look like this: Private _MainTitle As String Private _SubTitle As String Public Property MainTitle() As String Get Return _MainTitle End Get Set(ByVal value As String) _MainTitle = value End Set End Property Public Property SubTitle() As String Get Return _SubTitle End Get Set(ByVal value As String) _SubTitle = value End Set End Property In C#: private string _MainTitle; private string _SubTitle; public string MainTitle { get { 15_57860x ch09.qxd 10/4/05 9:22 PM Page 301 302 Chapter 9 return _MainTitle; } set { _MainTitle = value; } } public string SubTitle { get { return _SubTitle; } set { _SubTitle = value; } } To handle the Description element with its literal content (an element with text between its open and close tags) all that’s necessary is to create a class that inherits from the ASP.NET Literal control. This is the Visual Basic 2005 definition of that object: Public Class Description Inherits System.Web.UI.WebControls.Literal End Class In C#: public class Description : System.Web.UI.WebControls.Literal { } You also need to add a Description property to the BookInfo that can be set from the Description tag. In Visual Basic 2005 the property looks like this: Private _Description As String Public Property Description() As String Get Return _Description End Get Set(ByVal value As String) _Description = value End Set End Property In C#: private string _Description; public string Description 15_57860x ch09.qxd 10/4/05 9:22 PM Page 302 303 Adding Advanced Functionality { get { return _Description; } set { _Description = value; } } With all the groundwork laid, it’s time to override the BookInfo’s AddParsedSubObject method and add the code to handle these objects. ASP.NET processes each tag, creates the corresponding object, and passes the object to the AddParsedSubObject method. In the AddParsedSubObject, you must determine the kind of object being passed and take the appropriate action. For the BookInfo object those actions are: ❑ For an Author element: An Author object (defined in the previous section) is passed to the AddParsedSubObject method. That object can be added to the Authors property (also defined in the previous section). If the _Authors ArrayList that this method uses hasn’t been created, it should be created at this point. ❑ For a Titles element: A Titles object is passed to the method. The values for the Titles object’s MainTitle and SubTitle properties can be used to set the corresponding properties on the BookInfo object. ❑ For the Label element: The Label object passed to the method just needs to be added to the BookInfo’s Controls collection. ❑ For the Description element: The Text property (inherited from the Literal control) of the Description object can be used to set the BookInfo’s Description property. Any tags that don’t have a corresponding object are passed to the AddParsedSubObject method as a LiteralControl object. You can then retrieve the tag’s text from the LiteralControl’s Text property and parse the tag out. In Visual Basic 2005, the AddParsedSubObject method looks like this: Protected Overrides Sub AddParsedSubObject(ByVal obj As Object) If obj.GetType.Equals(GetType(Description)) Then Me.Description = CType(obj, Description).Text End If If obj.GetType.Equals(GetType(Author)) Then If _Authors Is Nothing Then _Authors = New ArrayList(2) End If Me.Authors.Add(obj) End If If obj.GetType.Equals(GetType(Titles)) Then Me.MainTitle = CType(obj, Titles).MainTitle Me.SubTitle = CType(obj, Titles).SubTitle 15_57860x ch09.qxd 10/4/05 9:22 PM Page 303 304 Chapter 9 End If If obj.GetType.Equals(GetType(System.Web.UI.WebControls.Label)) Then Me.Controls.Add(obj) End If End Sub In C#: protected override void AddParsedSubObject(object obj) { if (obj is Author) { if(_Authors == null) { _Authors = new ArrayList(2); } this.Authors.Add(obj); } if (obj is Titles) { this.MainTitle = ((Titles) obj).Main; this.SubTitle = ((Titles) obj).Subtitle; } if (obj is Description) { Description ds; ds = (Description) obj; this.Description = ds.Text; } if (obj is Label) { this.Controls.Add((System.Web.UI.WebControls.WebControl) obj); } } To have the AddParsedSubObject called, the ParseChildren attribute on the BookInfo object must have its first parameter set to False, as in this Visual Basic 2005 code: <ParseChildren(False), _ ToolboxData(“<{0}:BookInfo runat=server></{0}:BookInfo>”)> _ Public Class BookInfo In C#: [ParseChildren(false)] [ToolboxData(“<{0}:BookInfo runat=server></{0}:BookInfo>”)] public class BookInfo 15_57860x ch09.qxd 10/4/05 9:22 PM Page 304 While not a good practice, you can include plain text (text outside of any tag) inside your custom control’s open and close tags, as in this example: <cc1:BookInfo ID=”BookInfo1” runat=”server”> <cc1:Author runat=”server” FirstName=”Peter” LastName=”Vogel”/> A comprehensive guide to custom control and web parts. <asp:Label ID=”Label1” runat=”server” Text=”Your book”></asp:Label> </cc1:BookInfo > The text (including all whitespace) from the end of the Author tag to the start of the Label tag is passed to the AddParsedSubObject method as a LiteralControl. The text can be retrieved from the LiteralControl’s Text property. However, if all you want is to have the text rendered as a part of the custom control’s display, you just need to add the LiteralControl to your custom control’s Controls collection, as this Visual Basic 2005 code does: If obj.GetType.Equals(GetType(LiteralControl)) Then Me.Controls.Add(obj) End If In C#: if (obj is LiteralControl) { this.Controls.Add((System.Web.UI.WebControls.WebControl) obj) } Controlling Complex Content While simply overriding the AddParsedSubObject method will allow you to process complex content, the process, as described so far, has several deficiencies: ❑ No editing is performed to ensure that only valid tags are present. ❑ It’s not possible to manage the conversion of the nested tags to elements. ❑ HTML encoding (for example, replacing > with &gt;) is ignored. ❑ Whitespace between the end of one tag and the start of another is treated as literal text and passed to the AddParsedSubObject method. ❑ All nested elements must be assigned the appropriate prefix and the runat attribute. By using a control builder class in conjunction with your custom control, you can take more control over the process of processing tags within your custom control. As ASP.NET processes the tags inside a control, a control builder is called as part of the process before the resulting objects are passed to the AddParsedSubObject method. By tailoring properties on the control builder you can, for instance, eliminate unnecessary whitespace being passed to your AddParsedSubObject method and control the type of object created from the nested tags. Every ASP.NET control automatically invokes one of the default control builders that comes with ASP.NET or invokes a specialized control builder. 305 Adding Advanced Functionality 15_57860x ch09.qxd 10/4/05 9:22 PM Page 305 306 Chapter 9 A control builder is a class that inherits from the System.Web.UI.ControlBuilder class, as in this Visual Basic 2005 example: Public Class BookBuilder Inherits System.Web.UI.ControlBuilder End Class In C#: public class BookBuilder : System.Web.UI.ControlBuilder { } The control builder is tied to a custom control through the ControlBuilder attribute on the custom control’s Class declaration. This attribute must be passed the type of the control builder to be used with the custom control. In Visual Basic 2005, the class declaration to tie the BookBuilder control builder to the BookInfo custom control looks like this: <ControlBuilder(GetType(BookBuilder)), _ ToolboxData(“<{0}:BookInfo runat=server></{0}:BookInfo>”)> _ Public Class BookInfo In C#: [ControlBuilder(typeof(BookBuilder))] [ToolboxData(“<{0}:BookInfo runat=server></{0}:BookInfo>”)] public class BookInfo You can use the control builder to simplify processing for your AddParsedSubObject method. For instance, by default, the control builder returns all the whitespace from the end of one tag to the start of another as a LiteralControl. In most cases, you won’t want to deal with that text in your AddParsedSubObject method. You can suppress whitespace by overriding the control builder’s AllowWhitespaceLiteral property and returning False. You can also cause all the HTML literals to be decoded prior to being passed to the AddParsedSubObject method by overriding the HTMLDecodeLiterals method and returning True. While overriding the AllowWhitespaceLiterals property prevents any blank whitespace from being passed to the AddParsedSubObject method, it doesn’t prevent text that’s outside of any tag from being passed to the method. Overriding the control builder’s AppendLiteralString method prevents literal text from being passed to AddParsedSubObject. This Visual Basic 2005 example causes HTML to be decoded and prevents both whitespace and literal text from being passed to the custom control’s AddParsedSubObject method: Public Class BookBuilder Inherits System.Web.UI.ControlBuilder Overrides Public Function HtmlDecodeLiterals() As Boolean Return True End Function Public Overrides Function AllowWhitespaceLiterals() As Boolean 15_57860x ch09.qxd 10/4/05 9:22 PM Page 306 307 Adding Advanced Functionality Return False End Function Public Overrides Sub AppendLiteralString(ByVal s As String) End Sub End Class In C#: public class BookBuilder : System.Web.UI.ControlBuilder { public override bool HtmlDecodeLiterals() { return true; } public override bool AllowWhitespaceLiterals() { return false; } public override void AppendLiteralString(string s) { } } You can also use the control builder’s GetChildControlType method to simplify the tags used inside your custom control or to have different tags processed as the same object. The GetChildControlType method is called once for each tag nested inside your custom control tag and returns the type of object to be used with the tag. The GetChildControlType method is passed the name of the tag and an IDictionary object holding all of the attributes on the tag. This allows you to tailor the objects used with a particular tag, eliminating the need to fully qualify the tag nested inside the custom control. This method also provides a location where you can test for the content found nested in the control and decide what to do with it. For instance, by using the control builder’s GetChildControlType, it is possible to rewrite the nested controls for the BookInfo tag to eliminate the prefixes and runat attributes, as in this example: <cc1:BookInfo ID=”BookInfo1” runat=”server” > <Author FirstName=”Peter” LastName=”Vogel” /> <Titles MainTitle=”Custom Controls and Web Parts” SubTitle=”ASP.NET 2.0” /> <asp:Label ID=”Label1” runat=”server” Text=”Your book”></asp:Label> </cc1:BookInfo> As with saving property values as content in the control, you may get spurious errors from Visual Studio .NET saying that the schema doesn’t support these nested tags. You can ignore these errors. In the GetChildControlType method you can examine each tag name and return the object type to be used with the tag (this is the object type that will be passed to the custom control’s AddParsedSubObject method). Without this processing, all of the non-ASP.NET tags in the previous example would be treated as literal content because they don’t have a prefix or the runat attribute. 15_57860x ch09.qxd 10/4/05 9:22 PM Page 307 [...]... consumer’s method: Implements WebControls.WebParts.IWebPartField Sub FieldValue(ByVal fld As WebControls.WebParts.FieldCallback) _ Implements WebControls.WebParts.IWebPartField.GetFieldValue fld.Invoke(Me.BookData) End Sub ReadOnly Property BookData() As String Get Return strBookTitle End Get End Property In C#: void WebControls.WebParts.IWebPartField.FieldValue( WebControls.WebParts.FieldCallback fld)... _ Public Function IWebPartFieldProvider() As WebControls.WebParts.IWebPartField Return Me End Function And in C#: [WebControls.WebParts.WebParts.ConnectionProvider(“Provides IWebPartField”)] public WebControls.WebParts.IWebPartField IWebPartFieldProvider() { return this; } An IWebPartField Consumer Code in the consumer has to accomplish two tasks:... Basic 2005 example shows the connection point for the IBookInfo interface: Public Function IBookInfoProvider() As IBookInfo Return Me End Function In C#, the code looks like this: 326 Communicating Between Web Parts [WebControls.WebParts.WebParts.ConnectionProvider(“Provides ISBN”, “ISBNProvider”)] public IBookInfo... property and call the methods as this Visual Basic 2005 code does: _ Public Sub IBookInfoConsumer(ByRef bk As IBookInfo) Dim strProviderValue As String Dim bolSuccess As Boolean strProviderValue = “10345329” bk.ISBN = strProviderValue bk.UpdateCache(True) bolSuccess = bk.SortData(“Desc”) End Sub In C#: [WebControls.WebParts.WebParts.ConnectionConsumer(“IBookInfo... Web Parts that the Web Part is providing data to This block has the title “Providers” and the text Web Parts that the current Web Part gets information from:” ❑ One block is for Web Parts that it is consuming data from The Consumer block has the title “Consumers:” and the text Web Parts that the current Web Part sends information to:” 323 Chapter 10 Within the blocks is a list of parts for that category... through the methods and properties in the interface This Visual Basic 2005 code accesses the provider through the IBookInfo interface to retrieve the value of the ISBN property: _ Public Sub IBookInfoConsumer(ByVal bk As IBookInfo) Dim strISBN As String strISBN = bk.ISBN End Sub In C#: [WebControls.WebParts.WebParts.ConnectionConsumer(“IBookInfo... create a provider Web Part and a consumer Web Part Creating a Provider Web Part Let’s begin by walking through the process required to create a Web Part that can send data to other Web Parts There are three steps to creating a Web Part that can provide data to another Web Part: 1 2 Define an interface that specifies what data is to be passed between the Web Parts 3 Write the routine that handles the connection... connectable Web Parts, you should first see how to connect Web Parts on a page Let’s assume that two parts already exist: Chapter 10 ❑ A book detail display Web Part (BookDetail) ❑ A Web Part that lists books (BookList) A user can select a book from the list and have the detail Web Part display information about the book Setting up the Page To create a page where users can connect Web Parts, you first... — the Web Part framework comes with four predefined interfaces: IWebPartField, IWebPartRow, IWebPartTable, and IWebPartParameters The interfaces provide mechanisms that allow the consumers and providers to find out information about each other and tailor their activity based on that information As the names of the interfaces imply, IWebPartField is intended to be used to pass a single value, IWebPartRow... the GetChildControlType includes any prefix used with the control 3 08 Adding Advanced Functionality As part of building a custom control, additional control builders will be called to handle building the custom control’s constituent controls The builders for these constituent controls will either be one of the default builders that come with ASP.NET or a custom builder assigned to the control by the control’s . used with the control. 3 08 Chapter 9 15_5 786 0x ch09.qxd 10/ 4 /05 9 :22 PM Page 3 08 As part of building a custom control, additional control builders will be called to handle building the custom. /> <Titles MainTitle= Custom Controls and Web Parts SubTitle= ASP. NET 2. 0 /> < ;asp: Label ID=”Label1” runat=”server” Text=”Your book”>< /asp: Label> </cc1:BookInfo> As with saving property. C#: protected override void Render(System .Web. UI.HtmlTextWriter writer) { foreach(Control ctl in this.ChildControls) 15_5 786 0x ch09.qxd 10/ 4 /05 9 :22 PM Page 29 8 29 9 Adding Advanced Functionality { ctl.RenderControl(writer); } } While