Creating a Simple Web Part Application
| Let's get our hands dirty by building a simple Web Part application. In this section, you'll create a minimal Web Part application that consists of a single page. It illustrates how to use three of the different types of zones: Web Part Zones, Editor Zones, and Catalog Zones. You start by creating two painfully simple Web Parts. The easiest way to create new Web Parts is to create User Controls. The User Controls contained in Listing 27.1 and Listing 27.2 serve as the Web Parts. Note To learn more about User Controls, see Chapter 7, "Creating Custom Controls with User Controls." Listing 27.1. FirstSimplePart.ascx
Listing 27.2. SecondSimplePart.ascx
These simple Web Parts both consist of nothing more than a single line of text. You can, of course, create more complicated Web Parts with User controls. For example, you can create a User control that contains a GridView control bound to some database data. Or, you can create a User Control that calls a remote web service to display the current weather. In this section, however, we keep things simple. Next, you need to create the page that you'll use to host your Web Parts. Every page that contains Web Parts must, at a minimum, have one WebPartManager control and one or more WebPartZone controls. Every page that contains Web Parts must include one, and only one, WebPartManager control. The WebPartManager control is responsible for tracking the state of all the Web Parts on the page. The WebPartManager control must appear before any other Web Parts on the page. For this reason, it is a good idea to place the WebPartManager control immediately after the server-side form control in the page. The WebPartZone controls are used to mark the different areas of the page that can contain Web Parts. They are used to lay out Web Parts on a page. You can add as many WebPartZone controls to a page as you want. Tip You can add the WebPartManager control and the WebPartZone controls to a Master Page. This is useful when you want to automatically include a WebPartManager and WebPartZone controls in multiple content pages without explicitly declaring the controls in each page. You'll build the page in stages. First, create a page that contains a WebPartManager control and two Web Part Zone controls (see Listing 27.3). Listing 27.3. SimpleWebParts1.aspx
Notice that the page in Listing 27.3 contains a WebPartManager control immediately after the server-side <form> tag. If you neglected to add the WebPartManager control to the page, you would get an exception when you opened the page. The page also contains two Web Part Zones. The first Web Part Zone contains the two simple Web Parts that you created earlier. The Web Parts are listed in the WebPartZone control's ZoneTemplate. The second Web Part Zone is empty. Notice that the two simple Web Parts are both provided with a Title and Description attribute. The Title attribute appears in the Web Part's title bar, and the description appears as a tool tip when you hover your mouse over a Web Part. Visual Web Developer Note If you open the page in Listing 27.3 in Source View, you'll notice a green squiggle warning beneath the Title and Description attributes. You can safely ignore this warning. The warning appears because these aren't really properties of the User Controls. Technically, the Title and Description properties are expando properties that are interpreted by the Web Part Framework at runtime. Note To keep things simple, the two User controls are registered with the <%@ Register %> directive at the top of the page. Another option would be to register the User Controls in your application's Web Configuration file and make the controls automatically available in any page in your application. To learn more about User controls see Chapter 7. When you open the page in Listing 27.3 in a browser, you see the page in Figure 27.3. At the moment, you can't do very much with the page. The only thing you can do is open each of the Web Part's menus. Each Web Part menu has two options: Minimize and Close. Minimizing a Web Part shrinks a Web Part to its title bar. If you close a Web Part, then the Web Part is no longer rendered to the page. Figure 27.3. The Simple Parts 1 page. Web Standards Note The page in Listing 27.3 uses an internal Cascading Style Sheet to position the two Web Part Zones. The zones are positioned with a liquid layout. Both Web Part Zones are floated to the left with the help of a CSS class named column. You can, of course, lay out the Web Part Zones in a page by using an HTML table. However, you should feel very guilty about even thinking about doing it because you should strive to use HTML tables only when displaying tabular data and not for layout. Note How do you open a Web Part after you close it? You use the PageCatalogPart control that is discussed later in this section. If you prefer, you can prevent users from closing Web Parts by disabling the Close menu option. Set the CloseVerb-Visible property on the WebPartZone control to the value false. To do anything interesting in a page that contains Web Parts, you need to add a mechanism to the page that enables users to switch between different Web Part Display Modes. The WebPartManager control is responsible for setting the Display Mode. You can set the Display Mode by taking advantage of the WebPartManager control's DisplayMode property like this: WebPartManager1.DisplayMode = WebPartManager.DesignDisplayMode This line of code sets the page to Design Display Mode. Each of the standard Web Part Display Modes is represented by a shared (static) field exposed by the WebPartManager class. (Display Modes are not represented by an enumeration because you can create custom Display Modes.) Here's another method of setting the Display Mode: WebPartManager1.DisplayMode = WebPartManager1.DisplayModes("Design")This line of code also sets the page Display Mode to Design Display Mode. However, in this case, the DisplayModes property is used as the value of the assignment. The DisplayModes property exposes a collection of all the Display Modes that the WebPartManager control knows. We'll use this second method of setting the Display Mode because it makes it possible to avoid using a Visual Basic SELECT...CASE statement. The page in Listing 27.4 is the same as the previous page in Listing 27.3 with one addition. This new page contains an ASP.NET menu control that enables you to switch the Display Mode of the page to Design Display Mode. (The modifications are emphasized in bold.) Listing 27.4. SimpleWebParts2.aspx
After you open the page in Listing 27.4, you can click the Design menu option and drag and drop the Web Parts between the two Web Part Zones (see Figure 27.4). When you set a page to be in Design Display Mode, the Web Part Framework automatically generates the necessary client-side JavaScript code for moving Web Parts. Figure 27.4. Dragging a Web Part between Web Part Zones. Web Standards Note Performing a drag-and-drop operation requires using a mouse. This requirement violates Section 508 and WCAG accessibility guidelines because a person with limited mobility might need to interact with a web page from the keyboard. You can satisfy these accessibility requirements by adding a LayoutEditorPart control to the page. The LayoutEditorPart control enables you to move Web Parts around a page without using a mouse. It is important to understand that the Web Part Framework automatically saves the state of all the Web Parts in a page. In other words, if you rearrange the Web Parts, the Web Parts retain their new positions when you return to the page in the future. Note In this section, I'm assuming that Windows Authentication is enabled for your application (which is the default Authentication mode). If your Web Parts are forgetting their positions on a page after you close and re-open the page then, most likely, you are not being authenticated. For more information on configuring Authentication, see Part VI, "Security," of this book. You can also enable users to add new Web Parts to a page. To do this, you need to add a CatalogZone control that contains one or more Catalog Parts to the page. For example, the page in Listing 27.5 includes a Declarative Catalog Part which lists both the FirstSimplePart and SecondSimplePart Web Parts. Listing 27.5. SimpleWebParts3.aspx
The additions to Listing 27.5 are emphasized in bold. Notice that a new menu option has been added to the ASP.NET Menu control. The new menu option enables you to switch the page to Catalog Display Mode (see Figure 27.5). Figure 27.5. Opening Catalog Display mode. Furthermore, a Catalog Zone has been added to the page. The Catalog Zone includes a DeclarativeCatalogPart which is used to list the two Web Parts that you can add to the page. The CatalogZone also includes a PageCatalogPart control, which is used to add closed Web Parts back to a page. After you open the page in Listing 27.5 in a browser, you can click the Catalog menu option and add new instances of the two Web Parts to the page. Again, any changes you make to the page are saved automatically by the Web Part Framework. Notice that you can now retrieve any Web Parts that you have closed on the page by taking advantage of the PageCatalogPart. If you close a Web Part by selecting a Web Part's Close menu option, you can re-open the Web Part by clicking Catalog and selecting the closed Web Part from the list of Web Parts rendered by the Page Catalog Part control. Note The DeclarativeCatalogPart control does not enable you to drag and drop Web Parts onto the page. If you want to add drag-and-drop support or paging and sorting support or any other custom functionality to a Catalog Part, then you need to create a custom Catalog Part. This option is discussed in Chapter 30. Finally, you can enable users to edit Web Parts. For example, Listing 27.6 contains a new Web Part named FeaturedBookPart. This Web Part displays information about a particular book. Listing 27.6. FeaturedBookPart.ascx
You should notice several things about the Web Part in Listing 27.6. Notice that each of its properties is decorated with the following attributes: Personalizable, WebBrowsable, WebDisplayName, WebDescription. The Web Part Framework automatically detects these attributes. The most important attribute is the Personalizable attribute. Any property marked with the Personalizable attribute is automatically saved and loaded by the Web Part Framework. Because the BookTitle, BookCategory, BookDescription, and OnSale properties are all marked as Personalizable, any changes to these properties are saved by the Web Part Framework. The remaining three attributesWebBrowsable, WebDisplayName, and WebDescriptionare used by the PropertyGridEditorPart control. Only properties marked with the WebBrowsable attribute are displayed in the property grid rendered by the PropertyGridEditorPart control. The WebDisplayName and WebDescription attributes determine the title and description displayed for the property in the property sheet. Both the WebDisplayName and WebDescription attributes are optional. The page in Listing 27.7 illustrates how you can edit the FeaturedBookPart by using the PropertyGridEditorPart control (changes from the previous listings are emphasized in bold). Listing 27.7. SimpleWebParts4.aspx
When you open the page in Listing 27.7 in a browser, you can click the Edit menu option to switch the page into Edit Display Mode. When a page is in Edit Display Mode, you can edit particular Web Parts by selecting the Edit menu option from a Web Part menu. Selecting a Web Part to edit causes the EditorZone to render the PropertyGridEditorPart control (see Figure 27.6). Figure 27.6. Opening the PropertyGridEditorPart control. Notice that form fields are automatically generated for each of the properties that were marked as Personalizable. If you modify any of the properties and click either OK or Apply, the Web Part Framework automatically saves any changes to the properties. Note By default, changes to a Web Part property have User scope. In other words, each person who uses a Web Part page can customize it for his or her particular needs. You can also enable Shared scope personalization. In that case, changes to a Web Part property have an effect on all users. To learn more about personalization, see Chapter 29, "Personalizing Web Parts." Web Standards Note The PropertyGridEditorPart automatically generates a form that is accessible to persons with disabilities. The form is contained in a fieldset element. Furthermore, label elements with for attributes are used to explicitly associate each label with each form field. This section has walked you through the process of creating a basic page that contains Web Parts. The remainder of this chapter examines each of the tool zones included in the Web Part Framework in more detail. You'll learn how to work with Catalog Zones, Editor Zones, and Connections Zones. |
