Microsoft patterns & practices Composite UI Application Block (CAB) based Module Composite Mapper Service: An XML Configurable Builder for Workspaces, UIElements, Commands, and Event Publications/Subscriptions

• Download source files - 997 Kb

Introduction

Proof-of-Concept Framework

The module composite mapper service is based and executes on the CAB using a Model-View-Presenter (MVP) pattern within a proof-of-concept (POC) framework. While the POC framework can be modified (or removed altogether) based on your needs, the following describes the POC framework base classes in further detail. Note that the POC framework shell uses the native CAB reflection-based module loader service against a local startup directory.

• Module Initialization Class (e.g., MyModuleInit): in the POC framework, effectively only a bootstrap mechanism for the module work item (contained in the root namespace for any module)
  
  
• Work Item Interface and Class (IXSWorkItem and XSWorkItem): the model bridge (i.e., communicates state to underlying business objects) and/or model implementation (i.e., communicates state to a persistence layer) in the MVP pattern that contains the views (i.e., SmartParts), presenters, and other components (i.e., UI elements, commands, events, services and more) that collaborate at runtime to realize a specific use case (contained in the root namespace for any module); in the POC framework, work item-based composite mappings are applied on work item build up (i.e., OnBuiltUp) ensuring that event publication/subscription is consistent with the native CAB application initialization sequence (as well as shell workspace, UI element and command initialization prior to module catalog enumeration that may rely on shell hosted items):
  
  this.RootWorkItem.Services.Get<IXSModuleCompMpprService>().ApplyModuleMappings(this);
  
  
  
  In the POC framework, note that base work item and presenter classes provide generic events for programming efficiency and infrastructure performance optimization by alleviating the need for repetively specifying such application-wide events using the module composite mapper service (i.e., the native CAB declarative model for event publication is used).
  
  
• Presenter Interface and Class (IXSPresenter and XSPresenter): the presenter in the MVP pattern that manages end-user displayed view(s) based on events broadcast/received or method calls made from/to the participating work item (i.e., model) (contained in the SmartParts namespace for any module); in the POC framework, presenter-based composite mappings are applied on presenter construction (which occurs on the owning XSWorkItem.Run) ensuring that views are not accessed by composite mapper classes (e.g., XSWorkspaceCompMppr) until they are actually shown:
  
  this.workItem.RootWorkItem.Services.Get<IXSModuleCompMpprService>().ApplyModuleMappings(this);
  
  
  
  As noted previously, the POC framework base work item and presenter classes provide generic events for programming efficiency and infrastructure performance optimization by alleviating the need for repetively specifying such application-wide events using the module composite mapper service (i.e., the native CAB declarative model for event publication is used).
  
  
• View Interface and Class (IXSView and XSView): the view in the MVP pattern that provides end-user display only based on method calls made from/to the participating presenter (contained in the SmartParts namespace for any module)
  
  
  
  

Module Composite Mapper Service

• Workspace: encapsulates a particular layout of controls and SmartParts, such as within tabbed pages; in the POC framework, mainly applicable to the shell presenter that provides interfaces with which to easily display module views in desired workspaces
• UI Extension Site: identified by an extension site topic, provides a UI element adapter that serves as an extension point for any registered UI element (i.e., for adding and removing child UI elements); in the POC framework, allows a module to specify user interface element extensions within the shell (e.g., menu, toolbar and statusbar items) including end-user control over the ordering of UI elements that are added using an insert priority
• Command: associates a command handler method that is defined on the module presenter with any command topic
• Event Publication: specifies a method that is defined on the module work item or presenter as a publication handler for event broadcast
• Event Subscription: specifies a method that is defined on the module work item or presenter as a subscription method for event receive

• Module composite mapper XML configuration file specification
• Workspace topic access for view display (from the workspace composite mapper for the shell... an XSWorkspaceCompMppr class static property)
• User interface element access for view management (from the presenter-specific UI extension site composite mapper... an XSPresenter base class property)

Module Composite Mapper Service Classes

• Module Composite Mapper Service Interface and Class (IXSModuleCompMpprService and XSModuleCompMpprService): a singleton service class that manages module composite mapper creation and delegates the application of module composite mappings (at the work item or presenter level) to the contained module composite mapper
  
  
  
  The module composite mapper service is instantiated and registered in the shell application AddServices method per the following:
  
  

  XSModuleCompMpprService service = XSModuleCompMpprService.CreateInstance();
  this.RootWorkItem.Services.Add<IXSModuleCompMpprService>(service);

