How to: Add a New Navigation Group and Move a Folder into that Group

You can use the Create method of the NavigationGroups collection to create custom navigation groups for a NavigationModule object. Once added, you can then use the Add method of the NavigationFolder object to move an existing navigation folder into the custom navigation group. Only one NavigationFolder object can be associated to a given Folder object at any time so using the Add method to create a new NavigationFolder object in a different NavigationGroup deletes the existing NavigationFolder object for the specified Folder object before the method creates a new navigation folder in the specified navigation group.

This sample provides the following two routines to customize the folder context menu for a task folder, allowing the user to move the selected folder to a custom navigation group named "Company Folders":

• An event handler routine that, when the FolderContextMenuDisplay event for the Application object occurs, adds a new menu item to the bottom of the selection context menu.
• An action routine, associated with the menu item, that retrieves a NavigationGroup object reference for the "Company Folders" custom navigation group and then moves the selected folder to that navigation group.

The event handler routine performs the following actions:

1. The event handler first creates a CommandBarButton object in the command bar returned by the CommandBar parameter of the FolderContextMenuDisplay event, but only if the DefaultItemType property of the selected Folder object is set to olTaskItem.

2. It then configures the CommandBarButton:

3. 1. The OnAction property is set to "Project1.ThisOutlookSession.MoveToCompanyFolders", the full name of the action that the menu item will take when selected. The value of this property corresponds to the full name of the action routine in this sample.
   2. The Parameter property is set to the value of the EntryID for the selected Folder object, which is retrieved from the Folder parameter of the FolderContextMenuDisplay event.
   3. The Caption property is set to "&Move to ""Company Folders" group".
   4. The Tag property is set to "MoveToCompanyFolders".

After the event handler routine finishes execution, the folder context menu is displayed. If the Move to "Company Folders" group menu item appended to the end of the folder context menu is selected, the action routine that was specified in the OnAction property of the CommandBarButton representing that menu item is called. The action routine then performs the following actions:

1. The action routine first retrieves the entry ID of the selected folder from the Parameter property of the object returned by the Application.ActiveExplorer.CommandBars.ActionControl property. This value is used to retrieve a Folder object reference for the selected folder.
2. It then checks if a value was retrieved from the Parameter property. If no value was retrieved, a message is displayed indicating that the selected folder could not be retrieved.
3. If a value was retrieved, a Folder object reference representing the selected folder is retrieved using the GetFolderFromID method of the NameSpace object.
4. If a valid folder was not retrieved, the action routine displays a dialog box describing the issue. If a valid folder was retrieved, the action routine then performs the following actions:
   1. The action routine obtains a reference to the NavigationPane object for the active explorer and uses the GetNavigationModule method of the NavigationModules collection to obtain a TasksModule object reference.
   2. The action routine then attempts to obtain the NavigationGroup object named "Company Folders". If the NavigationGroup object cannot be obtained, the routine then creates a new NavigationGroup object named "Company Folders" by using the Create method of the NavigationGroups collection.
5. Finally, the action routine uses the Add method of the NavigationFolders collection for the NavigationGroup object to move the selected navigation folder into the navigation group.

  Private Sub Application_FolderContextMenuDisplay( _
    ByVal CommandBar As Office.CommandBar, _
    ByVal Folder As Folder)
Dim objButton As Office.CommandBarButton

On Error GoTo ErrRoutine

If Folder.DefaultItemType = olTaskItem Then
    ' Add a new button to the bottom of the CommandBar
    ' (which represents the selection context menu.)
    Set objButton = CommandBar.Controls.Add( _
        msoControlButton)
    
    With objButton
        .OnAction = _
            "Project1.ThisOutlookSession.MoveToCompanyFolders"
        .Parameter = Folder.EntryID
        .Caption = "&Move to ""Company Folders"" group"
        .Tag = "MoveToCompanyFolders"
    End With
End If

EndRoutine:
Exit Sub
ErrRoutine:
MsgBox Err.Number & " - " & Err.Description, _
vbOKOnly Or vbCritical, _
"Application_FolderContextMenuDisplay"
GoTo EndRoutine
End Sub
Private Sub MoveToCompanyFolders()
Dim objNamespace As NameSpace
Dim objFolder As Folder
Dim objPane As NavigationPane
Dim objModule As TasksModule
Dim objGroup As NavigationGroup
Dim objNavFolder As NavigationFolder

Dim strTargetFolder As String
Dim strEntryID As String

On Error GoTo ErrRoutine

' Retrieve the Parameter property value from the
' control that called this routine.
strEntryID = _
    Application.ActiveExplorer.CommandBars.ActionControl.Parameter

' If there's no entry ID, we can't easily retrieve the folder.
If strEntryID = "" Then
    MsgBox "An entry ID could not be retrieved from " & _
        "the selected menu item."
Else
    ' Fetch the folder reference using the specified entry ID.
    Set objNamespace = Application.GetNamespace("MAPI")
    Set objFolder = objNamespace.GetFolderFromID(strEntryID)
    
    If objFolder Is Nothing Then
        MsgBox "A reference for the folder " & _
            "could not be retrieved."
    Else
        ' Get the NavigationPane object for the
        ' currently displayed Explorer object.
        Set objPane = Application.ActiveExplorer.NavigationPane
        
        ' Get the tasks module from the Navigation Pane.
        Set objModule = objPane.Modules.GetNavigationModule(olModuleTasks)
        
        ' Attempt to retrieve a navigation group named "Company Folders"
        ' from the tasks module. If it doesn't exist, create it.
        On Error Resume Next
        With objModule.NavigationGroups
            Set objGroup = .Item("Company Folders")
            If objGroup Is Nothing Then
                Set objGroup = .Create("Company Folders")
            End If
        End With
        On Error GoTo ErrRoutine
        
        ' Create a navigation folder for the selected folder
        ' in the "Company Folders" navigation group. As only
        ' one NavigationFolder object can be assigned to a
        ' given Folder object reference, this deletes the
        ' existing NavigationFolder object, if any, and creates
        ' a new one in the specified navigation group.
        Set objNavFolder = objGroup.NavigationFolders.Add(objFolder)
        
    End If
End If

EndRoutine:
Set objNavFolder = Nothing
Set objGroup = Nothing
Set objModule = Nothing
Set objPane = Nothing
Set objFolder = Nothing
Set objNamespace = Nothing

Exit Sub

ErrRoutine:
MsgBox Err.Number & " - " & Err.Description, _
vbOKOnly Or vbCritical, _
"MoveToCompanyFolders"
GoTo EndRoutine
End Sub