Home Documentation Download License Contact

Custom Components And Functions

The M4 Back Office application can be customized, adding custom components, user controls, data templates or functions. These items can be developed with Microsoft Visual Studio. For each item a ClassDefinition is added to the Application Model. You also have the option to create templates to use any tape of settings or even other custom items. These templates are also saved with the Application Model.
You can also add your classes to the list of defined items in AppSettings.xml, so they can be chosen easily from a selection box.

This chapter gives you an overview of the different types of custom elements you can use. In the subsequent chapters, more information can be found on each item type.

Types Of Custom Classes

The following types of classes can be used. The key is used in the DefinedClassesData section of AppSettings.xml. Classes with this key will be added to the SelectedClass list in the Application Model.

Application And Access Model

The GroupReader property in AppModel allows you to define a reader for users, groups and roles.
SearchReader and ExportAdapter can be defined on AccessModel and AccessModelNode scope. If not defined in AccessModelNode, they are inherited from AccessModel.
CustomSearchParameters provide data validation on user input and custom SQL parameters.
Field and node validations are used for custom data manipulation, setting data error messages and to exclude saving or closing of records.
CustomCondition sets the applicability of permits.

Key Defined In Required Type Standard Classes
GroupReader AppModel IGroupReader Application Model Groups Reader
Active Directory Groups Reader
SearchReader AccessModel ISearchReader Parameterized Search Reader
SearchReader AccessModelNode ISearchReader Parameterized Search Reader
ExportAdapter AccessModel IExportAdapter CSV Export Adapter
XML Export Adapter
ExportAdapter AccessModelNode IExportAdapter CSV Export Adapter
XML Export Adapter
CustomSearchParameters SearchParameterField ICustomSearchParameters None
FieldValidation AccessField IFieldValidation Is Mandatory
Matches Regular Expression
Is E-Mail Address
Copy Modified Value
NodeValidation AccessNode INodeValidation Compare Field1 with Field2
CustomCondition ConditionParameterField ICustomCondition None


Here you can set the controls for the Components section of the Application Model.
Setting the ClientControl will replace the complete client interface.
At the moment, only a test VoiceAdapter is available to demonstrate the integration into the application. The IVoiceAdapter interface is really simple to allow the integration of a wide range of phone systems.
The StartPage can be any component. It is added at the top of the component tree and preselected.
A ComponentControl is the control for the items in the components tree.
SettingsControl applies only to the M4 Creator. It lets you define a custom editor for the component.

Key Defined In Required Type Standard Classes
ClientControl ComponentModel IComponent Side Bar Client
VoiceAdapter ComponentModel IVoiceAdapter Voice Test Adapter
StartPage ComponentModel IComponent News
ComponentControl ComponentDefinition IComponent Tree Employ Component
SettingsControl ComponentDefinition IComponent None

Tree Employ Component

The defined component Tree Employ Component contains other custom items.
EmployRowComponent lets you define a control for a specified access node, while EmployFieldTemplate and SearchFieldTemplate set data templates for individual access and search fields.

Key Defined In Required Type Standard Classes
EmployRowComponent EmployRowComponent IEmployRowComponent None
EmployFieldTemplate EmployFieldTemplate IEmployFieldTemplate None
SearchFieldTemplate SearchFieldTemplate ISearchFieldTemplate None

Adding Custom Items To The Application Model

In the Application Model all custom items are added using a ClassDefinition property. The first ClassDefinition can be found in the Application Model root node. Go to the Application Model root node and expand the GroupReader property.

Saleperson DataRootNode and AccessModelNode

The ClassDefinition contains the following properties:

  • RequiredType
    The type the custom class must implement or inherit from.
  • DefinedClassName
    The full name of the class that currently is used. The defined class can be tested, verifying library location, class name and class type.
  • SelectedClass
    Title of a class predefined in AppSettings.xml or [Custom Class]. Set to [Custom Class] to use the class defined in the CustomClass property.
  • Template
    An instance of the defined class. Templates allow you to set properties in your class. Theses properties can be simple value types, other classes or even other custom items.
  • CustomClass
    Library and class name of class. Libraries paths can be absolute, relative to the application directory or server paths. It is also possible to use HTTP addresses.

DefinedClassesData In AppSettings.xml

If you use a custom item frequently, it is more convenient just to select it from the SelectedClass list box, instead of setting file and class name each time.
To add a class to the list box, you have to add it to AppSettings.xml. The M4 standard classes are also defined in AppSettings.xml. Here you see the definitions for the GroupReader property.

    <Title>Application Model Groups Reader</Title>

    <Title>Active Directory Groups Reader</Title>

NOTE: AppSettings.xml can be found and modified in the application directory in the folder Settings. You can also create custom distributions of M4 Back Office, that allow you to create installation packages containing a modified version of AppSettings.xml.
Read more in the next chapter on custom distributions.

The DefinedClassesData contain the following fields:

  • GuidData
    Unique GUID ID. This ID is added to the Application Model to identify the selected class.
    NOTE: You can get a new GUID using M4 Creator. Open an Application Model and select "Application Model/Copy new GUID to clipboard" in the main menu.
  • ClassName
    Full class name of the defined class.
  • IsDefault
    If true, the class is used, until no other class is selected.
    Only one class of each type can be the default class.
  • Key
    Identifies the custom class type. You can find the value in the tables of custom class types above.
  • Title
    Title shown in the selection list.

If the class definition does not contain any information about the library of the class, the class loader assumes, that the library is found in the program directory with the name of the root namespace. In our example the class M4.GroupReader.ActiveDirectoryGroupReader is excepted to be found in the library M4.dll.
If your library has a different name or is located somewhere else, you can specify LibraryData for it.

    <Title>My Groups Reader</Title>


    <Title>My Groups Reader</Title>