• Module Composite Mapper Class (XSModuleCompMppr): builds the module composite mapper object hierarchy using the XML configuration file specified with a module (and a private XMLReader-based loader class, XSModuleCompMpprLoader) and delegates the application of composite mappings (at the work item or presenter level) to the contained composite mappers; note that the module composite mapper class applies event publication and event subscription composite mappings to both work items and presenters (as specified in the configuration file) whereas workspace, UI extension site, and command composite mappings are applied to presenters only given the interpretation of the MVP pattern as realized in the POC framework implementation
  
  
  
  
• Composite Mapper Classes: the workhorses of the service, composite mapper classes apply composite mappings (at the work item or presenter level with the overloaded ApplyCompositeMappings method) based on the contained composites (if any) built from the module composite mapper XML configuration file
  
  
  
  Several unique interfaces are provided on the composite mapper classes including:
  
  XSWorkspaceCompMppr.ShellWorkspaceCompMppr: workspace composite mapper for the shell that allows for...
  XSWorkspaceCompMppr.GetWorkspaceTopic: workspace topic access for view display by pre-defined workspace types
  
  The base XSPresenter.ShowView method displays its current view in the requested workspace as follows:
  
  protected void ShowView(XSWorkspaceType thisWorkspaceType)
  {
      this.workItem.RootWorkItem.Workspaces[
          XSWorkspaceCompMppr.ShellWorkspaceCompMppr.GetWorkspaceTopic(
              thisWorkspaceType)].Show(this.View);
  }
  
  
  
  XSUIExtSiteCompMppr.GetUIElements: user interface element access for view management by the presenter (e.g., setting a menu item and toolbar item Checked property on command invocation); currently all UI elements are returned that match the topic parameter including either the UI element command, registration or parent topic property (obviously, this can be modified or extended to meet your needs)
  
  
  
  
• Composite Classes: composites are essentially persisted by (read-only) and built directly from the module composite mapper XML configuration file; static object creation methods (i.e., CreateInstance) are provided by each of the composite classes including some validation of XML configuration file input parameters passed from the XSModuleCompMpprLoader loader class
  
  
  

Module Composite Mapper XML Configuration File Syntax and Examples (XSModuleCompMppr.xml)

• The configuration file and any associated image files must be set to compile as embedded resources in the container module project
• The configuration file must be located and named per the following namespace hierarchy, i.e., folders and file name (assuming a project name of MyComponentModule)
  
  MyComponentModule.Services.XSModuleCompMppr.XSModuleCompMppr.xml
  
  The XSModuleCompMppr.CreateInstance method uses the following code in order to get a manifest resource stream using the IXSWorkItem parameter type (as it is expected to be in the assembly default namespace), standard module composite mapper service assembly extended namespace and filename (reference XSModuleCompMppr.AssyXSModuleCompMpprNS):
  
  mpprStream = thisWorkItem.GetType().Assembly.GetManifestResourceStream(
      thisWorkItem.GetType(),
      XSModuleCompMppr.AssyXSModuleCompMpprNS);

XSModuleCompMppr.xml Syntax

