SharePoint Tips and Tricks: 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.

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

Close the default page and add a new page named WebPartsDemo.aspx.
Switch to Design view.
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.
Position the insertion point in the div element.
From the WebParts tab of the Toolbox, drag a WebPartManager control onto the page, between the newline character and the opening <div> tag.

The WebPartManager control does not render any output, so it appears as a gray box on the designer surface.
Add a new line just after the WebPartManager control.
In the Block Format list in the toolbar, select Heading 1.
In the heading, add the text "Web Parts Demonstration Page".
Add a new line after the text.
In the Table menu, click Insert Table, specify a table with one row and three columns, and then click OK.
Drag a WebPartZone control into the left table column.
Right-click the WebPartZone control, choose Properties, and set the following properties:

ID: "SidebarZone"

HeaderText: "Sidebar"
Drag a second WebPartZone control into the middle table column and set the following properties:

ID: "MainZone"

HeaderText: "Main"
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

Switch to Design view.
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.
Switch to Source view.

Notice that a ZoneTemplate element is added to wrap the Label control in the MainZone zone.
Add an attribute named title to the Label control and set its value to "Content".
Remove the Text attribute from the Label control.

Inside the Label control, add some text such as "<h2>Welcome to my Home Page</h2>".

The markup will look like the following example:

<asp:WebPartZone id="MainZone" runat="server" headertext="Main">
  <ZoneTemplate>
    <asp:Label ID="Label1" runat="server" Title="Content">
      <h2>Welcome to My Home Page</h2>
    </asp:Label>
  </ZoneTemplate>
</asp:WebPartZone>

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

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.
Switch to Design view.
From the Standard tab of the Toolbox, drag a TextBox control onto the page.
Add a blank line after the text box that you just added.
Drag a Button control onto the page and drop it below the text box.
Set the Text property of the Button control to "Search".
Switch to Source view.

Note
The user control for this walkthrough does not implement actual search functionality; it is used only to demonstrate Web Parts features.

Make sure that the markup for the user control looks like the following example:

<%@ Control language="C#" classname="SearchUserControl" %>
<asp:TextBox runat="server" ID="TextBox1"></asp:TextBox>
<p>&nbsp;</p> 
<asp:Button runat="server" ID=" Button1" text="Search" />

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.

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 GenericWebPart 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

Open the WebPartsDemo.aspx page.
Switch to Design view.
Drag the SearchUserControl.ascx user control from Solution Explorer into the SidebarZone zone.
Add an attribute named title to the user control element and set its value to "Search".
Save the WebPartsDemo.aspx page.
Switch to Source view.

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:WebPartZone id="SidebarZone" runat="server" 
    headertext="Sidebar">
  <ZoneTemplate>
    <asp:Label runat="server" id="linksPart" title="My Links">
      <a href="http://www.asp.net">ASP.NET site</a> 
      <br />
      <a href="http://www.gotdotnet.com">GotDotNet</a> 
      <br />
      <a href="http://www.contoso.com">Contoso.com</a> 
      <br />
    </asp:Label>
    <uc1:SearchUserControl id="SearchUserControl1" runat="server"
        title="Search" />
  </ZoneTemplate>
</asp:WebPartZone>

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

In Visual Studio, in the File menu, click New, and then click File.
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.
Click Add to create the new control.
Switch to Source view.

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.

