ASP.NET Web Parts is an integrated set of controls for creating Web sites that enable end users to modify the content, appearance, and behavior of Web pages directly from a browser. The modifications can be applied to all users on the site or to individual users. When users modify pages and controls, the settings can be saved to retain a user's personal preferences across future browser sessions, a feature called personalization. These Web Parts capabilities mean that developers can empower end users to personalize a Web application dynamically, without developer or administrator intervention
Using the Web Parts control set, you as a developer can enable end users to:
• Personalize page content. Users can add new Web Parts controls to a page, remove them, hide them, or minimize them like ordinary windows.
• Personalize page layout. Users can drag a Web Parts control to a different zone on a page, or change its appearance, properties, and behavior.
• Export and import controls. Users can import or export Web Parts control settings for use in other pages or sites, retaining the properties, appearance, and even the data in the controls. This reduces data entry and configuration demands on end users.
• Create connections. Users can establish connections between controls so that, for example, a chart control could display a graph for the data in a stock ticker control. Users could personalize not only the connection itself, but the appearance and details of how the chart control displays the data.
• Manage and personalize site-level settings. Authorized users can configure site-level settings; determine who can access a site or page, set role-based access to controls, and so on. For example, a user in an administrative role could set a Web Parts control to be shared by all users, and prevent users who are not administrators from personalizing the shared control.
Web Parts Essentials
The Web Parts control set consists of three main building blocks: personalization, user interface (UI) structural components, and actual Web Parts UI controls. For more details, see Web Parts Control Set Overview. Much of your development effort will focus on Web Parts controls, which are simply ASP.NET controls that can use the features of the Web Parts control set.
As an example of how Web Parts controls can be used to build personalizable Web pages, examine the following screen shot.
Typical Web Parts page
This page contains several basic elements of a Web Parts application:
• Use of zones for page layout. There are two columns that can contain controls: one has the Weather and Stock Quotes controls, the other has Hotmail and News controls. These columns in Web Parts terminology are called zones--regions on a page that contain Web Parts controls. Zones exist to lay out Web Parts controls on a page, and to provide a common UI for the controls. There can be one or many zones on a page, each zone can contain one or many Web Parts controls, and each zone can have a vertical or horizontal orientation for page layout.
• Use of zones for page layout. There are two columns that can contain controls: one has the Weather and Stock Quotes controls, the other has Hotmail and News controls. These columns in Web Parts terminology are called zones--regions on a page that contain Web Parts controls. Zones exist to lay out Web Parts controls on a page, and to provide a common UI for the controls. There can be one or many zones on a page, each zone can contain one or many Web Parts controls, and each zone can have a vertical or horizontal orientation for page layout.
• Web Parts controls within the zones. Each control has UI verbs (actions that a user can perform) that can appear as links, buttons, or clickable images on the control. In the preceding screen shot, notice that each control has a button in its title bar that exposes a drop-down menu. In the menus for each control are options to change details particular to that control, and other options to carry out common actions such as moving or deleting a control, and getting help. Some controls, such as the Weather control, allow users to personalize them so the controls display only information relevant to the user.
Links to enable extensive personalization. These allow users to change the content, color, and layout of the page. For instance, if users click the Add Column link, a Web Parts application could enable them to add another column to a page. Or users could click the Add Content link, which displays a catalog of controls that that they can optionally add to the page. One of those could be a stock charting control. A user could add that control to one of the zones on the page, and could then connect it to the existing Stock Quotes control to chart the stock data it contains.
Walkthrough: Creating a Web Parts Page
This walkthrough is a hands-on demonstration of the essential components and tasks for creating Web pages that use Web Parts controls in Visual Studio.
In many Web applications it is useful to be able to change the appearance of the content, as well as to allow users to select and arrange the content they want to see. ASP.NET Web Parts enable you to create Web pages that present modular content and that enable users to change the appearance and content to suit their preferences. For a general introduction to Web Parts, see ASP.NET Web Parts Overview. For an overview of the Web Parts control set, see Web Parts Control Set Overview.
During this walkthrough, you create a page that uses Web Parts controls to create a Web page that user can modify, or personalize. Tasks illustrated in this walkthrough include:
• Adding Web Parts controls to a page.
• Creating a custom user control and using it as a Web Parts control.
• Enabling users to personalize the layout of the Web Parts controls on the page.
• Enabling users to edit the appearance of a Web Parts control.
• Enabling users to select from a catalog of available Web Parts controls.
During this walkthrough, you create a page that uses Web Parts controls to create a Web page that user can modify, or personalize. Tasks illustrated in this walkthrough include:
• Adding Web Parts controls to a page.
• Creating a custom user control and using it as a Web Parts control.
• Enabling users to personalize the layout of the Web Parts controls on the page.
• Enabling users to edit the appearance of a Web Parts control.
• Enabling users to select from a catalog of available Web Parts controls.
Prerequisites
In order to complete this walkthrough, you will need:
• A site that can identify individual users. If you have a site already configured with ASP.NET membership, you can use that site for this walkthrough. Otherwise, the walkthrough provides instructions on how to configure your site to identify you by your Windows user account name.
• A visual design environment for creating Web pages. This walkthrough uses Visual Studio 2005.
• A configured personalization provider and database. Web Parts personalization is enabled by default, and it uses the SQL personalization provider (SqlPersonalizationProvider) with Microsoft SQL Server Express Edition to store personalization data. This walkthrough uses SQL Server Express and the default SQL provider. If you have SQL Server Express installed, no configuration is needed. SQL Server Express is available with Microsoft Visual Studio 2005 as an optional part of the installation, or as a free download from Microsoft.com. To use a full version of SQL Server, you must install and configure an ASP.NET application services database, and configure the SQL personalization provider to connect to that database. For details, see Creating and Configuring the Application Services Database for SQL Server.
Creating and Configuring the Web Site
This walkthrough requires that you have a user identity, so that your Web Parts settings can be keyed to you. If you already have a Web site configured to use membership, it is recommended that you use that site. Otherwise, you can create a new site and use your current Windows user name as your user identity.
Note:
You do not need to do anything to enable Web Parts personalization; it is enabled by default for the Web Parts control set. When you first run a Web Parts page on a site, ASP.NET sets up a default personalization provider to store user personalization settings. For more information about personalization, see Web Parts Personalization Overview.
To create a new Web site
• In Visual Studio, create a new ASP.NET Web site as described in Walkthrough: Creating a Web Site with Membership and User Login.
Creating a Simple Page with Web Parts
In this part of the walkthrough, you create a page that uses Web Parts controls to show static content. The first step in working with Web Parts is to create a page with these elements:
• A WebPartManager control, which coordinates all Web Parts controls.
• One or more zones, which are composite controls that contain WebPart or other server controls and occupy a specified region of a page.
To create a page for containing Web Parts controls
1. Close the default page and add a new page named WebPartsDemo.aspx.
2. Switch to Design view.
3. In the View menu, click Visual Aids, and then make sure that the ASP.NET Non-Visual Controls and Margins and Padding options are selected.
This enables you to see layout tags and controls that do not have a UI.
4. Position the insertion point in the div element.
5. From the WebParts tab of the Toolbox, drag a WebPartManager control onto the page, between the newline character and the opening
tag.
The WebPartManager control does not render any output, so it appears as a gray box on the designer surface.
6. Add a new line just after the WebPartManager control.
7. In the Block Format list in the toolbar, select Heading 1.
8. In the heading, add the text "Web Parts Demonstration Page".
9. Add a new line after the text.
10. In the Table menu, click Insert Table, specify a table with one row and three columns, and then click OK.
11. Drag a WebPartZone control into the left table column.
12. Right-click the WebPartZone control, choose Properties, and set the following properties:
ID: "SidebarZone"
HeaderText: "Sidebar"
13. Drag a second WebPartZone control into the middle table column and set the following properties:
ID: "MainZone"
HeaderText: "Main"
14. Save the file, but do not close it yet
Your page now has two zones that you can control separately. However, neither zone has any content, so the next step is to create content. For this walkthrough, you work with Web Parts controls that display only static content.
The layout of a Web Parts zone is specified by a ZoneTemplate element. Inside the zone template, you can add any ASP.NET control, including a custom Web Parts control, a user control, or a server control. In this walkthrough, you use the Label control to display static text. When you place a server control in a WebPartZone zone, ASP.NET treats the control as a Web Parts control at run time, which enables Web Parts features for the control.
To create content for the main zone
1. Switch to Design view.
2. From the Standard tab of the Toolbox, drag a Label control into the contents area of the zone whose ID property is set to MainZone.
3. Switch to Source view.
Notice that a ZoneTemplate element is added to wrap the Label control in the MainZone zone.
4. Add an attribute named title to the Label control and set its value to "Content".
5. Remove the Text attribute from the Label control.
6. Inside the Label control, add some text such as "
The markup will look like the following example:
7. Save the file.
Next, you will create a user control that can also be added to the page as a Web Parts control.
To create a user control
1. Add a new Web user control to your site and name it SearchUserControl.ascx. Make sure that the Place source code in a separate file is cleared.
This control will act as a search control.
Note:
The user control for this walkthrough does not implement actual search functionality; it is used only to demonstrate Web Parts features.
2. Switch to Design view.
3. From the Standard tab of the Toolbox, drag a TextBox control onto the page.
4. Add a blank line after the text box that you just added.
5. Drag a Button control onto the page and drop it below the text box.
6. Set the Text property of the Button control to "Search".
7. Switch to Source view.
8. Make sure that the markup for the user control looks like the following example:
Visual Basic
<%@ Control language="VB" classname="SearchUserControl" %>
C#
<%@ Control language="C#" classname="SearchUserControl" %>
9. Save and close the file.
Security Note:
This control has a text box that accepts user input, which is a potential security threat. User input in a Web page can potentially contain malicious client script. By default, ASP.NET Web pages validate user input to ensure that the input does not contain HTML elements or script. As long as this validation is enabled, you do not need to explicitly check for script or HTML elements in user input. For more information, see Script Exploits Overview.
Now you can add Web Parts controls to the Sidebar zone. You will add two controls to the Sidebar zone. One contains a list of links, and the other is the user control you created earlier in the walkthrough. You create the links by using a Label server control, similar to the way you created the static text for the Main zone. However, although the individual server controls contained in the user control could be contained directly in the zone (like the Label control), in this case they are not. Instead, they are part of the user control you created in the previous procedure. This demonstrates a common way to package controls and extra functionality in a user control, and then reference that control in a zone as a Web Parts control.
At run time, the Web Parts control set wraps both controls inside a Generic WebPart controls. The generic part control becomes the parent control, and you can access the server control through the parent control's ChildControl property. Using generic part controls enables standard Web server controls to have the same basic behavior and attributes as Web Parts controls that derive from the WebPart class.
To add Web Parts controls to the sidebar zone
1. Open the WebPartsDemo.aspx page.
2. Switch to Design view.
3. Drag the SearchUserControl.ascx user control from Solution Explorer into the SidebarZone zone.
4. Add an attribute named title to the user control element and set its value to "Search".
5. Save the WebPartsDemo.aspx page.
6. Switch to Source view.
7. Inside the asp:WebPartZone element for the SidebarZone zone, add a Label control that contains links. In the opening tag for the user control, add a title attribute with a value of "My Links".
The markup looks like the following example:
ASP.NET site
GotDotNet
Contoso.com
8. Save and close the file.
Now you can test the page.
To test the page
• Load the page in a browser.
The page displays the two zones. The following figure shows the page.
In the title bar of each control is a down arrow that provides access to a verbs menu of actions that you can perform on a control. Click the verbs menu in one of the controls, and then click the Minimize verb and note that the control is minimized. From the verbs menu, click Restore, and the control returns to its normal size.
Enabling Users to Edit Pages and Change Layout
Web Parts lets users change the layout of Web Parts controls by dragging them from one zone to another. In addition to allowing users to move WebPart controls from one zone to another, you can allow users to edit various characteristics of the controls, including their appearance, layout, and behavior. The Web Parts control set provides basic editing functionality for WebPart controls. Although you will not do so in this walkthrough, you can also create custom editor controls that allow users to edit the features of WebPart controls. As with changing the location of a WebPart control, editing a control's properties relies on ASP.NET personalization to save the changes that users make.
In this part of the walkthrough, you add the ability for users to edit the basic characteristics of any WebPart control on the page. To enable these features, you add another custom user control to the page, along with an asp:editorzone element and two editing controls.
To create a user control that enables changing page layout
1. In Visual Studio, in the File menu, click New, and then click File.
2. In the Add New Item dialog box, select Web User Control. Name the new file DisplayModeMenu.ascx. Clear the Place source code in separate file box.
3. Click Add to create the new control.
4. Switch to Source view.
5. Remove all the existing markup in the new file, and then paste in the following code.
This user control code uses features of the Web Parts control set that enable a page to change its view or display mode. It also enables you to change the physical appearance and layout of the page while you are in certain display modes.
Visual Basic
<%@ control language="vb" classname="DisplayModeMenuVB"%>
Width="230"
BackColor="lightgray"
Font-Names="Verdana, Arial, Sans Serif" >
Font-Bold="true"
Font-Size="8"
Width="120" />
Width="120"
OnSelectedIndexChanged="DisplayModeDropdown_SelectedIndexChanged" />
ToolTip="Reset the current user's personalization data for
the page."
Font-Size="8"
OnClick="LinkButton1_Click" />
Font-Bold="true"
Font-Size="8"
Visible="false" >
AutoPostBack="true"
GroupName="Scope"
OnCheckedChanged="RadioButton1_CheckedChanged" />
AutoPostBack="true"
GroupName="Scope"
OnCheckedChanged="RadioButton2_CheckedChanged" />
Save the file.
Note:
Although this user control can enable users of the Web Parts page to toggle between shared and user-personalization mode, the personalization feature requires the user to have appropriate permissions, as specified in the Web.config file. This walkthrough does not illustrate how to grant these rights, so the feature is not enabled. Therefore, the User and Shared radio buttons on the user control are hidden when you run the page. For more information on personalization, see Web Parts Personalization.
To enable users to change the layout
1. Open the WebPartsDemo.aspx page.
2. Switch to Design view.
3. Add a blank line after the "Web Parts Demonstration Page" text that you added earlier.
4. From Solution Explorer, drag the DisplayModeMenu.ascx user control into the WebPartsDemo.aspx page and drop it on the blank line.
5. From the WebParts tab of the Toolbox, drag an EditorZone control to the remaining open table cell in the WebPartsDemo.aspx page.
6. Switch to Source view.
7. From the WebParts tab of the Toolbox, drag an AppearanceEditorPart control and a LayoutEditorPart control into the EditorZone control.
The WebPartManager control does not render any output, so it appears as a gray box on the designer surface.
6. Add a new line just after the WebPartManager control.
7. In the Block Format list in the toolbar, select Heading 1.
8. In the heading, add the text "Web Parts Demonstration Page".
9. Add a new line after the text.
10. In the Table menu, click Insert Table, specify a table with one row and three columns, and then click OK.
11. Drag a WebPartZone control into the left table column.
12. Right-click the WebPartZone control, choose Properties, and set the following properties:
ID: "SidebarZone"
HeaderText: "Sidebar"
13. Drag a second WebPartZone control into the middle table column and set the following properties:
ID: "MainZone"
HeaderText: "Main"
14. Save the file, but do not close it yet
Your page now has two zones that you can control separately. However, neither zone has any content, so the next step is to create content. For this walkthrough, you work with Web Parts controls that display only static content.
The layout of a Web Parts zone is specified by a ZoneTemplate element. Inside the zone template, you can add any ASP.NET control, including a custom Web Parts control, a user control, or a server control. In this walkthrough, you use the Label control to display static text. When you place a server control in a WebPartZone zone, ASP.NET treats the control as a Web Parts control at run time, which enables Web Parts features for the control.
To create content for the main zone
1. Switch to Design view.
2. From the Standard tab of the Toolbox, drag a Label control into the contents area of the zone whose ID property is set to MainZone.
3. Switch to Source view.
Notice that a ZoneTemplate element is added to wrap the Label control in the MainZone zone.
4. Add an attribute named title to the Label control and set its value to "Content".
5. Remove the Text attribute from the Label control.
6. Inside the Label control, add some text such as "
Welcome to my Home Page
".The markup will look like the following example:
Welcome to My Home Page
7. Save the file.
Next, you will create a user control that can also be added to the page as a Web Parts control.
To create a user control
1. Add a new Web user control to your site and name it SearchUserControl.ascx. Make sure that the Place source code in a separate file is cleared.
This control will act as a search control.
Note:
The user control for this walkthrough does not implement actual search functionality; it is used only to demonstrate Web Parts features.
2. Switch to Design view.
3. From the Standard tab of the Toolbox, drag a TextBox control onto the page.
4. Add a blank line after the text box that you just added.
5. Drag a Button control onto the page and drop it below the text box.
6. Set the Text property of the Button control to "Search".
7. Switch to Source view.
8. Make sure that the markup for the user control looks like the following example:
Visual Basic
<%@ Control language="VB" classname="SearchUserControl" %>
C#
<%@ Control language="C#" classname="SearchUserControl" %>
9. Save and close the file.
Security Note:
This control has a text box that accepts user input, which is a potential security threat. User input in a Web page can potentially contain malicious client script. By default, ASP.NET Web pages validate user input to ensure that the input does not contain HTML elements or script. As long as this validation is enabled, you do not need to explicitly check for script or HTML elements in user input. For more information, see Script Exploits Overview.
Now you can add Web Parts controls to the Sidebar zone. You will add two controls to the Sidebar zone. One contains a list of links, and the other is the user control you created earlier in the walkthrough. You create the links by using a Label server control, similar to the way you created the static text for the Main zone. However, although the individual server controls contained in the user control could be contained directly in the zone (like the Label control), in this case they are not. Instead, they are part of the user control you created in the previous procedure. This demonstrates a common way to package controls and extra functionality in a user control, and then reference that control in a zone as a Web Parts control.
At run time, the Web Parts control set wraps both controls inside a Generic WebPart controls. The generic part control becomes the parent control, and you can access the server control through the parent control's ChildControl property. Using generic part controls enables standard Web server controls to have the same basic behavior and attributes as Web Parts controls that derive from the WebPart class.
To add Web Parts controls to the sidebar zone
1. Open the WebPartsDemo.aspx page.
2. Switch to Design view.
3. Drag the SearchUserControl.ascx user control from Solution Explorer into the SidebarZone zone.
4. Add an attribute named title to the user control element and set its value to "Search".
5. Save the WebPartsDemo.aspx page.
6. Switch to Source view.
7. Inside the asp:WebPartZone element for the SidebarZone zone, add a Label control that contains links. In the opening tag for the user control, add a title attribute with a value of "My Links".
The markup looks like the following example:
ASP.NET site
GotDotNet
Contoso.com
8. Save and close the file.
Now you can test the page.
To test the page
• Load the page in a browser.
The page displays the two zones. The following figure shows the page.
In the title bar of each control is a down arrow that provides access to a verbs menu of actions that you can perform on a control. Click the verbs menu in one of the controls, and then click the Minimize verb and note that the control is minimized. From the verbs menu, click Restore, and the control returns to its normal size.
Enabling Users to Edit Pages and Change Layout
Web Parts lets users change the layout of Web Parts controls by dragging them from one zone to another. In addition to allowing users to move WebPart controls from one zone to another, you can allow users to edit various characteristics of the controls, including their appearance, layout, and behavior. The Web Parts control set provides basic editing functionality for WebPart controls. Although you will not do so in this walkthrough, you can also create custom editor controls that allow users to edit the features of WebPart controls. As with changing the location of a WebPart control, editing a control's properties relies on ASP.NET personalization to save the changes that users make.
In this part of the walkthrough, you add the ability for users to edit the basic characteristics of any WebPart control on the page. To enable these features, you add another custom user control to the page, along with an asp:editorzone element and two editing controls.
To create a user control that enables changing page layout
1. In Visual Studio, in the File menu, click New, and then click File.
2. In the Add New Item dialog box, select Web User Control. Name the new file DisplayModeMenu.ascx. Clear the Place source code in separate file box.
3. Click Add to create the new control.
4. Switch to Source view.
5. Remove all the existing markup in the new file, and then paste in the following code.
This user control code uses features of the Web Parts control set that enable a page to change its view or display mode. It also enables you to change the physical appearance and layout of the page while you are in certain display modes.
Visual Basic
<%@ control language="vb" classname="DisplayModeMenuVB"%>
Width="230"
BackColor="lightgray"
Font-Names="Verdana, Arial, Sans Serif" >
Font-Bold="true"
Font-Size="8"
Width="120" />
Width="120"
OnSelectedIndexChanged="DisplayModeDropdown_SelectedIndexChanged" />
ToolTip="Reset the current user's personalization data for
the page."
Font-Size="8"
OnClick="LinkButton1_Click" />
Font-Bold="true"
Font-Size="8"
Visible="false" >
AutoPostBack="true"
GroupName="Scope"
OnCheckedChanged="RadioButton1_CheckedChanged" />
AutoPostBack="true"
GroupName="Scope"
OnCheckedChanged="RadioButton2_CheckedChanged" />
Save the file.
Note:
Although this user control can enable users of the Web Parts page to toggle between shared and user-personalization mode, the personalization feature requires the user to have appropriate permissions, as specified in the Web.config file. This walkthrough does not illustrate how to grant these rights, so the feature is not enabled. Therefore, the User and Shared radio buttons on the user control are hidden when you run the page. For more information on personalization, see Web Parts Personalization.
To enable users to change the layout
1. Open the WebPartsDemo.aspx page.
2. Switch to Design view.
3. Add a blank line after the "Web Parts Demonstration Page" text that you added earlier.
4. From Solution Explorer, drag the DisplayModeMenu.ascx user control into the WebPartsDemo.aspx page and drop it on the blank line.
5. From the WebParts tab of the Toolbox, drag an EditorZone control to the remaining open table cell in the WebPartsDemo.aspx page.
6. Switch to Source view.
7. From the WebParts tab of the Toolbox, drag an AppearanceEditorPart control and a LayoutEditorPart control into the EditorZone control.