<XtensibleSolutions version="2.0" language="XSModuleCompMppr">
    <!--Module composite mapper contains composite mappers: 
         * Workspace (optional; applies to shell presenter only)
         * UI extension site (optional)
         * Command (optional)
         * Event (optional) 
            NOTE: ALL WorkItems/Presenters publish generic events.-->
    <Module_Composite_Mapper>
      <!--Workspace composite mapper contains workspace composites:
            * Workspace type descriptor (optional; for readability only) and... 
            * Workspace type enumeration value (required)
            * Workspace topic (required)-->
      <Workspace_Composite_Mapper>
          <Workspace_Composite
              XSWorkspaceType_Descriptor="Foo"
              XSWorkspaceType_Enum="0"
              Workspace_Topic="wks://XS/Shell/Foo"/>
      <!--UI extension site composite mapper contains UI extension site composites: 
           * Parent topic (required)
           * Insert priority (optional - defaults to 0.0; used to indicate an 
              insertion priority for positioning the UI element in relation to its sibling 
              items); if not populated, the null priority is assigned (0.0) and the default 
              CAB behavior is used for the requested insertion (appended as the last item); 
              if populated (with a float value), the indicated priority is assigned and 
              used for positioning the requested insertion where: 
              - the smaller the indicated magnitude, the higher its priority and the closer 
                the item will be to the top of the list if not the first (i.e., 1.0 is 
                considered "priority one", though the actual algorithm has no practical limit 
                on the lower bounds while also considering the special value of 0.0)
              - the higher the indicated magnitude, the lower its priority and the closer 
                the item will be to the bottom of the list if not the last (e.g., 99.0 is 
                lower priority than 1.0)
              - equivalent priorities result in the existing item taking precedence (i.e., the
                new item is inserted immediately after that which it is equal to in priority)
              - an assigned priority always takes precedence over those not assigned 
                that are appended as the last items (e.g., 99.0 is higher priority 
                than 0.0)
           * UI element Type (optional - defaults to "ToolStripMenuItem")
           * UI element properties (optional; a generic attribute with 
              property|value|property|value|... pairs used to configure 
              virtually any property on the created UI element); currently 
              supported property types include strings, booleans, and images...

              Examples: 

              "Text|&amp;File": sets the Text property on the UI element to "File" 
              with the "F" specified as the UI element mnemonic

              "Checked|true": sets the Checked property on the UI element to True

              "Image|MyImageFile.ico": sets the Image property on the UI element 
              from the image file as specified (e.g., toolbar icons); images must 
              be named per the property specification (e.g., MyImageFile.ico), 
              co-located alongside the composite mapper file in the XSModuleCompMppr 
              folder, and compiled as an embedded resource

           * Register topic (optional) and...
           * Register property (optional - defaults to "DropDownItems"; used to 
              indicate which property on the created UI element is registered as 
              an extension point)
           * Command topic (optional) and...
           * Command event name (optional - defaults to "Click")-->
      <UIExtensionSite_Composite_Mapper>
          <UIExtensionSite_Composite 
              Parent_Topic="ste://XS/Shell/Menu"
              Insert_Priority="1.0"
              UIElement_Type="ToolStripMenuItem" 
              UIElement_Properties="Text|&amp;File"
              Register_Topic="ste://XS/Shell/Menu/File"
              Register_Property="DropDownItems"
              Command_Topic="cmd://XS/Shell/File_Click"
              Command_EventName="Click"/>
      </UIExtensionSite_Composite_Mapper>
      <!--Command composite mapper contains command composites: 
           * Command topic (required)
           * Command handler method name (required)-->
      <Command_Composite_Mapper>
          <Command_Composite 
              Command_Topic="cmd://XS/Shell/FileExit_Click"
              Command_HandlerName="OnFileExit_Click"/>
      </Command_Composite_Mapper>
      <!--NOTE: ALL WorkItems/Presenters publish generic events.-->
      <!--Event publication composite mapper contains event publication composites: 
           * Event topic (required)
           * Publication scope descriptor (optional; for readability only) and... 
           * Publication scope enumeration value (optional - defaults to 
             Global {0}); values include (see the CAB help for more info): 
                 - Global {0}
                 - WorkItem {1}
                 - Descendants {2} 
         * Publisher type descriptor (optional; for readability only) and... 
         * Publisher type enumeration value (optional - defaults to WorkItem {0}); 
            values include: 
                - WorkItem {0}
                - Presenter {1} 
         * Publication handler method name (required)-->
      <EventPublication_Composite_Mapper>
          <EventPublication_Composite 
              Event_Topic="evt://XS/MyModule/MyEvent"
              PublicationScope_Descriptor="Global"
              PublicationScope_Enum="0"
              XSEventPubSubType_Descriptor="WorkItem"
              XSEventPubSubType_Enum="0" 
              Publication_HandlerName="BroadcastMyEvent"/>
      </EventPublication_Composite_Mapper>
      <!--Event subscription composite mapper contains event subscription composites: 
           * Event topic (required)
           * Subscriber type descriptor (optional; for readability only) and... 
           * Subscriber type enumeration value (optional - defaults to WorkItem {0}); 
              values include: 
                  - WorkItem {0}
                  - Presenter {1} 
           * Subscription method name (required)-->
      <EventSubscription_Composite_Mapper>
          <EventSubscription_Composite 
              Event_Topic="evt://XS/MyModule/MyEvent"
              XSEventPubSubType_Descriptor="WorkItem"
              XSEventPubSubType_Enum="0" 
              Subscription_MethodName="OnReceiveMyEvent"/>
      </EventSubscription_Composite_Mapper>
    </Module_Composite_Mapper>
</XtensibleSolutions>

Module Composite Mapper Topic Formats

Workspace Topic Format

UIExtensionSite Topic Format

Command Topic Format

Event Topic Format

Example Modules

XSShell

MyServerModule

MyClientModule

Conclusion