View the Manager Dashboard Use Case

The manager dashboard is an example of how standard SharePoint Web Parts, custom Web Parts, and user controls can be incorporated into a SharePoint application. To see the manager's view of the dashboard, log on as spgmanager. From the Quick Launch, select Manager Dashboard. The dashboard uses both custom Web Parts and Web Parts that are provided by SharePoint. Figure 1 illustrates an example of the dashboard.

Figure 1
The manager dashboard

The four Web Parts on the page display the following:

• They display pending registrations, which is a standard SharePoint List View Web Part.
• They display registration approval tasks, which is a standard SharePoint List View Web Part.
• They display training budget information, which is a custom Web Part.
• They display direct reports information for the current user, which is a user control that is wrapped in a custom Web Part.

For guidance on deciding between standard and custom Web Parts, see Using Standard and Custom Web Parts. For more information about Web Parts, see ASP.NET Web Part Controls on MSDN.

Pending Registration and Registration Approval Tasks Web Parts

The pending registrations and registration approval tasks Web Parts are SharePoint List View Web Parts. The pending registrations Web Part is based on a custom view of the registrations list and the approval tasks Web Part is based on the registration approval tasks list view. Because the data for these two Web Parts is in SharePoint, you can use the standard List View Web Part combined with custom views to display the data. There is no need to develop a custom user interface.

The pending registrations Web Part is based on the following code that defines the custom registrations list view. The code is located in the List Definitions\RegistrationListDefinition\schema.xml file in the Contoso.TrainingManagement project.

...        
<ViewFields>
    <FieldRef Name="LinkTitle">
    </FieldRef>
    <FieldRef Name="User">
    </FieldRef>
    <FieldRef Name="RegistrationStatus">
    </FieldRef>
</ViewFields>
<Query>
    <Where>
            <Eq>
                <FieldRef Name="RegistrationStatus" />
                <Value Type="Text">Pending</Value>
            </Eq>
    </Where>
    <OrderBy>
        <FieldRef Name="Modified" Ascending="FALSE">
        </FieldRef>
    </OrderBy>
</Query>
....

The List View definition creates an instance of a List View Web Part on the Manage.aspx page that displays the custom registrations list view. The code for the definition is located in the Forms\ManagerDashboard\ManagerDashboardElement.xml file of the Contoso.TrainingManagement project.

<View List="Lists/Registrations" BaseViewID="3" DisplayName="Pending Registrations"
            Name="Pending Registrations" RecurrenceRowset="TRUE" WebPartZoneID="Left"
            WebPartOrder="1">
   <![CDATA[
        <WebPart xmlns=https://schemas.microsoft.com/WebPart/v2>
            <Assembly>Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral,
               PublicKeyToken=71e9bce111e9429c</Assembly>

            <TypeName>Microsoft.SharePoint.WebPartPages.ListViewWebPart</TypeName>
            <Title>Pending Registrations</Title>
       </WebPart>
            ]]>    
</View>

The code for the registration approval tasks Web Part is similar to the code for the pending registrations Web Part.

Training Budget and Direct Reports Web Parts

The training budget and direct reports Web Parts are custom Web Parts. The training budget Web Part accesses the Accounting Management service for financial information for the selected cost center. This functionality requires a custom Web Part because the accounting data is not stored in SharePoint. Therefore, it requires a custom user interface to display it.

The direct reports Web Part is a combination of a custom user control and a custom Web Part. The user control accesses the HR Management service to display the direct reports for the current user. The custom Web Part wraps the user control and allows it to be placed inside of a Web Part zone on the Web Part page.

Including a custom Web Part on a Web Part Page has the following four phases:

1. The code is compiled and deployed. This installs the Web Part in SharePoint.
2. Developers can place the Web Part on the manager dashboard in one of two ways. They can either use code or the File element definitions in the ManageElement.xml file.
3. At run time, the OnInit method executes and creates the Web Part layout.
4. When the page loads, the OnLoad method populates the Web Part with the data.

These steps are discussed in the next section.

Training Budget Web Part

[Guid("1e98f121-e107-4301-854a-0db8ba88385b")]
public class TrainingBudgetWebPart : 
       System.Web.UI.WebControls.WebParts.WebPart, ITrainingBudgetView
{
   /// ...
}

The Contoso.TrainingManagement project also contains an XML file named TrainingBudget.webpart. This is shown in the following code.

