[ Download Sample Code ]

ASP.NET 2.0 ships with a public release of the Microsoft Portal Framework (MSPF). Previously available only to SharePoint developers, the Portal Framework is centered on the concept of Web Parts. This article is the first in a series aimed at introducing the MSPF from a development and implementation perspective.

System Requirements:

• .NET Framework 2.0 Beta 2
• Visual Studio 2005 Beta 2
• SQL Server Express or SQL Server 2005 Beta 2.0

Note: It is imperative that you have a working installation of either SQL Express or SQL Server 2005 Beta 2.0. The Microsoft Portal Framework uses a SQL database to persist personalization information.

Anatomy of a Portal

Portal applications are applications with a niche in mind. That may sound overly simplified, but is essentially accurate. On the web, portals are most commonly experienced as a site devoted to a general topic such as www.fishingworks.com, or as a site devoted to aggregating your general interests such as www.google.com/ig. In the business world, domain-specific portals have existed for decades. They weren’t necessarily web based, but they fit the general definition of being a niche-based searchable information store. Most often they are branded by their specific function such as CRM, BI, or Reporting, but when it boils down to it, a portal is simply a targeted information aggregation tool that typically provides a custom search capability.

Portals by definition do not require personalization services, but today’s user will likely expect some level of personalization to be provided. Personalization is a broad term that may mean persistent UI layout customization or content control selection. Ultimately it comes down to this: the application should recognize the user and remember any runtime customizations the user has defined within the system.

The MSPF provides this type of behavior via a family of controls that is generically referred to as Web Parts. In fact, a Web Part is just one of many controls used to tie this suite of functionality together. The controls that will be covered in this article are:

• WebPartManager
• WebPart
• WebPartZone
• CatalogZone
• DeclarativeCatalogPart

WebPartManager and DisplayModes

Any page that uses web parts will require a WebPartManager instance. The WebPartManager member list breaks down into two categories: Event members and DisplayMode fields. Unfortunately, to cover the Event members in detail is beyond the scope of this article. Look for more on that topic in subsequent articles. What will be of interest to this discussion is an explanation of DisplayMode fields. As might seem evident, they control the mode of the page. When the user posts back and changes the display mode of a page, the page will render itself with one or several mode-specific controls visible. The newly visible controls will provide the user with some array of personalization options depending on the mode selected. Below is a synopsis of each mode.

• BrowseDisplayMode – Should be the default mode of most pages. This is the mode that allows the user to browse the page for its normal purpose.
• DesignDisplayMode – User can drag and drop web parts to different web part zones.
• EditDisplayMode – Allows customization of Appearance, Behavior, Layout, and Properties.
• CatalogDisplayMode – Displays a list of available web parts. Allows the user to add and remove web parts to zones at runtime.
• ConnectDisplayMode – Displays options for modifying connection settings between web parts.

This article will address changing the display mode of a page and adding controls to zones from a catalog. Each other mode will be addressed in later installments of the series.

Setting up the Palette

The sample project contains two web user controls: Search.ascx and AccountManagement.ascx. The code-behind files for these controls contain no functionality. There is no need to review them. The controls exist solely as a means of providing some content/visual elements that can be managed via the MSPF.

Search.ascx is a simple search control that (theoretically) allows users to search for accounts by a number of attributes. It displays a list of search results. The user can click on the record of interest and the AccountManagement.ascx control would populate with the appropriate detail information. By default the page loads with the Search control above the AccountManagement control. This creates a problem because if the user searches on a value with a large hit ratio the detail control will be pushed of the bottom of the screen. The usability team has decided this is a no no, but some users are so accustomed to it that they complain when the default control layout is changed. It is decided the solution is to allow users to customize page control rendering order via the web part catalog. In order for users to see catalog options they must be able to change the display mode of the page.

Below is the code for the web form. Follow the step-by-step instructions that you see in the comments to create your own portal starter page. The comments have been added above relevant blocks of controls. Currently the Visual Studio 2005 Beta 2.0 IDE will consider comments within a Zone declaration to be a schema violation. Also, note that a Title attribute has been added to numerous controls. Another Beta anomaly is the lack of IntelliSense and schema validation support for this attribute, despite its wide documentation. If you rely on IntelliSense to remind you of which attributes to set on controls in the web form view, you will get no help with this one.

