How to: Implement Custom Context Navigation

• Dec 22, 2023
• 6 minutes to read

The Navigation System supports context navigation. You can track the process of creating navigation items in the navigation control and add custom navigation items. This topic demonstrates how to implement custom context navigation in your applications. A Window Controller will be implemented. This Controller will add the “Task-Based Help” child navigation items, each of which will contain items invoking Detail Views displaying various help documents.

To implement the sample custom context navigation, perform the following steps.

1. Define the HelpDocument business class. This is the class that will represent help documents.
2. Implement a custom Window Controller. It will contain the custom context navigation logic that will handle the ShowNavigationItemController.NavigationItemCreated. The event handler must create a child navigation item titled “Task-Based Help” and its corresponding child nodes pointing to appropriate help documents. Note that each help document will be associated with a particular business class. And a created navigation item can point to a View of a business class that does not have associated documents. In this instance, the “Task-Based Help” navigation item should not be created.

Define the HelpDocument Business Class

The HelpDocument business class is comprised of three properties.

• Title - represents a document’s title.
• Text - holds the actual text contained in the document. A help document’s text can be very long, so this property should be decorated with the Size[-1] attribute (see Data Annotations in Data Model).
• ObjectType - each document will be associated with a business class. So only help topics relevant to a specific business class will be displayed. The ObjectType property holds the associated business class’ type. Since this property is of the Type type, a custom value converter must be implemented (see ValueConverter) for the property to be stored properly in the database.

C# (EF Core)

using DevExpress.ExpressApp.Utils;
using System.ComponentModel.DataAnnotations;
using Microsoft.EntityFrameworkCore.Storage.ValueConversion;
// ...

public class ApplicationDbContext : DbContext {
    // ...
    public DbSet<HelpDocument> HelpDocuments { get; set;}
    // ...
    protected override void OnModelCreating(ModelBuilder modelBuilder) {
        // ...
        modelBuilder.Entity<HelpDocument>()
            .Property(t => t.ObjectType)
            .HasConversion(new TypeToStringConverter());
    }
}

public class TypeToStringConverter : ValueConverter<Type, string> {
    public TypeToStringConverter() : base(
            v => v.FullName,
            v => ReflectionHelper.FindType(v)) { }
}

[DefaultClassOptions, ImageName("BO_Report")]
public class HelpDocument : BaseObject {
    public virtual Type ObjectType { get; set; }
    public virtual string Title { get; set; }
    [FieldSize(-1)]
    public virtual string Text { get; set; }
}

// Make sure that you use options.UseChangeTrackingProxies() in your DbContext settings.

C# (XPO)

using DevExpress.ExpressApp.Utils;
//...
[DefaultClassOptions, ImageName("BO_Report")]
public class HelpDocument : BaseObject {
    public HelpDocument(Session session) : base(session) { }
    [DevExpress.Xpo.ValueConverter(typeof(TypeToStringConverter ))]
    public Type ObjectType {
        get { return GetPropertyValue<Type>(nameof(ObjectType)); }
        set { SetPropertyValue<Type>(nameof(ObjectType), value); }
    }
    public string Title {
        get { return GetPropertyValue<string>(nameof(Title)); }
        set { SetPropertyValue<string>(nameof(Title), value); }
    }
    [Size(-1)]
    public string Text {
        get { return GetPropertyValue<string>(nameof(Text)); }
        set { SetPropertyValue<string>(nameof(Text), value); }
    }
}

VB.NET (XPO)

Imports DevExpress.ExpressApp.Utils
'...
<DefaultClassOptions, ImageName("BO_Report")> _
Public Class HelpDocument
    Inherits BaseObject
    Public Sub New(ByVal session As Session)
        MyBase.New(session)
    End Sub
    <DevExpress.Xpo.ValueConverter(GetType(TypeToStringConverter ))> _
    Public Property ObjectType() As Type
        Get
            Return GetPropertyValue(Of Type)(NameOf(ObjectType))
        End Get
        Set(ByVal value As Type)
            SetPropertyValue(Of Type)(NameOf(ObjectType), value)
        End Set
    End Property
    Public Property Title() As String
        Get
            Return GetPropertyValue(Of String)(NameOf(Title))
        End Get
        Set(ByVal value As String)
            SetPropertyValue(Of String)(NameOf(Title), value)
        End Set
    End Property
    <Size(-1)> _
    Public Property Text() As String
        Get
            Return GetPropertyValue(Of String)(NameOf(Text))
        End Get
        Set(ByVal value As String)
            SetPropertyValue(Of String)(NameOf(Text), value)
        End Set
    End Property
End Class

Implement a Custom Window Controller

The custom Controller must only be activated for the main Window, since only main Window Templates contain the navigation Action Container (see Navigation System). To implement the custom context navigation logic, subscribe to the ShowNavigationItemController‘s NavigationItemCreated event. Do not forget to unsubscribe from the event to prevent memory leaks.

C#

using DevExpress.ExpressApp.SystemModule;
//...
public class TaskBasedHelpController : WindowController {
    private ShowNavigationItemController navigationController;
    protected override void OnFrameAssigned() {
        UnsubscribeFromEvents();
        base.OnFrameAssigned();
        navigationController =
            Frame.GetController<ShowNavigationItemController>();
        if(navigationController != null) {
            navigationController.NavigationItemCreated += 
                navigationItemCreated;
        }
    }
    private void UnsubscribeFromEvents() {
        if(navigationController != null) {
            navigationController.NavigationItemCreated -= 
                navigationItemCreated;
            navigationController = null;
        }
    }
    protected override void Dispose(bool disposing) {
        UnsubscribeFromEvents();
        base.Dispose(disposing);
    }
}

