How to: Add a New UI Page to a Wizard

Applies To: Windows Server 2012 Essentials

To add a new UI page to a dialog or wizard, you must first create an AddinPageContent object, which contains your custom control. Then, create an adorner object that inherits from FormContentAdorner and IHostedEmailExtension. You can then use your new adorner pass your custom UI page to the built-in UI. You can also use the adorner object to create pre- and post- execution tasks, such as retrieving or refreshing data on the UI page. Once you have created the AddinPageContent and the adorner, you can link your adorner to a specific UI element though the .addin file. For more information, see How to: Install the UI Update.

To create the AddinPageContent object that contains your custom control

1. Create your custom control in an associated project within your solution.

   In this case, the custom control is called DistributionGroupControl, and is a tab control. This control is designed to display a hosted email distribution group list in the User Properties dialog.

2. Create an AddinPageContentobject.

   The AddinPageContent object is essentially a wrapper for your custom control, and contains a number of event handlers and properties which are useful for the main page to hook into.

   public class DistributionGroupTabContent : AddinPageContent  
       {  
       }  
   

3. Implement the constructor.

   Note the use of the property bag to pass information to the control. In this case, UI elements (such as the dock and autoscroll) are being set here, and then passed on later to the adorner. Also note that the developers chose to use the PageInitializing events to load the data, rather than loading the information right here.

   DistributionGroupControl tabControl = null;  
   public DistributionGroupTabContent(FormPropertyBag propertyBag)  
       : base(propertyBag)  
   {  
       tabControl = new DistributionGroupControl(base.PropertyBag);  
       tabControl.Dock = DockStyle.Fill;  
       tabControl.AutoScroll = false;  
       // ATTENTION:   
       // the reason of loading data in page initiailzing coz that we need the UserName in propertyBag which will be   
       // filled in with data after the controls are created. Therefore, we cannot get data we want in this ctor.  
       this.PageInitializing += (object sender, EventArgs e) => { this.tabControl.StartLoadingData(); };  
       this.PageValidating += (object sender, CancelEventArgs e) =>  
           {  
               // Putting the data here coz this method is called in UI thread  
               base.PropertyBag.AddinData[Constants.ExtendedParam_DGs] = tabControl.GetDistributionGroupsString();  
           };  
   }  
   

4. Override the CreateControl method to create the control.

   In this instance, the constructor will be called in the adorner object.

   public override Control CreateControl()  
   {  
       return tabControl;  
   }  
   

5. Hook up any necessary events.

   public override event EventHandler PropertyChanged  
   {  
       add  
       {  
           tabControl.PropertyChanged += value;  
       }  
       remove  
       {  
           tabControl.PropertyChanged -= value;  
       }  
   }  
   

To add the UI page to an existing dialog or wizard

1. Create an object that inherits from FormContentAdorner and IHostedEmailExtension.

   FormContentAdorner allows you to hook into an existing UI dialog or wizard, while IHostedEmailExtension allows you to associate your UI add-in with your add-in.

   public class DistributionGroupAdorner : FormContentAdorner, IHostedEmailExtension  
       {  
       }  
   

2. Implement the constructor, using the GUID, display name, and description of the UI element you wish to hook into.

   public DistributionGroupAdorner()  
       : base(new Guid("B00F3F8D-176B-4A85-A1C9-3022A6E5B9BC"), Resources.DGAdorner_Name, Resources.DGAdorner_Des)  
   {  
   }  
   

3. Override the CreatePages method, using your custom control, wrapped in an AddinPageContent object.

   In this context, DistributionGroupTabContent is an a tab control described in the procedure below. Note the use of the FormPropertyBag to pass initiation data to the control.

   public override ICollection<AddinPageContent> CreatePages(FormPropertyBag propertyBag)  
   {  
       List<AddinPageContent> list = new List<AddinPageContent>();  
       content = new DistributionGroupTabContent(propertyBag)  
       {  
           Title = Resources.DGTab_Name,  
           HelpLink = null,  
           HelpLinkText = null  
       };   
       list.Add(content);  
       return list;  
   }  
   

4. Override the CreatePostExecutionTasks method, if you need to add any relevant tasks.

   public override ICollection<Task> CreatePostExecutionTasks(FormPropertyBag propertyBag)  
   {  
       return null;  
   }  
   

5. Override the CreatePreExecutionTasks method, if you need to add any relevant tasks.

   In this case, a common pre-execution task is to check to update the data in the control before displaying the content.

   public override ICollection<Task> CreatePreExecutionTasks(FormPropertyBag propertyBag)  
   {  
       if (content == null) return null;  
       List<Task> tasks = new List<Task>();  
       tasks.Add(new Task(() => content.UpdateDistributionGroups()));  
       return tasks;  
   }  
   

6. Implement GetAddinId.

   This method is called by the form to identify which add-in your UI is associated with.

   public Guid GetAddinId()  
   {  
       return Constants.AdaptorId;  
   }