How to: Implement Custom Context Navigation 如何：实现自定义上下文导航

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.

导航系统支持上下文导航。您可以在导航控件中跟踪创建导航项的过程，并添加自定义导航项。本主题演示如何在应用程序中实现自定义上下文导航。将实现窗口控制器。此控制器将添加"基于任务的帮助"子导航项，每个项将包含调用显示各种帮助文档的详细信息视图的项目。

Note 注意

Mobile applications do not support the dynamically creation of navigation items, so the approach described in this topic cannot be implemented in the Mobile platform.

注意 • 移动应用程序不支持动态创建导航项，因此本主题中描述的方法无法在移动平台中实现。

Tip 提示

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E1843

完整的示例项目可在 DevExpress 代码示例数据库中找到，http://www.devexpress.com/example=E1843

.

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.

 

要实现示例自定义上下文导航，应执行以下步骤。

1.定义帮助文档业务类。这是表示帮助文档的类。
2.实现自定义窗口控制器。它将包含将处理显示导航项目控制器的自定义上下文导航逻辑。事件处理程序必须创建名为"基于任务的帮助"的子导航项及其指向相应帮助文档的相应子节点。请注意，每个帮助文档都将与特定的 Business 类相关联。并且创建的导航项可   以指向没有关联文档的业务部门的视图。在这种情况下，不应创建"基于任务的帮助"导航项。

 

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.

帮助文档业务类由三个属性组成。

• 标题 - 表示文档的标题。
• 文本 - 保存文档中包含的实际文本。帮助文档的文本可能很长，因此此属性应使用 Size_-1_ 属性进行修饰（请参阅数据模型中的数据注释）。
• 对象类型 - 每个文档都将与业务类关联。因此，仅显示与特定业务类相关的帮助主题。ObjectType 属性包含关联的 Business 类的类型。由于此属性为 Type 类型，因此必须实现自定义值转换器（请参阅 ValueConverter），才能将该属性正确存储在数据库中。

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); }
    }
}

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.

自定义控制器只能为主窗口激活，因为只有主窗口模板包含导航操作容器（请参阅导航系统）。要实现自定义上下文导航逻辑，请订阅显示导航项控制器的导航项目创建事件。不要忘记取消订阅事件，以防止内存泄漏。

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);
    }
}

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.

导航项目创建事件在导航控件中创建导航项后发生。您需要跟踪事件处理程序中导航项的创建。由于不是每个导航项都指向视图，请检查是否设置了特定的 NavigationItem 节点的 View 属性。如果是，请检查是否存在特定业务类的帮助文档。如果存在现有帮助文档，请创建"基于任务的帮助"子导航项，并填充与这些现有帮助文档对应的子节点。此外，通过模型编辑器创建只读HelpDocument_DetailView_FewColumns详细信息视图。此视图将用于显示帮助文档。

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);
                    }
                }
            }
        }
    }
}