Professional ASP.NET 3.5 in C# and Visual Basic Part 89 doc

Evjen c17.tex V2 - 01/28/2008 2:58pm Page 837 Chapter 17: Portal Frameworks and Web Parts ❑ < ExportVerb > ❑ < HelpVerb > ❑ < MinimizeVerb > ❑ < RestoreVerb > Figure 17-18 The < asp:WebPartZone > control allows you to control these verbs by nesting the appropriate verb ele- ments within the < asp:WebPartZone > element itself. After these are in place, you can manipulate how these items appear in all the Web Parts that appear in the chosen Web Part Zone. For example, look at graying out the default Close link included with a Web Part. This is illustrated in Listing 17-11. Listing 17-11: Graying out the Close link in a Web Part < asp:WebPartZone ID="WebPartZone3" Runat="server" > < CloseVerb Enabled="False" / > < ZoneTemplate > < asp:Calendar ID="Calendar1" Runat="server" > Continued 837 Evjen c17.tex V2 - 01/28/2008 2:58pm Page 838 Chapter 17: Portal Frameworks and Web Parts < /asp:Calendar > < /ZoneTemplate > < /asp:WebPartZone > In this example, you can see that you simply need to set the Enabled attribute of the < CloseVerb > element to False in order to gray out the Close link in any of the generated Web Parts included in this Web Part Zone. If you construct the Web Part Zone in this manner, you achieve the results shown in Figure 17-19. Figure 17-19 If you do not want to gray out the Close link (or any other verb link contained within the Web Part), you must instead use the Visible attribute of the appropriate verb (see Listing 17-12). Listing 17-12: Removing the Close link in a Web Part < asp:WebPartZone ID="WebPartZone3" Runat="server" > < CloseVerb Visible="False" / > Continued 838 Evjen c17.tex V2 - 01/28/2008 2:58pm Page 839 Chapter 17: Portal Frameworks and Web Parts < ZoneTemplate > < asp:Calendar ID="Calendar1" Runat="server" > < /asp:Calendar > < /ZoneTemplate > < /asp:WebPartZone > Using the Visible attribute produces the screen shown in Figure 17-20. Figure 17-20 Verb elements provide another exciting feature: They give you the capability to use images that would appear next to the text of an item. Using images with the text makes the Web Parts appear more like the overall Windows environment. For instance, you can change the contents of WebPartZone3 again so that it now uses images with the text for the Close and Minimize links. This is illustrated in Listing 17-13. Listing 17-13: Using images for the Web Part verbs < asp:WebPartZone ID="WebPartZone3" Runat="server" > < CloseVerb ImageUrl="Images/CloseVerb.gif" / > Continued 839 Evjen c17.tex V2 - 01/28/2008 2:58pm Page 840 Chapter 17: Portal Frameworks and Web Parts < MinimizeVerb ImageUrl="Images/MinimizeVerb.gif" / > < ZoneTemplate > < asp:Calendar ID="Calendar1" Runat="server" > < /asp:Calendar > < /ZoneTemplate > < /asp:WebPartZone > To point to an image for the verb, use the ImageUrl attribute. This produces something similar to Figure 17-21, depending on the images you use. Figure 17-21 This chapter, thus far, has concentrated on creating completely customizable portal applications in a declarative manner using the capabilities provided by the ASP.NET Portal Framework. As with most aspects of ASP.NET, however, not only can you work with appearance and functionality in a declarative fashion, but you can also create the same constructs through server-side code. 840 Evjen c17.tex V2 - 01/28/2008 2:58pm Page 841 Chapter 17: Portal Frameworks and Web Parts Working with Classes in the Portal Framework The Portal Framework provides three main classes for dealing with the underlying framework presented in this chapter: WebPartManager , WebPartZone ,and WebPart . The WebPartManager class allows you to perform multiple operations in your server-side code. The following table shows a partial listing of some of the properties that this class provides. WebPartManager Class Properties Description Connections Provides a collection of all the connections between Web Parts contained on the page. DisplayMode Allows you to change the page’s display mode. Possible choices include CatalogDisplayMode , ConnectDisplayMode , DesignDisplayMode , EditDisplayMode ,and BrowseDisplayMode . SelectedWebPart Allows you to perform multiple operations on the selected Web Part. WebParts Provides a collection of all the Web Parts contained on the page. Zones Provides a collection of all the Web Part Zones contained on the page. Beyond the properties of the WebPartManager class, you also have an extensive list of available methods at your disposal. The following table outlines some of the available methods of the WebPartManager class. WebPartManager Class Methods Description AddWebPart Allows you to dynamically add new Web Parts to a particular zone on the page. ConnectWebParts AllowsyoutoconnecttwoWebPartstogether via a common property or value. DeleteWebPart Allows you to dynamically delete new Web Parts from a particular zone on the page. DisconnectWebParts Allows you to delete a connection between two Web Parts. MoveWebPart Allows you to move a Web Part from one zone to another, or allows you to change the index order in which Web Parts appear in a particular zone. Whereas the WebPartManager class allows you to manipulate the location, addition, and deletion of Web Parts that appear in the page as a whole, the WebPartZone class allows you to modify a single Web Part Zone on the page. The following table provides a list of some properties available to the WebPartZone class. 841 Evjen c17.tex V2 - 01/28/2008 2:58pm Page 842 Chapter 17: Portal Frameworks and Web Parts WebPartZone Class Properties Description AllowLayoutChange Takes a Boolean value and either enables or disables the Web Part Zone’s capability to accept or allow any changes in the Web Parts it contains. BackColor , BackImageUrl , BorderColor , BorderStyle , BorderWidth Enable you to modify the Web Part Zone’s general appearance. CloseVerb References the Close verb for a particular Web Part Zone from which you can then manipulate the verb’s Description , Enabled , ImageUrl , Text ,and Visible properties. ConnectVerb References a Web Part Zone’s Connect verb from which you can then manipulate the verb’s Description , Enabled , ImageUrl , Text ,and Visible properties. DragHighlightColor Takes a System.Color value that sets the color of the Web Part Zone’s border if focused when the moving of Web Parts is in operation. This also changes the color of the line that appears in the Web Part Zone specifying where to drop the Web Part. EditVerb References a Web Part Zone’s Edit verb from which you can then manipulate the verb’s Description , Enabled , ImageUrl , Text ,and Visible properties. EmptyZoneText Sets the text that is shown in the zone if a Web Part is not set in the zone. HeaderText Sets header text. Height Sets the height of the Web Part Zone. HelpVerb References a Web Part Zone’s Help verb from which you can then manipulate the verb’s Description , Enabled , ImageUrl , Text ,and Visible properties. MenuLabelStyle , MenuLabelText Enable you to modify the drop-down menu that appears when end users edit a Web Part. These properties let you apply an image, alter the text, or change the style of the menu. MinimizeVerb References a Web Part Zone’s Minimize verb from which you can then manipulate the verb’s Description , Enabled , ImageUrl , Text ,and Visible properties. LayoutOrientation Enables you to change the Web Part Zone’s orientation from horizontal to vertical or vice versa. RestoreVerb References a Web Part Zone’s Restore verb, from which you can then manipulate the verb’s Description , Enabled , ImageUrl , Text ,and Visible properties. 842 Evjen c17.tex V2 - 01/28/2008 2:58pm Page 843 Chapter 17: Portal Frameworks and Web Parts WebPartZone Class Properties Description VerbButtonType Enables you to change the button style. Choices include ButtonType.Button , ButtonType.Image ,or ButtonType.Link . WebParts Provides a collection of all the Web Parts contained within the zone. Width Sets the width of the Web Part Zone. You have a plethora of options to manipulate the look-and-feel of the Web Part Zone and the items contained therein. The final class is the WebPart class. This class enables you to manipulate specific Web Parts located on the page. The following table details some of the properties available in the WebPart class. WebPart Class Properties Description AllowClose Takes a Boolean value that specifies whether the Web Part can be closed and removed from the page. AllowEdit Takes a Boolean value that specifies whether the end user can edit the Web Part. AllowHide Takes a Boolean value that specifies whether the end user can hide the Web Part within the Web Part Zone. If the control is hidden, it is still in the zone, but invisible. AllowMinimize Takes a Boolean value that specifies whether the end user can collapse the Web Part. AllowZoneChange Takes a Boolean value that specifies whether the end user can move the Web Part from one zone to another. BackColor , BackImageUrl , BorderColor , BorderStyle , BorderWidth Enable you to modify the Web Part’s general appearance. ChromeState Specifies whether the Web Part chrome is in a normal state or is minimized. ChromeType Specifies the chrome type that the Web Part uses. Available options include BorderOnly , Default , None , TitleAndBorder ,and TitleOnly . Direction Specifies the direction of the text or items placed within the Web Part. Available options include LeftToRight , NotSet ,and RightToLeft .This property is ideal for dealing with Web Parts that contain Asian text that is read from right to left. 843 Evjen c17.tex V2 - 01/28/2008 2:58pm Page 844 Chapter 17: Portal Frameworks and Web Parts WebPart Class Properties Description HelpMode Specifies how the help items display when the end user clicks the Help verb. Available options include Modal , Modeless ,and Navigate . Modal displays the help items within a modal window if the end user’s browser supports modal windows. If not, a pop-up window displays. Modeless means that a pop-up window displays for every user. Navigate redirects the user to the appropriate help page (specified by the HelpUrl property) when he clicks on the Help verb. HelpUrl Used when the HelpMode is set to Navigate .Takesa String value that specifies the location of the page the end user is redirected to when he clicks on the Help verb. ScrollBars Applies scroll bars to the Web Part. Available values include Auto , Both , Horizontal , None ,and Vertical . Title Specifies the text for the Web Part’s title. Text appears in the title bar section. TitleIconImageUrl Enables you to apply an icon to appear next to the title by specifying to the icon image’s location as a String value of the property. TitleUrl Specifies the location to direct the end user when the Web Part’s title Web Part is clicked. When set, the title is converted to a link; when not set, the title appears as regular text. Zone Allows you to refer to the zone in which the Web Part is located. Creating Custom Web Parts When adding items to a page that utilizes the Portal Framework, you add the pre-existing ASP.NET Web server controls, user controls, or custom controls. In addition to these items, you can also build and incorporate custom Web Parts. Using the WebParts class, you can create your own custom Web Parts. Although similar to ASP.NET custom server control development, the creation of custom Web Parts adds some additional capabilities. Creating a class that inherits from the WebPart class instead of the Control class enables your control to use the new personalization features and to work with the larger Portal Framework, thereby allowing for the control to be closed, maximized, minimized, and more. To create a custom Web Part control, the first step is to create a project in Visual Studio 2008. From Visual Studio, choose File ➪NewProject.ThispopsopentheNewProject dialog. From this dialog, select ASP.NET Server Control. Name the project MyStateListBox and click OK to create the project. You are presented with a class that contains the basic framework for a typical ASP.NET server control. Ignore this framework; you are going to change it so that your class creates a custom Web Parts control instead of an ASP.NET custom server control. Listing 17-14 details the creation of a custom Web Part control. 844 Evjen c17.tex V2 - 01/28/2008 2:58pm Page 845 Chapter 17: Portal Frameworks and Web Parts Listing 17-14: Creating a custom Web Part control VB Imports System Imports System.Web Imports System.Web.UI.WebControls Imports System.Web.UI.WebControls.WebParts Namespace Wrox Public Class StateListBox Inherits WebPart Private _LabelStartText As String = " Enter State Name: " Dim StateInput As New TextBox Dim StateContents As New ListBox Public Sub New() Me.AllowClose = False End Sub < Personalizable(), WebBrowsable() > _ Public Property LabelStartText() As String Get Return _LabelStartText End Get Set(ByVal value As String) _LabelStartText = value End Set End Property Protected Overrides Sub CreateChildControls() Controls.Clear() Dim InstructionText As New Label InstructionText.BackColor = Drawing.Color.LightGray InstructionText.Font.Name = "Verdana" InstructionText.Font.Size = 10 InstructionText.Font.Bold = True InstructionText.Text = LabelStartText Me.Controls.Add(InstructionText) Dim LineBreak As New Literal LineBreak.Text = " < br / > " Me.Controls.Add(LineBreak) Me.Controls.Add(StateInput) Dim InputButton As New Button InputButton.Text = "Input State" AddHandler InputButton.Click, AddressOf Me.Button1_Click Me.Controls.Add(InputButton) Continued 845 Evjen c17.tex V2 - 01/28/2008 2:58pm Page 846 Chapter 17: Portal Frameworks and Web Parts Dim Spacer As New Literal Spacer.Text = " < p > " Me.Controls.Add(Spacer) Me.Controls.Add(StateContents) ChildControlsCreated = True End Sub Public Sub Button1_Click(ByVal sender As Object, ByVal e As EventArgs) StateContents.Items.Add(StateInput.Text) StateInput.Text = String.Empty StateInput.Focus() End Sub End Class End Namespace C# using System; using System.Web.UI.WebControls; using System.Web.UI.WebControls.WebParts; namespace Wrox { public class StateListBox : WebPart { private String _LabelStartText = " Enter State Name: "; readonly TextBox StateInput = new TextBox(); readonly ListBox StateContents = new ListBox(); public StateListBox() { AllowClose = false; } [Personalizable, WebBrowsable] public String LabelStartText { get { return _LabelStartText; } set { _LabelStartText = value; } } protected override void CreateChildControls() { Controls.Clear(); Label InstructionText = new Label(); InstructionText.BackColor = System.Drawing.Color.LightGray; InstructionText.Font.Name = "Verdana"; InstructionText.Font.Size = 10; InstructionText.Font.Bold = true; InstructionText.Text = LabelStartText; Continued 846 . Web Part Zone. For example, look at graying out the default Close link included with a Web Part. This is illustrated in Listing 17-11. Listing 17-11: Graying out the Close link in a Web Part < asp: WebPartZone. Runat="server" > Continued 837 Evjen c17.tex V2 - 01/28/2008 2 :58 pm Page 838 Chapter 17: Portal Frameworks and Web Parts < /asp: Calendar > < /ZoneTemplate > < /asp: WebPartZone > In this. Close link (or any other verb link contained within the Web Part) , you must instead use the Visible attribute of the appropriate verb (see Listing 17-12). Listing 17-12: Removing the Close link in