<?xml version="1.0" encoding="utf-8"?>
<webParts>
  <webPart xmlns="https://schemas.microsoft.com/WebPart/v3">
    <metaData>
      <!--
      The following Guid is used as a reference to the web part class, 
      and it will be automatically replaced with actual type name at deployment time.
      -->
      <type name="1e98f121-e107-4301-854a-0db8ba88385b" />
      <importErrorMessage>Cannot import Training Budget Web Part.</importErrorMessage>
    </metaData>
    <data>
      <properties>
        <property name="Title" type="string">Contoso Training Budget</property>
        <property name="Description" type="string">The Contoso Training Budget Web Part will display total budget, remaining budget, and a list of transactions, grouped by cost center.</property>
      </properties>
    </data>
  </webPart>
</webParts>

The Guid attribute of the TrainingBudgetWebPart class matches the GUID in the TrainingBudgetWebPart.xml file. When the project is deployed, this GUID enables Visual Studio extensions for Windows SharePoint Services to add the correct type information in the Web Part definition. The Web Part is installed in the SharePoint Web Part gallery.

The Web Parts are placed on the manager dashboard page with File element definitions. The following is the XML code that locates the Training Budget Web Part and Direct Reports Web Part. It is located in Forms\ManagerDashboard\ManageElement.xml file.

<AllUsersWebPart WebPartZoneID="Right" WebPartOrder="1">
  <![CDATA[
    <webParts>
      <webPart xmlns="https://schemas.microsoft.com/WebPart/v3">
        <metaData>
          <type name="Contoso.TrainingManagement.WebParts.TrainingBudgetWebPart,
                 Contoso.TrainingManagement, Version=1.0.0.0, Culture=neutral,
                    PublicKeyToken=9f4da00116c38ec5" /> 
          <importErrorMessage>Cannot import Training Budget Web
                 Part.</importErrorMessage> 
        </metaData>
        <data>
          <properties>
            <property name="Title" type="string">Training Budget</property> 
            <property name="Description" type="string">The Training Budget Web Part
 will display total budget, remaining budget, and a list of transactions, grouped by cost center.</property> 
          </properties>
        </data>
      </webPart>
    </webParts>
  ]]>
</AllUsersWebPart>
<AllUsersWebPart WebPartZoneID="Right" WebPartOrder="2">
  <![CDATA[
    <webParts>
      <webPart xmlns="https://schemas.microsoft.com/WebPart/v3">
        <metaData>
          <type name="Contoso.TrainingManagement.WebParts.DirectReportsWebPart,
                 Contoso.TrainingManagement, Version=1.0.0.0, Culture=neutral,
                      PublicKeyToken=9f4da00116c38ec5" /> 
          <importErrorMessage>Cannot import Direct Reports Web
                  Part.</importErrorMessage> 
        </metaData>
        <data>
          <properties>
            <property name="Title" type="string">Direct Reports</property> 
            <property name="Description" type="string">The Direct Reports Web Part
displays all direct reports for the current user.</property> 
          </properties>
        </data>
      </webPart>
    </webParts>
  ]]>
</AllUsersWebPart>

The type information is included in this file because, unlike the Webpart.xml file, it is not maintained by Visual Studio extensions for Windows SharePoint Services.

The Web Parts are installed as part of the solution using modules in the TrainingBudgetWebPart.xml and DirectReportsWebPart.xml files. The modules install the files to the _catalogs/wp folder, which is the location of the Web Part Gallery. After the Web Parts are in the gallery, they are declaratively added to the page with the AllUsersWebPart elements. These are in the Forms\Manage\ ManageElement and Forms\Default\DefaultElement XML folder.

At run time, the CreateChildControls method creates the UI elements that comprise the Web Part. This is shown in the following code. The code is located in the TrainingBudgetWebPart.cs file in Contoso.TrainingManagement\WebParts\TrainingBudgetWebPart project.

protected override void CreateChildControls()
{
    base.CreateChildControls();

    layout = new Panel();
    totalBudget = new Label();
    totalBudget.Attributes.Add("name", "TotalBudget");
    remainingBudget = new Label();
    remainingBudget.Attributes.Add("name", "RemainingBudget");
    costCenters = new DropDownList();
    costCenters.Attributes.Add("name", "CostCenters");
    costCenters.AutoPostBack = true;
    costCenters.SelectedIndexChanged += new EventHandler(costCenters_SelectedIndexChanged);

    transactions = new GridView();
    transactions.Attributes.Add("name", "Transactions");

    Label label = new Label();
    label.Text = "Cost Center: ";
    layout.Controls.Add(label);
    layout.Controls.Add(costCenters);
    layout.Controls.Add(new LiteralControl("<br />"));

    label = new Label();
    label.Text = "Total Budget: ";
    layout.Controls.Add(label);
    layout.Controls.Add(totalBudget);
    layout.Controls.Add(new LiteralControl("<br />"));

    label = new Label();
    label.Text = "Remaining Budget: ";
    layout.Controls.Add(label);
    layout.Controls.Add(remainingBudget);
    layout.Controls.Add(new LiteralControl("<br />"));

    label = new Label();
    label.Text = "Transactions";
    layout.Controls.Add(label);
    layout.Controls.Add(new LiteralControl("<br />"));

    layout.Controls.Add(transactions);

    this.Controls.Add(layout);
}