<%@ Page Language="C#" AutoEventWireup="true" CodeFile="Article1.aspx.cs" 
    Inherits="Article1" %>
<%@ Register Src="Search.ascx" TagName="Search" TagPrefix="SP" %>
<%@ Register Src="AccountManagement.ascx" TagName="AccountManagement" TagPrefix="SP" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
  <title>StarPort - Portal Solutions</title>
  <link href="Style.css" rel="stylesheet" type="text/css" />
</head>
<body>
  <form id="form1" runat="server">
  <!-- STEP 1 Add a WebPartManager to the web form just inside the form tag. -->
  <asp:WebPartManager ID="webPartManager" runat="Server" />
  <table width="90%" align="Center" border="0">
    <tr>
      <th colspan="2" class="header" valign="Bottom" >
        <H2>StarPort<sub>Portal Solutions</sub></H2>
      </th>
      <td width="20%" class="header" valign="Bottom" align="Right">
        <!-- STEP 2 Add a DropDownList to the header to allow the user to toggle the 
             mode of the Portal. -->
        <asp:DropDownList ID="ddlDisplayMode" runat="Server" >
          <asp:ListItem Value="Browse">Browse</asp:ListItem>
          <asp:ListItem Value="Catalog">Catalog</asp:ListItem>
        </asp:DropDownList>
        <br />
        <!-- STEP 3 Add a LinkButton to apply the selection made in the DropDownList.
             -->
        <asp:LinkButton ID="lnkChangeMode" runat="Server" ForeColor="white"
            OnClick="lnkChangeMode_Click">
          Switch Mode
        </asp:LinkButton>
      </td>
    </tr>
    <tr>
      <td width="20%" valign="top">
        <!-- STEP 4 Add a CatalogZone.  This is the required top level control for all
             CatalogPart controls. -->
        <!-- STEP 5 Create a ZoneTemplate.  All Zone controls require a ZoneTemplate
             container.   -->
        <!-- STEP 6 Create a DeclarativeCatalogPart to provide the user with a catalog
             of controls to select and remove. -->
        <!-- STEP 7 Creat WebPartsTemplate container to hold all ZoneTemplates. -->
        <!-- STEP 8 Create a ZoneTemplate for each control that should be exposed via 
             the catalog. Inside the ZoneTemplate create an instance of the desired 
             control. -->
        <asp:CatalogZone ID="catMain" Title="Part Catalog" runat="Server">
          <ZoneTemplate>
            <asp:DeclarativeCatalogPart Title="Available Parts" ID="catToolBox"
                runat="Server">
              <WebPartsTemplate>
                <ZoneTemplate>
                  <SP:Search ID="ctlSearch" runat="Server" Title="Search" />
                </ZoneTemplate>
                <ZoneTemplate>
                  <SP:AccountManagement ID="ctlAccountManagement" runat="Server"
                      Title="Account Management" />
                </ZoneTemplate>
              </WebPartsTemplate>
            </asp:DeclarativeCatalogPart>
          </ZoneTemplate>
        </asp:CatalogZone>
        </td>
      <td width="60%"></td>
      <td width="20%" valign="Top">
        <!-- STEP 9 Create a WebPartZone in the area of the page you wish to allow 
             WebParts to be added and removed. -->
        <!-- STEP 10 Create a ZoneTemplate.  WebParts must exist within a ZoneTemplate
             Container. -->
        <!-- STEP 11 To Set the WebPartZone styles switch to design view. Select the
             WebPartZone control. Click the arrow in the right upper corner of the 
             control border. Select AutoFormat from the popup. Choose any one of the
             default styles. -->
        <asp:WebPartZone ID="WebParts" runat="Server" BorderColor="#CCCCCC" 
          Font-Names="Verdana" Padding="6" Height="436px" Width="159px">
          <ZoneTemplate>
  
          </ZoneTemplate>
          <PartChromeStyle BackColor="#F7F6F3" BorderColor="#E2DED6" 
             Font-Names="Verdana" ForeColor="White" />
          <MenuLabelHoverStyle ForeColor="#E2DED6" />
          <EmptyZoneTextStyle Font-Size="0.8em" />
          <MenuLabelStyle ForeColor="White" />
          <MenuVerbHoverStyle BackColor="#F7F6F3" BorderColor="#CCCCCC" 
            BorderStyle="Solid" BorderWidth="1px" ForeColor="#333333" />
          <HeaderStyle Font-Size="0.7em" ForeColor="#CCCCCC"
              HorizontalAlign="Center" />
          <MenuVerbStyle BorderColor="#5D7B9D" BorderStyle="Solid" BorderWidth="1px"
              ForeColor="White" />
          <PartStyle Font-Size="0.8em" ForeColor="#333333" />
          <TitleBarVerbStyle Font-Size="0.6em" Font-Underline="False"
              ForeColor="White" />
          <MenuPopupStyle BackColor="#5D7B9D" BorderColor="#CCCCCC" BorderWidth="1px" 
            Font-Names="Verdana" Font-Size="0.6em" />
          <PartTitleStyle BackColor="#5D7B9D" Font-Bold="True" Font-Size="0.8em"
              ForeColor="White" />
        </asp:WebPartZone>
      </td>
    </tr>
    <tr>
      <td colspan="3">Copyright 2005 StarPort Portal (Just for Show)</td>
    </tr>
  </table>