<%@ control language="C#" classname="DisplayModeMenuCS"%>
<script runat="server">
  
 // Use a field to reference the current WebPartManager control.
  WebPartManager _manager;

  void Page_Init(object sender, EventArgs e)
  {
    Page.InitComplete += new EventHandler(InitComplete);
  }  

  void InitComplete(object sender, System.EventArgs e)
  {
    _manager = WebPartManager.GetCurrentWebPartManager(Page);

    String browseModeName = WebPartManager.BrowseDisplayMode.Name;

    // Fill the drop-down list with the names of supported display modes.
    foreach (WebPartDisplayMode mode in 
      _manager.SupportedDisplayModes)
    {
      String modeName = mode.Name;
      // Make sure a mode is enabled before adding it.
      if (mode.IsEnabled(_manager))
      {
        ListItem item = new ListItem(modeName, modeName);
        DisplayModeDropdown.Items.Add(item);
      }
    }

    // If Shared scope is allowed for this user, display the 
    // scope-switching UI and select the appropriate radio 
    // button for the current user scope.
    if (_manager.Personalization.CanEnterSharedScope)
    {
      Panel2.Visible = true;
      if (_manager.Personalization.Scope == 
        PersonalizationScope.User)
        RadioButton1.Checked = true;
      else
        RadioButton2.Checked = true;
    }
  }
 
  // Change the page to the selected display mode.
  void DisplayModeDropdown_SelectedIndexChanged(object sender, 
    EventArgs e)
  {
    String selectedMode = DisplayModeDropdown.SelectedValue;

    WebPartDisplayMode mode = 
     _manager.SupportedDisplayModes[selectedMode];
    if (mode != null)
      _manager.DisplayMode = mode;
  }

  // Set the selected item equal to the current display mode.
  void Page_PreRender(object sender, EventArgs e)
  {
    ListItemCollection items = DisplayModeDropdown.Items;
    int selectedIndex = 
      items.IndexOf(items.FindByText(_manager.DisplayMode.Name));
    DisplayModeDropdown.SelectedIndex = selectedIndex;
  }

  // Reset all of a user's personalization data for the page.
  protected void LinkButton1_Click(object sender, EventArgs e)
  {
    _manager.Personalization.ResetPersonalizationState();
  }

  // If not in User personalization scope, toggle into it.
  protected void RadioButton1_CheckedChanged(object sender, EventArgs e)
  {
    if (_manager.Personalization.Scope == 
      PersonalizationScope.Shared)
      _manager.Personalization.ToggleScope();
  }

  // If not in Shared scope, and if user has permission, toggle 
  // the scope.
  protected void RadioButton2_CheckedChanged(object sender, 
    EventArgs e)
  {
    if (_manager.Personalization.CanEnterSharedScope && 
        _manager.Personalization.Scope == 
          PersonalizationScope.User)
        _manager.Personalization.ToggleScope();
  }
</script>
<div>
  <asp:Panel ID="Panel1" runat="server" 
    Borderwidth="1" 
    Width="230" 
    BackColor="lightgray"
    Font-Names="Verdana, Arial, Sans Serif" >
    <asp:Label ID="Label1" runat="server" 
      Text="&nbsp;Display Mode" 
      Font-Bold="true"
      Font-Size="8"
      Width="120" />
    <asp:DropDownList ID="DisplayModeDropdown" runat="server"  
      AutoPostBack="true" 
      Width="120"
      OnSelectedIndexChanged="DisplayModeDropdown_SelectedIndexChanged" />
    <asp:LinkButton ID="LinkButton1" runat="server"
      Text="Reset User State" 
      ToolTip="Reset the current user's personalization data for 
      the page."
      Font-Size="8" 
      OnClick="LinkButton1_Click" />
    <asp:Panel ID="Panel2" runat="server" 
      GroupingText="Personalization Scope"
      Font-Bold="true"
      Font-Size="8" 
      Visible="false" >
      <asp:RadioButton ID="RadioButton1" runat="server" 
        Text="User" 
        AutoPostBack="true"
        GroupName="Scope" 
        OnCheckedChanged="RadioButton1_CheckedChanged" />
      <asp:RadioButton ID="RadioButton2" runat="server" 
        Text="Shared" 
        AutoPostBack="true"
        GroupName="Scope" 
        OnCheckedChanged="RadioButton2_CheckedChanged" />
    </asp:Panel>
  </asp:Panel>
</div>

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.

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

Open the WebPartsDemo.aspx page.
Switch to Design view.
Add a blank line after the "Web Parts Demonstration Page" text that you added earlier.
From Solution Explorer, drag the DisplayModeMenu.ascx user control into the WebPartsDemo.aspx page and drop it on the blank line.
From the WebParts tab of the Toolbox, drag an EditorZone control to the remaining open table cell in the WebPartsDemo.aspx page.
From the WebParts tab of the Toolbox, drag an AppearanceEditorPart control and a LayoutEditorPart control into the EditorZone control.

Switch to Source view.

The resulting markup in the table cell will look similar to the following code:

<td valign="top">
  <asp:EditorZone ID="EditorZone1" runat="server">
    <ZoneTemplate>
      <asp:AppearanceEditorPart ID="AppearanceEditorPart1" 
        runat="server" />
      <asp:LayoutEditorPart ID="LayoutEditorPart1" runat="server" />
    </ZoneTemplate>
  </asp:EditorZone>
</td> 

Note
Although the AppearanceEditorPart and LayoutEditorPart controls are used in this walkthrough, the BehaviorEditorPart and PropertyGridEditorPart controls are not, because they require setup beyond the scope of this walkthrough.

Save the WebPartsDemo.aspx file.

You have created a user control that lets you change display modes and change page layout, and you have referenced the control on the primary Web page. You can now test the capability to edit pages and change layout.

To test layout changes

Load the page in a browser.
In the Display Mode menu, click Edit.

