Navigation and View Management

  • 10 minutes to read

This topic explains how to implement navigation between separate application Views, and build the View-ViewModel relations.

Standard Navigation Services

DevExpress MVVM Framework inlcudes a number of Services that you can utilize to implement navigation between different application modules (Views).

The use of any MVVM Service consists of three major steps:

  1. Register a Service in a View. A Service can be registered either globally (it will be available from any application View) or locally (if you intend to use it from this module only).

  2. Declare a property inside a ViewModel to retrieve an instance of a registered Service.

  3. Call a public API of the Service instance inside your ViewModel.

For example, the main application View has the MvvmContext component that links this main application form (View) to the “Form1ViewModel” ViewModel.

// View
mvvmContext1.ViewModelType = typeof(mvvmNavi.Form1ViewModel);


// ViewModel
[POCOViewModel()]
public class Form1ViewModel {
    //...
}

The application also has two UserControls, each with its own MvvmContext component. A UserControl’s View is linked to its corresponding ViewModel.

public partial class ViewA : UserControl {
    MVVMContext mvvmContext;
    public ViewA() {
        mvvmContext = new MVVMContext();
        mvvmContext.ContainerControl = this;
        mvvmContext.ViewModelType = typeof(ViewAViewModel);
    }
}

public class ViewAViewModel {
}

public partial class ViewB : UserControl {
    MVVMContext mvvmContext;
    public ViewB() {
        mvvmContext = new MVVMContext();
        mvvmContext.ContainerControl = this;
        mvvmContext.ViewModelType = typeof(ViewBViewModel);
    }
}

public class ViewBViewModel {
}

Note

The code above initializes MvvmContext components and sets their ViewModelType properties for illustrative purposes only. In real-life applications, it is recommended to place components onto Forms and UserControls at design time, and use smart tag menus to set up ViewModels.

The following examples illustrate how to choose and utilize different DevExpress Services depending on your task:

Example 1: DocumentManager Tabs

The main application form (View) has an empty Document Manager, and the task is to display UserControls A and B as DocumentManager tabs (Documents).

To manage DocumentManager documents, use the DocumentManagerService. Register it inside the main View:

public Form1() {
    InitializeComponent();
    //. . .
    var service = DocumentManagerService.Create(tabbedView1);
    service.UseDeferredLoading = DevExpress.Utils.DefaultBoolean.True;
    mvvmContext1.RegisterDefaultService(service);
}

In the main ViewModel, implement a property that retrieves an instance of the registered Service:

[POCOViewModel()]
public class Form1ViewModel {
    protected IDocumentManagerService DocumentManagerService {
        get { return this.GetService<IDocumentManagerService>(); }
    }
}

The DocumentManagerService.CreateDocument and DocumentManagerService.FindDocumentById methods allow you to create and locate Documents. Then you can call the IDocument.Show method to display them.

// main ViewModel
public void CreateDocument(object id, string documentType, string title) {
    var document = DocumentManagerService.FindDocumentById(id);
    if (document == null) {
        document = DocumentManagerService.CreateDocument(
            documentType, parameter: null, parentViewModel: this);
        document.Id = id;
        document.Title = title;
    }
    document.Show();
}

This core method can be used in various scenarios.

  • Create a new Document with the specific UserControl and load it on application startup:

    // main ViewModel
    readonly static object ViewA_ID = new object();
    readonly static object ViewB_ID = new object();
    
    public void CreateDocumentA() {
        CreateDocument(ViewA_ID, "ViewA", "UserControl A");
    }
    
    public void CreateDocumentB() {
        CreateDocument(ViewB_ID, "ViewB", "UserControl B");
    }
    
    // main View
    var fluent = mvvmContext1.OfType<Form1ViewModel>();
    fluent.WithEvent(this, "Load").EventToCommand(x => x.CreateDocumentA);
    
  • Create one Document for each UserControl and load all of these Documents at startup.

    // main ViewModel
    public void CreateAllDocuments() {
        CreateDocument(ViewA_ID, "ViewA", "UserControl A");
        CreateDocument(ViewB_ID, "ViewB", "UserControl B");
    }
    
    // main View
    var fluent = mvvmContext1.OfType<Form1ViewModel>();
    fluent.WithEvent(this, "Load").EventToCommand(x => x.CreateAllDocuments);
    
  • Bind UI elements (for instance, Ribbon buttons) to a command that creates a new Document with the specific UserControl.

    // main ViewModel
    public void CreateDocument(object id, string documentType, string title) {
        var document = DocumentManagerService.CreateDocument(
            documentType, parameter: null, parentViewModel: this);
        document.Id = id;
        document.Title = title;
        document.Show();
    }
    
    public void CreateDocumentA() {
        CreateDocument(new object(), "ViewA", "UserControl A");
    }
    
    public void CreateDocumentB() {
        CreateDocument(new object(), "ViewB", "UserControl B");
    }
    
    // main View
    fluent.BindCommand(bbiCreateDocA, x => x.CreateDocumentA);
    fluent.BindCommand(bbiCreateDocB, x => x.CreateDocumentB);
    

Run Demo: Open the specific module Run Demo: Open all modules Run Demo: Open or activate the specific contact

Example 2: Navigation Frame