This code demonstrates how to programmatically lay out a Web Part. There is no Visual Studio designer support for Web Parts.

The OnLoad method executes when the page loads. The code is located in the TrainingBudgetWebPart.cs file in the Contoso.TrainingManagement\WebParts\ TrainingBudgetWebPart folder.

protected override void OnLoad(EventArgs e)
{
    base.OnLoad(e);

    if ( !Page.IsPostBack )
    {
        presenter.SetCostCenterSource();
        costCenters.DataBind();
        presenter.SetTransactionSource();
        transactions.DataBind();
    }            
}       

The OnLoad method populates the Web Part's data controls. It uses a presenter class named TrainingBudgetPresenter to do this. The following code shows the TrainingBudgetPresenter class. This code is found in the WebParts\TrainingBudgetWebPart\TrainingBudgetPresenter.cs file of the Contoso.TrainingManagement project.

public TrainingBudgetPresenter(ITrainingBudgetView view)
{
    ServiceLocator serviceLocator = ServiceLocator.GetInstance();

    this.view = view;
    this.acct = serviceLocator.Get<IAccountingManager>();
    this.hr = serviceLocator.Get<IHRManager>();
}

public void SetCostCenterSource()
{
    List<string> costCenters = hr.GetCostCenters();
    view.CostCenters = costCenters;                                 
}

public void SetTransactionSource()
{
    string costCenter = view.CostCenter;

    view.TotalBudget = acct.GetBudget(costCenter, "Training");
    view.RemainingBudget = acct.GetRemainingBudget(costCenter, "Training");
    view.Transactions = acct.GetTransactions(costCenter, "Training");
}

This code shows how the Accounting Management service is invoked to get the data required by the Training Budget Web Part.

Direct Reports Web Part

The Direct Reports Web Part is similar to the Training Budget Web Part. The difference is that instead of programmatically creating the UI elements, it embeds a user control. The CreateChildControls method performs this function. It is shown in the following code. This code is found in the WebParts\DirectReportsWebPart\DirectReportsWebPart.cs file of the Contoso.TrainingManagement project.

protected override void CreateChildControls()
{
    base.CreateChildControls();

    try
    {
        DirectReports directReports =  
           (DirectReports)Page.LoadControl(
                 "~/_controltemplates/TrainingManagement/DirectReports.ascx");
        directReports.Web = SPContext.Current.Web;
        directReports.LoginName = SPContext.Current.Web.CurrentUser.LoginName;
        directReports.ShowLogin = this.showLogin;
        this.Controls.Add(directReports);
    }
    catch ( HttpException ex )
    {
        this.Controls.Add(new LiteralControl("<br />An unexpected error occurred loading Web Part. " + ex.Message));
    }    
}

The advantage of a user control is that it allows you to use the Visual Studio design surface. This option is not available for Web Parts. To learn how to wrap a user control in a Web Part, see How to: Wrap a User Control Inside of a Web Part for SharePoint.

The Direct Reports Web Part contains a custom (programmer-provided) property named Show Login Name. The following code example, from the Web Parts\DirectReportsWebPart\DirectReportsWebPart.cs file in the Contoso.TrainingManagement project, exposes a user control property through a Web Part property.

private bool showLogin = false;

[Personalizable(PersonalizationScope.Shared)]
[WebBrowsable(true)]                
[WebDisplayName("Show Login Name")]
[WebDescription("Show login name for direct reports.")]
[SPWebCategoryName("Development")]
public bool ShowLogin
{
    get
    {
        return showLogin;
    }
    set
    {
        this.showLogin = value;
    }
}     

The property definition uses custom attributes provided by SharePoint to allow the property to be recognized by SharePoint at run time.The property value is used within the CreateChildControls method to modify the embedded user control.

Employee View of Manager Dashboard

When employees log on to the Training Management application, they can see the manager dashboard. However, employees have insufficient privileges to view the registration approval tasks. Figure 2 illustrates an example of the employee's view of the manager dashboard.

Figure 2
Employee view of management dashboard

To provide feedback, get assistance, or download additional, please visit the SharePoint Guidance Community Web site.

Copyright © 2008 by Microsoft Corporation. All rights reserved.