Object mapping files

•

Environment: onsite

• 6 minutes to read

Since all the rendering and building of a page in SuperOffice Web depends on XML configuration files, we need a mechanism to map the objects of the pages to the actual objects of the system. For example, in which assembly a particular control is taken from.

SoObjectMapping maps element types used in page configuration files to actual implementation classes defined in assemblies, such as user controls and web controls.

Below is an excerpt of an object mapping config file. We have cut out some parts to keep it reasonably short.

<objects>
  <!-- rendering framework-->
  <object type="IPanel" mappingname="SoPanel" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Controls.Panel"></object>
  <object type="IPanel" mappingname="SoMainPanel" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Controls.MainPanel"></object>

  <object type="ICard" mappingname="SoCard" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Controls.Card"></object>
  <object type="ICard" mappingname="SoTabbedCard" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Controls.TabbedCard"></object>

  <object type="IView" mappingname="SoView" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Controls.View"></object>
  <object type="IView" mappingname="SoPlainView" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Controls.PlainView"></object>

  <object type="IControlGroup" mappingname="SoControlGroup" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Controls.ControlGroup"></object>
  <object type="IControlGroup" mappingname="SoHookedControlGroup" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Controls.HookedControlGroup"></object>

  <object type="IViewStateProvider" mappingname="SoProtocolProvider" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.Protocol.SoProtocolProvider" ></object>
  <object type="IViewStateProvider" mappingname="SoMiniPreviewProvider" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.Protocol.SoMiniPreviewProvider" ></object>

  <!-- Data handlers -->
  <object type="IDataHandler" mappingname="DiaryDataHandler" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.Data.DiaryDataHandler"></object>
  <object type="IDataHandler" mappingname="ContactEntityDataHandler" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.Data.ContactEntityDataHandler"></object>

  <!-- Validations -->
  <object type="IValidation" mappingname="DateValidation" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Validations.DateValidator"></object>
  <object type="IValidation" mappingname="RangeValidation" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Validations.RangeValidator"></object>

  <!-- User controls -->
  <object type="UserControl" mappingname="ContactMainView" assemblyname="SuperOffice.CRMWeb" objectname="~/WebParts/Contact/ContactMainView.ascx"></object>
  <object type="UserControl" mappingname="Contact2PersonMainView" assemblyname="SuperOffice.CRMWeb" objectname="~/WebParts/Contact/Contact2PersonMainView.ascx"></object>

  <!-- Find dialog -->
  <object type="UserControl" mappingname="SoCriteria" assemblyname="" objectname="~/WebParts/Find/CriterionControl.ascx"></object>
  <object type="UserControl" mappingname="SoCriteriaDialog" assemblyname="" objectname="~/WebParts/Find/CriterionDialogControl.ascx"></object>

  <object type="Control" mappingname="SoHiddenField" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Controls.SoHiddenField" ></object>
  <object type="Control" mappingname="SoButton" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Controls.SoButton"></object>

  <object type="IArchiveAction" mappingname="UpdateRows" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Controls.UpdateRows"></object>
  <object type="IArchiveAction" mappingname="ToggleActivities" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Controls.ToggleActivities"></object>

  <object type="AjaxMethod" mappingname="Appointment" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.AjaxMethods.Appointment" xusing_ajaxnet="true"></object>
  <object type="AjaxMethod" mappingname="DiaryUpdate" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.AjaxMethods.DiaryUpdate" xusing_ajaxnet="true"></object>

  <!-- filters -->
  <object type="IFilter" mappingname="FreetextFindFilter" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Filters.FreetextFindFilter"></object>
  <object type="IFilter" mappingname="ContextFilter" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Filters.ContextFilter"></object>

  <!-- Archive data fetchers-->
  <object type="IArchiveControlDataFetcher" mappingname="SoArchiveFetcher" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Controls.SoArchiveFetcher"></object>
  <object type="IArchiveControlDataFetcher" mappingname="SoArchiveFindFetcher" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Controls.SoArchiveFindFetcher"></object>
