[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Collapse]WPF Controls
  Prerequisites
 [Expand]What's Installed
 [Expand].NET Core 3 Support
 [Expand]Common Concepts
 [Collapse]MVVM Framework
  [Expand]View Models
  [Expand]Commands
  [Expand]Behaviors
  [Collapse]Services
    Getting Started
    Services in ViewModelBase descendants
    Services in POCO objects
    Services in custom ViewModels
    View creation mechanisms
   [Collapse]Predefined Set
    [Expand]Dialog Services
    [Expand]Message Box Services
    [Collapse]Document Services
      Document Management System
      FrameDocumentUIService
      TabbedDocumentUIService
      WindowedDocumentUIService
      DockingDocumentUIService
      TabbedWindowDocumentUIService
    [Expand]ViewInjectionService
    [Expand]Report Services
     NotificationService
     TaskbarButtonService
     ApplicationJumpListService
     DXSplashScreenService
     DispatcherService
     FrameNavigationService
     LayoutSerializationService
     FolderBrowserDialogService
     OpenFileDialogService
     SaveFileDialogService
     WizardService
     WindowService
     CurrentDialogService
     CurrentWindowService
     NotifyIconService
    How to create a Custom Service
  [Expand]DXBinding
  [Expand]MIF
   Converters
   ViewLocator
   Messenger
   Data Annotation Attributes
   LayoutTreeHelper
   Weak Event
 [Expand]Controls and Libraries
 [Expand]Scaffolding Wizard
 [Expand]Localization
  Redistribution and Deployment
  Get More Help
 [Expand]API Reference
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Reporting
[Expand]Report and Dashboard Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

Document Management System

This topic describes the common concepts behind services that implement the IDocumentManagerService interface.

Expanded Document Manager Service and Documents Concepts

The IDocumentManagerService is an abstraction of the document manager that works with document-objects representing Views and ViewModels. The DevExpress MVVM Framework includes several implementations of the IDocumentManagerService interface that are associated with different DevExpress WPF Controls and as a result uses different forms to display their documents. Nevertheless, each of these services uses the common document management mechanism provided by IDocumentManagerService to control documents.

The IDocumentManagerService interface definition is represented below.

All Views and ViewModels injected in a Document Manager are stored as collections of document-objects in the IDocumentManagerService.Documents property. Each document in a collection is an object implementing the IDocument interface (see its code below). Note that documents for different services may have a different structure regardless of owner-service specifics.

The IDocument interface provides the base methods and properties to work with the document.

Note

The IDocument.Id property value is used as a control name and should conform to the XamlName Grammar.

The CreateDocument method cannot be browsed, because there is no need to use all four parameters simultaneously. Instead, there are several extension methods from the DocumentManagerServiceExtensions class.

Method 1 is used when a document View is defined through the ViewServiceBase.ViewTemplate or ViewServiceBase.ViewTemplateSelector property and at the same time, the document View should not contain a View Model, because it is passed through the service.

Method 2 and Method 3 create a document View by implicitly calling the ViewLocator and pass the specified ViewModel to the created View. To learn how the view creation works using the ViewLocator, see the following topic: View creation mechanisms.

When the document is created, use the IDocument.Show method to display it.

This method works differently, based on which IDocumentManagerService implementation you use. For instance, if you use the WindowedUIDocumentManagerService, the document will be shown in a separate window.

When a document is created, it can be obtained with the IDocumentManagerService.Documents property. Alternatively, there are several built-in methods in the DocumentManagerServiceExtensions class that perform searching.

The DocumentManagerServiceExtensions.GetDocumentsByParentViewModel method (Method 4) returns a collection of documents whose ParentViewModel is equal to the ViewModel passed as a parameter. To use this method, the document View Model should implement the ISupportParentViewModel interface. Otherwise, this method returns an empty collection. Method 5 requires you to implement the ISupportParameter interface by the document's ViewModel and returns the first document with a specified parameter and parent ViewModel. Method 6 and Method 7 retrieve and return a document with a specified ViewModel or id accordingly.

Note

Searching by the ID requires the IDocument.Id property to be initialized with a unique value.

In addition to the base methods, the DocumentManagerServiceExtensions class provides two methods.

The DocumentManagerServiceExtensions.FindDocumentByIdOrCreate method retrieves and returns a document with a specific Id. If such a document does not exist, it will be created and returned by the method.

The DocumentManagerServiceExtensions.CreateDocumentIfNotExistsAndShow method creates and shows a new document if a document with the specified parameters does not exist.

The active document can be obtained using the IDocumentManagerService.ActiveDocument property. After the active document has been changed, the IDocumentManagerService.ActiveDocumentChanged event is raised. To subscribe this event, you can use the EventToCommand class or create an event handler for the ActiveDocumentChanged event in your ViewModel.

In the code snippet above, the ActiveDocumentChanged event is bound to the ActiveDocumentChangedCommand command. The implementation of this command is shown in the code snippet below.

Expanded Implementing Document and ViewModel Interaction

To organize relationships between a ViewModel and its document created by IDocumentManagerService, implement the IDocumentContent interface at the ViewModel level.

This interface provides the following capabilities.

  • Use the IDocumentContent.Title property to specify the document's title. The IDocument.Title has higher priority than IDocumentContent.Title.
  • Control the document's closing and erasing with the IDocumentContent.OnClose and IDocumentContent.OnDestroy methods. OnClose is an event handler that is raised when the document is going to be closed. By using the OnClose method's arguments, you can prevent the document from being closed. The OnDestroy method is called after the document is closed.
  • Access the document's service-owner by using the IDocumentContent.DocumentOwner property of the IDocumentOwner type. The IDocumentOwner interface provides a single method: IDocumentOwner.Close, which allows you to close a document specified in the documentContent parameter.

Below is an example that illustrates how to use the IDocumentContent and IDocumentOwner interfaces.

Expanded Document Manager Serialization

IDocumentManagerService implementations allow you to save layout information about opened documents. Layout information can be divided into two parts.

  • Logical Layout
  • Visual Layout

The Logical Layout contains document descriptions (title, id, type, visibility, etc). Additionally, you can save information about the document's ViewModel state by implementing the ISupportLogicalLayout generic interface at the ViewModel level.

The ISupportLogicalLayout interface is shown below.

This interface provides the following capabilites:

  • CanSerialize - specifies whether ViewModel's state can be serialized.
  • DocumentManagerService - specifies the service owner.
  • SaveState/RestoreState methods to save/restore ViewModel's state.
  • LookupViewModels specifies a collection of ViewModels of child documents.

To serialize\deserialize the logical part, use the SerializeDocumentManagerService extension method that returns the saved layout as a string object.

The Visual Layout - includes information about controls displayed within a document. To serialize\deserialize the visual layout, use the LayoutSerializationService.

To learn how to use this service, see the LayoutSerializationService topic. A sample illustrating this feature in action is available here here.

Important

To properly save and restore documents, follow these recommendations.

  • The Document.Id property should be initialized with an unique value that is defined in accordance with XamlName Grammar.
  • A document ViewModel should be defined in XAML at the document's View level.
  • A document ViewModel should implement the ISupportLogicalLayout interface. Otherwise, the ViewModel's state will not be serialized.
  • An object representing a ViewModel's state should support serialization/deserialization by using the Data Contracts serialization engine

Is this topic helpful?​​​​​​​