The main form (View) has an empty NavigationFrame component. This component can store multiple pages, but allows users to view only one page at a time. To populate this component with pages and implement navigation, use the NavigationService.

Global Service registration:

// main View
var service = NavigationService.Create(navigationFrame1);
mvvmContext1.RegisterDefaultService(service);

The property that retrieves a Service instance:

// main ViewModel
protected INavigationService NavigationService {
    get { return this.GetService<INavigationService>(); }
}

Navigation:

// main View
var fluent = mvvmContext.OfType<RootViewModel>();
fluent.WithEvent(mainView, "Load")
    .EventToCommand(x => x.OnLoad);

// main ViewModel

public void OnLoad() {
    NavigationService.Navigate("ViewA", null, this);
}

The Navigate method can accept parameters as its second argument. This allows you to pass any data between navigated modules. The DevExpress Demo Center sample illustrates how to pass the name of a previosly active module to the currently selected View. Note in this example the global Service registration allows every child ViewModel to utilize this Service’s API.

Run Demo: Open the specific module and close the previous

Example 3: Modal Forms

In this example, child Views are shown as separate forms above other application windows. To do this, use the WindowedDocumentManagerService Service.

Local registration:

// main View
var service = WindowedDocumentManagerService.Create(mainView);
service.DocumentShowMode = WindowedDocumentManagerService.FormShowMode.Dialog;
mvvmContext.RegisterService(service);

The property that retrieves a Service instance:

// main ViewModel
protected IDocumentManagerService WindowedDocumentManagerService {
    get { return this.GetService<IDocumentManagerService>(); }
}

Navigation:

// main View
var fluent = mvvmContext.OfType<MainViewModel>();
fluent.BindCommand(showBtn, x => x.ShowAcceptDialog);

// main ViewModel
int id = 0;
public void ShowAcceptDialog() {
    var viewModel = ViewModelSource.Create(() => new ViewAViewModel());
    var document = WindowedDocumentManagerService.FindDocumentById(id);
    if(document == null) {
        document = WindowedDocumentManagerService.CreateDocument(string.Empty, viewModel: viewModel);
        document.Id = id;
        document.Title = "Accept Dialog";
    }
    document.Show();
}

Run Demo: Open the specific modal form

ViewType Attribute

If you follow naming conventions (a ViewModel for the “ModuleX” View is called “ModuleXViewModel”) and Views/ViewModels are located in the same namespace, the default use of MVVM Services shown in the examples above is sufficient. Otherwise, the Framework is unable to locate a View related to the given ViewModule. To resolve this issue, you need to decorate Views with the ViewType attribute to explicitly set the View-ViewModel relation.

[DevExpress.Utils.MVVM.UI.ViewType("AccountCollectionView")]
public partial class AccountsView { 
    // ...
}

[DevExpress.Utils.MVVM.UI.ViewType("CategoryCollectionView")]
public partial class CategoriesView { 
    // ...
}

[DevExpress.Utils.MVVM.UI.ViewType("TransactionCollectionView")]
    public partial class TransactionsView { 
    // ...
}

See this tutorial for more information: Lesson 3 - Navigation and Services.

Views in Separate Assemblies

When your Views are located in separate assemblies or have custom constructors, the ViewType attribute is not sufficient. In these cases, use one of the following approaches:

IViewService

Cast your navigation Service instance to the DevExpress.Utils.MVVM.UI.IViewService interface.

var service = DevExpress.Utils.MVVM.Services.DocumentManagerService.Create(tabbedView1);
var viewService = service as DevExpress.Utils.MVVM.UI.IViewService;
mvvmContext1.RegisterService(service);

After that, handle the QueryView event to dynamically assign Views depending on the required View type.

viewService.QueryView += (s, e) =>
{
    if(e.ViewType == "View1")
        e.Result = new Views.View1();
    //...
};

To specify which View type is required, you need to implement the corresponding logic in your navigation ViewModel. For instance, the code below enumerates all available Views as items within the Modules collection.

public class MyNavigationViewModel {
    protected IDocumentManagerService DocumentManagerService {
        get { return this.GetService<IDocumentManagerService>(); }
    }
    //Lists all available view types
    public string[] Modules {
        get { return new string[] { "View1", "View2", "View3" }; }
    }
    //Bind this command to required UI elements to create and display a document
    public void Show(string moduleName) {
        var document = DocumentManagerService.CreateDocument(moduleName, null, this);
        if(document != null) {
            document.Title = moduleName;
            document.Show();}
    }
}

Control APIs

You can use an API of individual View controls that your navigation Service manages. For example, if Views should be displayed as DocumentManager tabs, handle the BaseView.QueryControl event to populate Documents. The View type is stored as the Document.ControlName property value.

var service = DevExpress.Utils.MVVM.Services.DocumentManagerService.Create(tabbedView1);
mvvmContext1.RegisterService(service);

tabbedView1.QueryControl += (s, e) =>
{
    if(e.Document.ControlName == "View 2")
        e.Control = new Views.View2();
    //...
};

IViewLocator

All DevExpress navigation services use the DevExpress.Utils.MVVM.UI.IViewLocator service to find and manage required Views. You can create your own custom implementation of this service and register it (either locally or globally) to change the way it works with application Views. See this article to learn how to implement and register custom services: Services.