</objects>

Parameter	Description
type	the type of the object
mappingname	the name that this object is given in the other config files
assemblyname	the assembly that this particular object resides in
objectname	the actual name of the object inside the given assembly

For example, the following line tells us the object that is represented by this line is referred to as SoPanel in other config files, resides in the SuperOffice.CRMWeb assembly, and is called SuperOffice.CRM.Web.UI.Controls.Panel.

<object type="IPanel" mappingname="SoPanel" assemblyname="SuperOffice.CRMWeb" objectname="SuperOffice.CRM.Web.UI.Controls.Panel"></object>

When you have the mapping like this in a config file, it is very easy for a class factory to come in and use these configurations to build the actual objects. By using this method we can gain another advantage: we can very easily extend the object library and we can add customization versions very easily as well. The logic behind this is if the name of the object does not change, we can alter the behavior of the object and the PageBuilder framework will not know the difference.

Explicit object mapping

The excerpt below declares an SoPanel type in SoObjectMapping.config. It states that the class Panel in the SuperOffice.CRM.Web.UI.Controls namespace, located in the SuperOffice.CRMWeb assembly is referenced by mappingname SoPanel.

Next, the file declares an SoNavigatorButton type. It states that a class SoNavigatorButton in the SuperOffice.CRM.Web.UI.Controls namespace, located in the SuperOffice.CRMWeb assembly is referenced by mappingname SoNavigatorButton.

<!-- SoObjectMapping.config -->
<objects>
  <object
    type="IPanel"
    mappingname="SoPanel"
    assemblyname="SuperOffice.CRMWeb"
    objectname="SuperOffice.CRM.Web.UI.Controls.Panel" />
  <object
    type="Control"
    mappingname="SoNavigatorButton"
    assemblyname="SuperOffice.CRMWeb"
    objectname="SuperOffice.CRM.Web.UI.Controls.SoNavigatorButton" />
</objects>

Looking at the SoNavigatorPanel.config file, the contents of which define all the navigator controls on the left side of SuperOffice is where the panel type declares the object mappingname, SoPanel. Additionally, nested deep in a card, view, controlgroup, and controls element is where several SoNavigatorButton types that represent the buttons in the panel are declared.

<!-- SoNavigatorPanel.config -->
<panel id="Navigator" type="SoPanel" paneltype="Navigator" ...>
...
  <control id="dashboardButton" type="SoNavigatorButton" >
  ...
  </control>
  ...
</panel>

Implicit object mapping

An alternative approach to adding a type in the SoObjectMapping.config file is to in code decorate the class with the SoWebObject attribute, and inherit the IWebObject interface. The IWebObject doesn't contain any methods that must be implemented, it's only for discoverability purposes by the plugin system. The SoWebObject parameter becomes the mapping name used to reference the control in configuration files.

[SoWebObject("SoDialogSimpleCard")]
public class DialogSimpleCard :Card, IWebObject
{
  ...
}

Applicable implicit types

Type	Description
AjaxMethods	Server-side web methods invoked by AjaxMethodDispatcher.CallSync\|CallAsync.
Control	AspNet web controls.
IArchiveAction	Runs when an archive control is selected
IArchiveControlDataFetcher	Use by SoArchive Control to invoke archive providers and return formatted results.
ICard	A layout control inside a panel.
IControlGroup	A layout control inside a view.
IDataHandler	Acts as a controller that loads data, populates view models, and saves changes.
IFilter	User to remove items from display output. `Filterbase` and `CustomCheckFilter`.
IMDOControlDataFetcher	Used by MDO Control to invoke MDO providers and return formatted results.
IPanel	A layout control inside a page.
IValidation	Used to validate a controls' state.
IView	A layout control inside a card.
IViewStateProvider	Used to get and set currents.
UserControl	AspNet user controls.