VB.NET

Imports DevExpress.ExpressApp.SystemModule
'...
Public Class TaskBasedHelpController
    Inherits WindowController
    Private showNavigationItemController As navigationController
    Protected Overrides Sub OnFrameAssigned()
        UnsubscribeFromEvents()
        MyBase.OnFrameAssigned()
        navigationController = Frame.GetController(Of ShowNavigationItemController)()
        If navigationController IsNot Nothing Then
            AddHandler navigationController.NavigationItemCreated, _
            AddressOf navigationItemCreated
        End If
    End Sub
    Private Sub UnsubscribeFromEvents()
        If navigationController IsNot Nothing Then
            RemoveHandler navigationController.NavigationItemCreated, _
            AddressOf navigationItemCreated
            navigationController = Nothing
        End If
    End Sub
    Protected Overrides Overloads Sub Dispose(ByVal disposing As Boolean)
        UnsubscribeFromEvents()
        MyBase.Dispose(disposing)
        End Sub
End Class

Handle the NavigationItemCreated event

The NavigationItemCreated event occurs after a navigation item has been created in the navigation control. You will need to track the creation of navigation items in the event handler. Since not every navigation item points to a View, check whether a particular NavigationItem node’s View property is set. If it is, check whether help documents for a particular business class exist. If there are existing help documents, create the “Task-Based Help” child navigation item and populate it with child nodes corresponding to these existing help documents. Additionally, create a read-only HelpDocument_DetailView_FewColumns Detail View via the Model Editor. This View will be used to display help documents.

C#

using System.Collections.Generic;
using DevExpress.Data.Filtering;
using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Actions;
using DevExpress.ExpressApp.DC;
using DevExpress.ExpressApp.Model;
//...
public class TaskBasedHelpController : WindowController {
    //...
    void navigationItemCreated(object sender, NavigationItemCreatedEventArgs e) {
        ChoiceActionItem navigationItem = e.NavigationItem;
        IModelObjectView viewNode = ((IModelNavigationItem)e.NavigationItem.Model).View as 
            IModelObjectView;
        if (viewNode != null) {
            ITypeInfo objectTypeInfo = XafTypesInfo.Instance.FindTypeInfo(viewNode.ModelClass.Name);
            if (objectTypeInfo != null) {
                CriteriaOperator docCriteria = 
                    CriteriaOperator.Parse("ObjectType == ?", objectTypeInfo.Type);
                IObjectSpace myObjectSpace = Application.CreateObjectSpace(typeof(HelpDocument));
                IList<HelpDocument> docs = myObjectSpace.GetObjects<HelpDocument>(docCriteria);
                if (docs.Count > 0) {
                    ChoiceActionItem docsGroup = new ChoiceActionItem(
                        "CustomDocuments", "Task-Based Help", null) { ImageName = "BO_Report" };
                    navigationItem.Items.Add(docsGroup);
                    foreach (HelpDocument doc in docs) {
                        ViewShortcut shortcut = new ViewShortcut(typeof(HelpDocument), 
                            doc.Oid.ToString(), "HelpDocument_DetailView_FewColumns");
                        ChoiceActionItem docItem = new ChoiceActionItem(
                            doc.Oid.ToString(), doc.Title, shortcut) 
                            { ImageName = "Navigation_Item_Report" };
                        docsGroup.Items.Add(docItem);
                    }
                }
            }
        }
    }
}

VB.NET

Imports System.Collections.Generic
Imports DevExpress.Data.Filtering
Imports DevExpress.ExpressApp
Imports DevExpress.ExpressApp.Actions
Imports DevExpress.ExpressApp.DC
Imports DevExpress.ExpressApp.Model
'...
Public Class TaskBasedHelpController
    Inherits WindowController
    '...
    Private Sub navigationItemCreated(ByVal sender As Object, _
    ByVal e As NavigationItemCreatedEventArgs)
        Dim navigationItem As ChoiceActionItem = e.NavigationItem
        Dim viewNode As IModelObjectView = TryCast( _
        (CType(e.NavigationItem.Model, IModelNavigationItem)).View, IModelObjectView)
        If viewNode IsNot Nothing Then
            Dim objectTypeInfo As ITypeInfo = _
            XafTypesInfo.Instance.FindTypeInfo(viewNode.ModelClass.Name)
            If objectTypeInfo IsNot Nothing Then
                Dim docCriteria As CriteriaOperator = _
                CriteriaOperator.Parse("ObjectType == ?", objectTypeInfo.Type)
                Dim myObjectSpace As IObjectSpace = Application.CreateObjectSpace(GetType(HelpDocument))
                Dim docs As IList(Of HelpDocument) = _
                myObjectSpace.GetObjects(Of HelpDocument)(docCriteria)
                If docs.Count > 0 Then
                    Dim docsGroup As New ChoiceActionItem("CustomDocuments", _
                    "Task-Based Help", Nothing) With {.ImageName = "BO_Report"}
                    navigationItem.Items.Add(docsGroup)
                    For Each doc As HelpDocument In docs
                        Dim shortcut As New ViewShortcut(GetType(HelpDocument), _
                        doc.Oid.ToString(), "HelpDocument_DetailView_FewColumns")
                        Dim docItem As New ChoiceActionItem( _
                        doc.Oid.ToString(), doc.Title, shortcut) With _
                        {.ImageName = "Navigation_Item_Report"}
                        docsGroup.Items.Add(docItem)
                    Next doc
                End If
            End If
        End If
    End Sub
End Class