How to: Create a Top-Level Tab with Multiple Subtabs

Article
10/19/2016

Applies To: Windows Server 2012 Essentials, Windows Home Server 2011, Windows Storage Server 2008 R2 Essentials, Windows Small Business Server 2011 Essentials

You can create a top-level tab that contains multiple subtabs. The subtabs can be a mix of custom control subtabs and list view subtabs.

You create a top-level tab with multiple subtabs by performing the following procedures:

Complete the procedure listed in Create a Top-Level Tab, and ensure that you used the HSBSTopLevelTabTwoSubtabs template to create the tab.
Create a list view subtab
Create a custom control subtab
Install the top-level tab

Create a list view subtab

You create a list view subtab by performing the following procedures:

Create a page class
Create a business object
Create a list provider
Create the supporting classes

Create a page class

You must create a class that inherits the Page class to add a list view subtab to the Dashboard. The page object defines the panes that are visible to the administrator when using the subtab. The panes that are created by the page object include the list pane that lists business object data, a details pane that displays additional information about a specific business object, and a task pane that provides actions that can be performed for all business objects or a specific business object. To display the list pane, task pane, and details pane in the Dashboard, you must create a subtab and add it to a top-level tab.

To create a page class

In the SubTab project, open the SubTabPage.cs file.
You must provide identifying information for the page. Change the subtab name and description in the constructor of the class as well as the GUID passed to the base class’s constructor:
```
public class SubTabPage : ControlRendererPage  
{  
   public SubTabPage()  
      : base(new Guid([Insert new GUID here.]),   
      "SubTab Sample",   
      "SubTab Sample Description")  
   {  
   }  
}  
```
SubTab Sample is the name of your tab. SubTab Sample Description is the tool tip description for your tab that is displayed when the mouse hovers over the tab name.

Note