</form>
</body>
</html>

protected void lnkChangeMode_Click(object sender, EventArgs e)
{
    string mode = ddlDisplayMode.SelectedValue;
    WebPartDisplayMode displayMode = webPartManager.SupportedDisplayModes[mode];
    if (displayMode != null)
    {
        webPartManager.DisplayMode = displayMode;
    }
}

As you can see from the code above, the WebPartManager provides us with the means to access the page’s currently supported display modes using the WebPartManager.SupportedDisplayModes indexer as well as a means of getting and setting the current DisplayMode via the WebPartManager.DisplayMode property. The means of accessing the current display mode is a little indirect so here it is in a little more detail.

• First, you set an inline string variable equal to the selected value of the DropDownList. In this example the variable is called mode. This means the values you allow in the DropDownList must specifically match all or some of the possible DisplayMode values. The acceptable DisplayMode values are Browse, Design, Edit, Catalog, and Connect.
• Next, you attempt to create an inline WebPartDisplayMode instance. But instead of calling new WebPartDisplayMode() you try initializing the instance by calling WebPartManager.SupportedDisplayMode. Make sure to pass the mode variable inside the brackets.
• If the selected display mode is supported you will have succeeded in creating a WebPartDisplayMode instance. Simply do a null check on the WebPartDisplayMode instance and if the mode is supported set the WebPartManager.DisplayMode equal to the user selected display mode.

Practice Adding Controls to Zone

Now browse the page, change the drop-down list to Catalog and click on Switch Mode. You should see a catalog zone on the left-hand side, just as you did in the design view of the page. In the catalog zone you should see all the controls that we defined in the CatalogZone ZoneTemplates. At the bottom of the catalog zone you will see a drop-down list that lists all available WebPartZones. Click the check box next to one of the control names and then click Add. The page should refresh and the control you selected should appear in the right-hand column where we defined the WebPartZone. Play around. You will notice some interesting things. Each control by default now has an arrow in the upper right hand corner. Click the arrow and you will see a list of familiar menu options. This is because when a control is added to a WebPartZone it is by default wrapped in a WebPart container class that provides simple common functionality which includes this menu. It also provides hooks into the larger MSPF event model that allows for communication between WebParts.

Now take her for a ride. Click on all the menu options. Try to add the same control to the WebPartZone twice. Switch back and forth between Browse and Catalog.

Conclusion

We went through some very basic, focused actions here, but touched on a wide variety of topics. I am sure you have a ton of questions about the things we didn’t cover. Rest assured there is more information coming in future articles, but hopefully you have had enough of an introduction to get started playing around with your options. Thanks for reading.

Rock.On(); Code.On();