The zone titles are displayed.
Drag the My Links control by its title bar from the Sidebar zone to the bottom of the Main zone.

The page will look like the following:
Click Display Mode, and then click Browse.

The page is refreshed, the zone names disappear, and the My Links control remains where you positioned it.
To demonstrate that personalization is working, close the browser, and then load the page again. The changes you made are saved for future browser sessions.
In the Display Mode menu, click Edit.

Each control on the page is now displayed with a down arrow in its title bar, which contains the verbs drop-down menu.
Click the arrow to display the verbs menu on the My Links control and then click Edit.

The EditorZone control appears. It displays the EditorPart controls that you added.
In the Appearance section of the edit control, change the title to My Favorites. In the Chrome Type list, select Title Only, and then click Apply.

The following figure shows the page in edit mode.
In the Display Mode menu, click Browse to return to browse mode.

The control now has an updated title and no border, as shown in the following figure.

Adding Web Parts at Run Time

You can also enable users to add Web Parts controls to their page at run time. To do so, configure the page with a Web Parts catalog, which contains a list of Web Parts controls that you want to make available to users.

Note
In this walkthrough, you create a template containing FileUpload and Calendar controls. This will allow you to test the basic functionality of the catalog, but the resulting Web Parts controls do not have any real functionality. If you have a custom Web or user control, you can substitute it for the static content.

To allow users to add Web Parts at run time

Open the WebPartsDemo.aspx page.
Switch to Source view.
From the WebParts tab of the Toolbox, drag a CatalogZone control into the right column of the table, beneath the EditorZone control.

Both controls can be in the same table cell because they will not be displayed at the same time.
In the Properties pane, assign the string Add Web Parts to the HeaderText property of the CatalogZone control.
Switch to Design view
From the WebParts tab of the Toolbox, drag a DeclarativeCatalogPart control into the content area of the CatalogZone control.
Click the arrow in the upper right corner of the DeclarativeCatalogPart control to expose its Tasks menu, and then select Edit Templates.
From the Standard tab of the Toolbox, drag a FileUpload control and a Calendar control into the WebPartsTemplate section of the DeclarativeCatalogPart control.

Switch to Source view and inspect the source code of the CatalogZone control.

Notice that the DeclarativeCatalogPart control contains a WebPartsTemplate element with the two enclosed server controls that you will be able to add to your page from the catalog.

Note
If you have a custom control, this is the place to substitute it for one of the server controls in the example, although this requires steps beyond the scope of this walkthrough. For further details, see the code example in the documentation for the WebPart class.

Add a Title property to each of the controls that you added to the catalog, and set the property to the names shown in the following example. Even though the title is not a property you can normally set for these controls at design time, when a user adds these controls to a WebPartZone zone from the catalog at run time, they are each wrapped with a GenericWebPart control. This enables them to act as Web Parts controls. Therefore, they will be able to display titles.

The markup for the controls contained in the DeclarativeCatalogPart control will look like the following example:
<asp:DeclarativeCatalogPart ID="DeclarativeCatalogPart1" runat="server"> <WebPartsTemplate> <asp:Calendar ID="Calendar1" runat="server" title="My Calendar" /> <asp:FileUpload ID="FileUpload1" runat="server" title="Upload Files" /> </WebPartsTemplate> </asp:DeclarativeCatalogPart>
Save the page.

You can now test the catalog.

To test the Web Parts catalog

Load the page in a browser.
In the Display Mode menu, click Catalog.

The catalog titled Add Web Parts is displayed.
Drag the My Favorites control from the Main zone back to the top of the Sidebar zone.
In the Add Web Parts catalog, select both check boxes, and then select Main from the list of available zones
Click Add in the catalog.

The controls are added to the Main zone. If you want, you can add multiple instances of controls from the catalog to your page. The following figure shows the page with the file upload control and the calendar in the Main zone:

Controls added to Main zone from the catalog
In the Display Mode menu, click Browse.

The catalog disappears and the page is refreshed.
Close the browser and then load the page again.

The changes you made persist.

Next Steps

This walkthrough has illustrated the basic principles of using Web Parts controls on an ASP.NET Web page. Suggestions for further exploration include:

Create Web Parts controls that offer more sophisticated functionality than the static Web Parts from this walkthrough. You can create Web Parts controls as user controls or custom controls. For details, see the documentation for the WebPart class.

--------------------------------------------------------------------------------------------------------------------------

Source: https://msdn.microsoft.com/en-us/library/sk23dydw.aspx

SharePoint Tips and Tricks

Wednesday, March 22, 2017

Walkthrough: Creating a Web Parts Page