Wrox Professional Web Parts and Custom Controls with ASP.NET 2.0 phần 5 pptx

TitleBar, then all the verbs in your Verb menu display in the title bar as hyperlinks. Because the Verb menu always includes the Web Part default verbs (e.g., Close Minimize), setting WebPartVerbRenderMode to TitleBar can give you a very long title bar and a very wide Web Part. Finding out about Your Web Part There are many aspects of your Web Part that you won’t be able to determine at design time. For example, the developer that adds your Web Part to a page will set the Web Part’s name. Web Parts have a number of properties that let you determine what those settings are at run time. They are: ❑ DisplayTitle: The title as currently displayed on the page reflecting the value of the Title prop- erty plus any modification, changes, or personalizations. This property is read-only. ❑ Hidden: When True, indicates that the part is not visible in a WebPartZone when the page is being displayed in the browser. You can’t use the Visible property to suppress the display of a Web Part when the Web Part is in a WebPartZone. You can, however, use the Hidden property to suppress the Web Part’s display when the Web Part is in a WebPartZone (setting the Hidden property in a Web Part that’s not in a WebPartZone has no effect on the Web Part). Effectively, this property provides another state for a Web Part in addition to the closed, minimized, and browse states available through the Verb menu. A hidden custom control does not appear on the page, is not minimized (when a Web Part is hidden, the title bar for the custom control is not displayed, unlike a minimized control), and is not closed (the Web Part does not appear in the catalog for the page). When the page is viewed in one of the customization modes, the text “(Hidden)” appears in the title bar to indicate the part’s state. ❑ IsClosed: True when your Web Part is closed. ❑ IsShared, IsStandalone: If a WebPart is in a WebPartZone (that is, when a WebPart can be customized) then IsShared is True if the Web Part is visible to all the users of the page; IsStandalone is True when the Web Part is visible only to a single user. For instance, a Web Part added to a WebPartZone at design time has its IsShared property set to True and IsStandalone set to False because it is visible to all users. On the other hand, a Web Part that a user imported into the page as part of a user’s customizations will have its IsShared prop- erty set to False and IsStandalone set to True because it is visible only to the user who imported it. When a WebPart is not in a WebPartZone (that is, when it cannot be customized), IsStandalone is True and IsShared is False. ❑ IsStatic: True if the Web Part has been added to the page declaratively (that is, the Web Part’s tag was added to the page at design time rather than the Web Part being loaded dynamically at run time). ❑ SetPersonalizationDirty: If you make customization changes to the Web Part’s properties from your code, your changes may not be recognized by the personalization framework and, as a result, not saved. Calling the SetPersonalizationDirty method ensures that your changes are saved. ❑ Zone: Returns a reference to the WebPartZone that your Web Part is inside. If the Web Part is not in a WebPartZone, Zone returns Nothing. ❑ ZoneIndex: Returns the position of your control inside the WebPartZone (if your control is the first Web Part in the zone or if your control is not in a WebPartZone, ZoneIndex returns 0). 153 Building Web Parts 10_57860x ch05.qxd 10/4/05 9:18 PM Page 153 Web Parts also inherit many of the properties of the Panel control (for example, Direction, DefaultButton, HorizontalAlignment), so if you’re familiar with these properties from working with the Panel control, you can also use them in the Web Part. Turning off Personalization Several properties on the WebControl and WebPart objects allow you to turn off customization options (all customization options are available by default). These properties, when set to False, prevent the WebPart from performing some action: ❑ AllowClose: The Web Part cannot be closed in the browser. This prevents the user from losing your control by closing it. ❑ AllowConnect: The Web Part cannot be connected to other controls. ❑ AllowEdit: The Web Part cannot have its properties set in the browser. ❑ AllowHide: The Web Part cannot be hidden. ❑ AllowMinimize: The Web Part cannot be minimized in the browser. ❑ AllowZoneChange: The Web Part cannot be moved to a different WebPartZone. This allows you to control where on the page a Web Part can be dragged. While you can set these properties in your Web Part’s code, nothing prevents the developer from setting the properties back to some other value (unless, of course, you set these properties in the Render* methods when it’s too late for the host page code to change the value back). A better strategy for controlling these properties is to override the properties to ensure that they remain set to whatever value you want. The following Visual Basic 2005 code, for example, overrides the AllowClose property to keep the property set to False. When code in the host page reads the property, the code returns False; when the code attempts to set the property to any other value, the code sets the WebPart’s version of the property to False (it might be a good idea to raise an error when the user attempts to set the property). Public Overrides Property AllowClose() As Boolean Get AllowClose = False End Get Set(ByVal value As Boolean) MyBase.AllowClose = False End Set End Property In C#: public override bool AllowClose { get { AllowClose = false; 154 Chapter 5 10_57860x ch05.qxd 10/4/05 9:18 PM Page 154 } set { base.AllowClose = false; } } Providing Help Two properties allow you to provide your users with help at run time: HelpMode and HelpURL. The HelpUrl property specifies the start page for help information on your Web Part. When the HelpUrl property is set to a string, a Help verb is added to the control’s Verb menu at run time (see Figure 5-6). You can let the developer using your control set the HelpUrl property, or you can set it from within your Web Part’s code. This Visual Basic 2005 code sets the HelpURL property in the Init event of the Web Part: Private Sub BookDisplay_Init(ByVal sender As Object, _ ByVal e As System.EventArgs) Handles Me.Init MyBase.HelpUrl = “http://www.phvis.com/Booksite.htm” End Sub As does this C# code: private void BookDisplay_Init(object sender, System.EventArgs e) { base.HelpUrl = “http://www.phvis.com/Booksite.htm”; } Figure 5-6 By default, the HelpUrl property is treated as a relative URL to a location somewhere on the site where your control is being used. To have the URL used as an absolute URL that points, for instance, to a location on your Web site, you must begin the URL with http://. 155 Building Web Parts 10_57860x ch05.qxd 10/4/05 9:18 PM Page 155 If you do set the HelpUrl property from within your code, you should override the HelpUrl property of the WebPart object with a ReadOnly version. This will help send a message to a developer using your control that he won’t be able change the HelpURL in the Property List. This Visual Basic 2005 code is an example of a replacement HelpURL property: Public Shadows ReadOnly Property HelpUrl() As String Get Return MyBase.HelpUrl End Get End Property In C#: public override string HelpUrl { get { return base.HelpUrl; } } The HelpMode property controls how your Help page is displayed when the user clicks the Help verb. You can set HelpMode to one of the three values: ❑ System.Web.UI.WebControls.WebParts.WebPartHelpMode.Modalless: Opens the Help page in a new instance of the browser. The user can switch back to the page with your Web Part or close the copy of Internet Explorer displaying the Help page. ❑ System.Web.UI.WebControls.WebParts.WebPartHelpMode.Modal: Opens the Help page in a dialog box that prevents the user from returning to the browser. The user has to close the dialog box to return to the page with your Web Part. ❑ System.Web.UI.WebControls.WebParts.WebPartHelpMode.Navigate: Opens the Help page in the same instance as the page with the Web Part. The user can return to the page with the Web Part by using the browser’s Back button. The result of setting the HelpMode varies from one browser to another. The behavior described here is what you get with Internet Explorer. 156 Chapter 5 10_57860x ch05.qxd 10/4/05 9:18 PM Page 156 Summary In this chapter you have learned a few important skills: ❑ First, the chapter has shown you both how to create a Web Part and how to give user controls or custom controls more functionality when used as Web Parts. Any custom control or user control can have its properties made both customizable (that is, able to be changed by a Web Part editor at run time) and personalizable (that is, having its customizations saved). You make both your custom properties (described in Chapter 8) and base properties from the underlying class customizable and personalizable. ❑ The bulk of the chapter, however, showed you how the WebPart class provides additional features for your control in the Web Part environment —provided that you’re willing to build a custom control. You saw, for example, how you can add additional verbs to your Verb menu and manage the appearance of your control. You also saw the HTML generated for your Web Part when it is used inside of a WebPartZone. In Chapter 8, you see how to add business logic to your Web Parts, custom controls, and user controls. However, there’s more to say about the special features of Web Parts. In Chapter 10, you see how to give your Web Parts the capability to communicate with each other. In Chapter 11 you get more details on the ASP.NET 2.0 personalization framework. That chapter focuses on the code that you put in your host page to manipulate the Web Part framework controls and how to configure your Web site to take advantage of the Web Parts that were built in this chapter. 157 Building Web Parts 10_57860x ch05.qxd 10/4/05 9:18 PM Page 157 10_57860x ch05.qxd 10/4/05 9:18 PM Page 158 Maintaining State with the ViewState One of the essential problems in creating Web applications is state management. Each page, after it’s been sent back to the user, is removed from memory and all of its internal data discarded. The next time the same user requests the page, the page will have suffered the worst kind of short-term memory loss — everything about the previous request has been lost. And, of course, what applies to the page as a whole applies to your control: If you want to carry information from one page request over to another request of the same page by the same user then you’re going to have to write some code to make that happen. Fortunately, ASP.NET provides a set of tools for managing state: State can be managed at the page level (ViewState), the user level (the Session object), and at the application level (the Application object and the ASP.NET Cache). When you’re building a control you can use those same tools. However, managing state from a control does have some special problems, and some tools for solving them. This chapter shows you the tools and techniques for managing state from a custom control or user control. You see how to: ❑ Access the ViewState from your control’s code to efficiently handle large blocks of data ❑ Deal with situations where the developer using your control has disabled the ViewState ❑ Take advantage of the ASP.NET 2.0’s control state portion of the ViewState ❑ Use the ASP.NET Cache to reduce the size of the ViewState ❑ Use type converters to improve the efficiency of your data storage 11_57860x ch06.qxd 10/4/05 9:17 PM Page 159 Using the ViewState The ViewState for your page provides a simple mechanism for maintaining information from one request of a page to another. The ASP.NET control framework gives you three mechanisms for storing data in the ViewState: ❑ Access the ViewState directly: This is the simplest (but least efficient way) of saving state, with all data saved as key/value pairs. ❑ Override the default control methods: This mechanism allows you to add (and retrieve) large blocks of data in the ViewState as efficiently as possible (both in terms of execution time and amount of data put in the ViewState). ❑ Use the area of the ViewState reserved for controls: This mechanism allows you to separate state information that you must manage for your control to function from the state information that the developer should control. One of the attractive features of these mechanisms is that they all work equally well in user controls, custom controls, and Web Parts. Accessing the ViewState Directly Accessing the ViewState from a custom control or a user control is handled the same way as you would from your Web Page. As you do in your Web pages, to add data to the ViewState you provide a key and set it to a value. To reduce the footprint of the ViewState, ASP.NET stores only updated values in the ViewState. In order to implement this facility, ASP.NET tracks changes to entries in the ViewState and saves only changes that the tracking process flags. You need to be aware of this because the tracking process is not started as soon as your control is loaded. This allows ASP.NET to update your control’s properties with values that were set at design time without having to add to the size of the ViewState. If you are storing values in the ViewState during events that occur early in the control’s life cycle (for example, in the Init event), there is the possibility that your changes will be lost. To be sure that your changes are kept you should call the WebControl’s TrackViewState method, as this Visual Basic 2005 code does: Me.TrackViewState() Me.ViewState(“custId”) = “A123” In C#: this.TrackViewState(); this.ViewState[“custId”] = “A123”; Regardless of whether the state of the ViewState is being tracked, if the ViewState for your control is not enabled, your changes to the ViewState will be discarded. You can determine whether it’s worthwhile to update the ViewState by checking your control’s IsViewStateEnabled, as this Visual Basic 2005 code does: 160 Chapter 6 11_57860x ch06.qxd 10/4/05 9:17 PM Page 160 If Me.IsViewStateEnabled = True Then Me.ViewState(“StateData”) = strData End If In C#: if(this.IsViewStateEnabled == true) { this.ViewState[“StateData”] = strData; } Figure 6-1 shows the relationship of the host page, your control, and the ViewState. Figure 6-1 Unfortunately, checking your control’s IsViewStateEnabled property tells you only whether the ViewState has been enabled for your control. If your control is in a panel or a WebPartZone that has had the ViewState turned off, you won’t be able to determine if the ViewState for all of your control’s potential parents have their ViewState turned off. It’s not impossible that your control might be used in a Panel on a user control that is being used in another Panel on a host page. ViewState WebForm Title Start Search 161 Maintaining State with the ViewState 11_57860x ch06.qxd 10/4/05 9:17 PM Page 161 ASP.NET 2.0 provides a solution to this problem: an area of the ViewState that can’t be turned off that is intended to be used by control (referred to as the ControlState in this book). This doesn’t mean that you shouldn’t use the ViewState — as I discuss later, you will often want to use both the ViewState and the ControlState. Regardless of whether you’re using the ViewState or just the portion set aside for controls, you need to understand how to use the ViewState. Managing ViewState Efficiently The problem with using the ViewState property is that, while it’s easy to use, it can result in very large amounts of data being transmitted to the browser. At the very least, storing multiple pieces of data in the ViewState requires setting up multiple key/value pairs in the ViewState. If you have large amounts of data to store it makes more sense to build a custom object or structure and store that object or structure as a single unit by overriding the LoadViewState and the SaveViewState methods. The LoadViewState and SaveViewState methods are called automatically during processing of your con- trol. In brief: ❑ The SaveViewState is a function. Anything that you return from this function is saved in the ViewState. ❑ The LoadViewState is a subroutine. A copy of the data saved in the SaveViewState method is passed to the single parameter that this method accepts. When a page is first requested, the LoadViewState method is not called because the page does not yet have a ViewState to load data from. The SaveViewState method is called, however, just before the control’s Render method, allowing you to save data to the ViewState. When the page is requested on postback, the Page object loaded back into memory and the ViewState information is recovered from the data sent back to the server. The LoadViewState is called early in the control’s life cycle, after the Page’s PreRender event and before the CreateChildControls method. This allows you to use data retrieved in the LoadViewState method as part of re-creating your control in the CreateChildControls and Render routines. The SaveControlState will run, as it did when the page is first requested, before the control’s Render method. Figure 6-2 shows the process. If you do use LoadViewState and SaveViewState methods, you can’t access the ViewState directly — using the SaveViewState method overwrites the key/value pairs saved through the ViewState property. 162 Chapter 6 11_57860x ch06.qxd 10/4/05 9:17 PM Page 162 [...]... the Web site, replacing the original version Updating Custom Controls and Web Parts The process of distributing and updating custom controls and Web Parts that are developed in a separate project from the Web site is simpler than distributing user controls simply because you have fewer options Custom controls and Web Parts in a separate project must be compiled to a DLL before being distributed and. .. will create custom controls and Web Parts in a separate project from your Web site so that the controls can be compiled independently of the Web site and shared among several Web sites In this scenario, the source code for the custom control is never copied to the Web site Only the compiled DLL for the controls is deployed to the site However, if you add a custom control or Web Part to a Web site project,... the tools to distribute and update your controls (and explains how to license your control) If you’re creating Web Parts, Chapter 7 also shows you how to manage the personalization system that Web Parts depend upon 180 Developer Tools At this point you’ve seen how to use and create both custom and user controls, and how to extend custom controls to take advantage of the Web Parts framework In the next... amounts of data ❑ You can handle the serialization and deserialization of objects by writing your own type converters In Chapters 1 and 2, you saw how custom controls, user controls, and Web Parts are used in a Web application In Chapters 3 through 5 you learned how to create your own controls This chapter also gave you the solutions for handling state — a major issue in creating Web applications Chapter... Studio 20 05 ❑ Distribute your controls to work with a single site and to be shared across sites ❑ License your controls so that you can sell them to third parties and have them used by ISPs ❑ Update your controls without redeploying your Web site ❑ Manage the personalization system used by Web Parts Debugging Your Controls at Design Time As you’ve probably realized, much of the code in your controls. .. ControlState information with the ClearChildControlState method, and just the ViewState information with ClearChildViewState method You can check to see if your constituent controls have saved ViewState information with the HasChildViewState For ControlState information, you can use the IsChildControlStateCleared property Putting this together, this Visual Basic 20 05 code checks for ViewState and ControlState... enable me to discuss all the issues in distributing Web applications with custom controls, Web Parts, and user controls In addition, these techniques are simple to work with in a test environment, allowing you to put the samples in this section to the test However, the best practice for distributing production ASP.NET applications is to create a setup and deployment package (an msi file) that can be executed... distributed and the DLL must be placed in the Web site’s bin folder For this section, I use the term custom control” to refer to both custom controls and Web Parts 187 Chapter 7 When you add a reference to a custom control to your Web project, the DLL for the custom control is automatically copied to your project’s directory In addition to copying the DLL for the custom control, some additional files may... RegisterRequiresControlState a reference to the control whose state is being saved (use Me in Visual Basic 20 05 code and this in C# code) Here’s a typical example in Visual Basic 20 05: Private Sub WebCustomControl1_Init(ByVal sender As Object, _ ByVal e As System.EventArgs) Handles Me.Init Me.Page.RegisterRequiresControlState(Me) End Sub In C#, the equivalent Init event looks like this: private void WebCustomControl1_Init(object... if you are deploying controls as part of deploying a Web site using Visual Studio 20 05, you have virtually nothing to do in order to deploy the controls used on the site If you reference a control library (including either custom controls or Web Parts) , that library will be included in the deployment package along with any other components referenced by your project Deploying user controls is equally . framework controls and how to configure your Web site to take advantage of the Web Parts that were built in this chapter. 157 Building Web Parts 10_ 57 860x ch 05. qxd 10/ 4 / 05 9:18 PM Page 157 10_ 57 860x. a location on your Web site, you must begin the URL with http://. 155 Building Web Parts 10_ 57 860x ch 05. qxd 10/ 4 / 05 9:18 PM Page 155 If you do set the HelpUrl property from within your code, you. in the zone or if your control is not in a WebPartZone, ZoneIndex returns 0) . 153 Building Web Parts 10_ 57 860x ch 05. qxd 10/ 4 / 05 9:18 PM Page 153 Web Parts also inherit many of the properties