You must supply your own unique GUID. For more information about creating a GUID, see Create Guid (guidgen.exe) (https://go.microsoft.com/fwlink/?LinkId=116098).
The CreateContent method uses the Create method of the PageContent class to initialize a PageContent object. The PageContent object is used by the Dashboard to define the columns and groups in the list pane, to define the tasks that can be performed on business objects, and to define the additional detail information that will be displayed for business objects. Ensure that the CreateContent method references your list provider and the other supporting classes (the list provider and supporting classes are defined in following sections). The following code example shows how to override the CreateContent method:
```
protected override PageContent CreateContent()  
{  
   return PageContent.Create<YourBusinessObject>(  
      new SubTabListProvider(),  
      SubTabListColumns.CreateColumns(),  
      SubTabListGroupings.CreateGroupings(),  
      SubTabTasks.CreateTasks(),  
      SubTabDetails.GetDetails  
   );  
}  
```

(Optional) You can provide help information for the page. The following code example shows how to override the CreateHelpTopicInfo method:

protected override HelpTopicInfo CreateHelpTopicInfo()  
{  
   // Replace with a custom URL or CHM/HTML file path.  
   return new HelpTopicInfo(new Uri("https://servername/help"));  
}

You can also refer to help information in a compiled help file.

protected override HelpTopicInfo CreateHelpTopicInfo()  
{  
   HelpTopicInfo helpTopic = null;  
   helpTopic = new HelpTopicInfo(@"<path to help .chm file>",  
      @"/html/076d08c2.html");  
   return helpTopic;  
}

Save and build the solution.

Create a business object

A business object is a class that provides access to property values that are used to populate the page in the Dashboard.

Note

The class that is used in this section to provide business object data to the add-in is used only to demonstrate how to access business object data. In most cases, business objects will not need to be created when you create an add-in. Business object data will usually be provided using non-Microsoft SDKs that access business objects from applications that are being integrated into the Dashboard. Business object data can come from many sources, such as classes, databases, or services.

The YourBusinessObject class in this example provides information that is displayed in the list pane.

To create a business object class

In the SubTab project, open the YourBusinessObject.cs file. Add or change the properties that you want to include in your business object. The following code example shows the YourBusinessObject class with properties added:

public class YourBusinessObject  
{  
   private string _computerName;   
   public string ComputerName  
   {  
      get { return _computerName; }  
      set { _computerName = value; }  
   }  

   private string _networkName;  
   public string NetworkName  
   {  
      get { return _networkName; }  
      set { _networkName = value; }  
   }  

   private string _adminName;  
   public string AdminName  
   {  
      get { return _adminName; }  
      set { _adminName = value; }  
   }  

   private string _companyName;  
   public string CompanyName  
   {  
      get { return _companyName; }  
      set { _companyName = value; }  
   }  

   private string _description;  
   public string Description  
   {  
      get { return _description; }  
      set { _description = value; }  
   }      
}

On the Build menu, click Build Solution.

You use the YourBusinessObject object when you create the list provider for your list view subtab.

Create a list provider

To create a list provider, you must create a class that inherits the ListProvider class. You initialize an instance of the class when you create content for the page that will be displayed in the Dashboard. A ListProvider object can obtain business object data from various sources and use the data to populate the list that is displayed in the list pane of the page.

The list of business objects that is used by the Dashboard is initialized and managed internally, but you must add business objects to the list for the data to be available in the list pane of the page. To populate the list you must override the RefreshAndListenForUpdates method. You will also override the StopListeningForUpdates, GetObjectDisplayName, and GetObjectId methods. The following table provides more information about these methods.

Method	Description
RefreshAndListenForUpdates	Used to ensure that the data sources for business objects are accessible and to populate the provided list with information from those data sources.
StopListeningForUpdates	If your Dashboard add-in implements events that listen for updates, use this method to stop listening for updates and relinquish control of the list that is passed to RefreshAndListenForUpdates.
GetObjectDisplayName	Used to define the title of the details pane and the title of the task pane for selected business objects.
GetObjectId	Used by the Dashboard to uniquely identify each list item that is returned by the ListProvider object.

To create a list provider class

In the SubTab project, open the SubTabListProvider.cs file.

Change the code in the RefreshAndListenForUpdates method to represent the data for your business object. The following code example shows business objects that are defined with an administrator name, company name, computer name, and network name:

protected override void RefreshAndListenForUpdates(IList<YourBusinessObject> list)  
{  
   YourBusinessObject bObject = new YourBusinessObject();  
   bObject.AdminName = "User";  
   bObject.CompanyName = "Microsoft";  
   bObject.ComputerName = "Computer";  
   bObject.NetworkName = "MyComputer.Local";  
   list.Add(bObject);  

   bObject = new YourBusinessObject();  
   bObject.AdminName = "User2";  
   bObject.CompanyName = "Microsoft";  
   bObject.ComputerName = "Computer2";  
   bObject.NetworkName = "MyComputer.Local";  
   list.Add(bObject);  
}

Note

RefreshAndListenForUpdates is used to initialize the list of business objects and to refresh the list when requested by the user in the Dashboard. If your application add-in implements events that listen for updates, you would use the list that is passed to the RefreshAndListenForUpdates method to refresh the list.

You must override the StopListeningForUpdates, GetObjectDisplayName, and GetObjectId methods. The following code example shows how these methods can be overridden:

protected override void StopListeningForUpdates()  
{  
    // not listening for updates; nothing to do  
}  

protected override string GetObjectDisplayName(  
   YourBusinessObject businessObject)  
{  
   // return a string that contains the name that   
   // is displayed for the object  
   return businessObject.ComputerName;  
}  

protected override string GetObjectId(YourBusinessObject businessObject)  
{  
   // return a string that uniquely identifies   
   // the business object  
   return businessObject.ComputerName + "." + businessObject.NetworkName;  
}

Save and build the project.

Create the supporting classes

To simplify the definition of the page, the arguments of the Create method have been defined as separate classes. The classes that are listed in this section provide information and actions for different areas in the Dashboard. Change the values in these classes to represent the values of your add-in.

The following code example shows how columns are defined in the SubTabListColumns class:

  
static class SubTabListColumns  
{  
   public static ListColumnCollection<YourBusinessObject> CreateColumns()  
   {  
      ListColumnCollection<YourBusinessObject> columns =   
         new ListColumnCollection<YourBusinessObject>();  
      ListColumn<YourBusinessObject> column = null;  
  
      column = columns.Add("ComputerName", "ComputerName");  
      column.IsRequired = true;  
  
      column = columns.Add("AdminName", "AdminName");  
      column.IsRequired = true;  
  
      column = columns.Add("CompanyName", "CompanyName");  
      column.IsRequired = true;  
  
      return columns;  
   }  
}

The following code example shows how groupings are defined in the SubTabListGroupings class:

  
static class SubTabListGroupings  
{  
   public static ListGroupingCollection<YourBusinessObject> CreateGroupings()  
   {  
      var groupings = new ListGroupingCollection<YourBusinessObject>();  
  
      var grouping = groupings.Add(  
         "Network Name",  
         GetObjectListGroup  
      );  
  
      return(groupings);  
   }  
  
   private static ListGroup<YourBusinessObject> GetObjectListGroup(YourBusinessObject businessObj)  
   {  
      var group = new ListGroup<YourBusinessObject>(businessObj.NetworkName);  
      return(group);  
   }  
}

The following code example shows how tasks are defined in the SubTabTasks class:

  
static class SubTabTasks  
{  
   public static TaskCollection CreateTasks()  
   {  
      TaskCollection tasks = new TaskCollection();  
  
      tasks.Add(CreateCustomAction());  
      tasks.Add(new ProcessTask<YourBusinessObject>("Selection Task", "notepad.exe"));  
  
      return tasks;  
   }  
  
   private static AsyncUiTask CreateCustomAction()  
   {  
      var task = new AsyncUiTask("Custom action",   
         delegate(object sender)  
         {  
            MessageBox.Show("Custom action");  
            return (null);  
         }  
      );  
  
      return (task);  
   }  
}

You can define a global task (a task that is not associated to a selected item) that is also included in the Common Tasks List. To do this, you must create a GUID with which the task can be identified, and you must add the identifier to a dictionary object for the task. The following code example shows how to define the task to be used in the Common Tasks List:

  
ProcessTask myTask = new ProcessTask ("Page Task", "notepad.exe");  
Dictionary<string, string> dictionaryMyTaskId = new Dictionary<string, string>();  
string myTaskGuid = "457B6016-A97B-4A25-BD02-949F6134E1FC";  
dictionaryMyTaskId.Add("TaskId", myTaskGuid);  
myTask.Tag = dictionaryMyTaskId;  
tasks.Add(myTask);

For more information about adding tasks to the Common Tasks List, see Extend Setup, Quick Status, and Help.

Note

Only global tasks can be added to the Common Tasks List. Object specific tasks cannot be added to list. The task identifier must be a Guid and it must be added to the dictionary object with the TaskId key.

The following code example shows how details are defined in the SubTabDetails class:

  
static class SubTabDetails  
{  
   public static DetailColumnCollection GetDetails(YourBusinessObject businessObj)  
   {  
      DetailColumnCollection columns = new DetailColumnCollection();  
      DetailColumn column = new DetailColumn();  
      DetailGroup group = new DetailGroup("Computer Information");  
      group.Add("Computer Name", businessObj.ComputerName);  
      group.Add("Network Name", businessObj.NetworkName);  
  
      column.Add(group);  
      columns.Add(column);  
  
      return columns;  
   }  
}

Create a custom control subtab

You can now use the CustomSubTabPage.cs file to create a custom control subtab. For more information about creating a custom control subtab, see How to: Create a Top-Level Tab with a Windows Forms Custom Control or How to: Create a Top-Level Tab with a WPF Custom Control.

Install the top-level tab

After you define the top-level tab and subtabs, you can install the tabs. To install the tabs, perform the procedure listed in How to: Install a Top-Level Tab.

Important

If your top-level tab contains subtabs with custom controls, the basedir attribute is not used in the .addin file.

For more information about the installation requirements of add-ins, see Add-In Installation Requirements.

Share via

How to: Create a Top-Level Tab with Multiple Subtabs

Create a list view subtab

Create a page class

To create a page class

Create a business object

To create a business object class

Create a list provider

To create a list provider class

Create the supporting classes

Create a custom control subtab

Install the top-level tab

Additional resources