Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Collapse]eXpressApp Framework
 [Expand]Fundamentals
 [Expand]Getting Started
 [Collapse]Concepts
  [Expand]Application Solution Components
  [Expand]Business Model Design
  [Collapse]Application Model
   [Expand]Model Editor
    Application Model Basics
    Business Model in the Application Model
    Application Model Structure
    Access the Application Model in Code
    Extend and Customize the Application Model in Code
    Built-in Nodes Generators
    Convert Application Model Differences
    Model Difference Storages
  [Expand]UI Construction
  [Expand]Extend Functionality
  [Expand]Data Manipulation and Business Logic
  [Expand]Security System
  [Expand]Localization
  [Expand]System Module
  [Expand]Extra Modules
  [Expand]Debugging and Error Handling
  [Expand]Filtering
  [Expand]Application Life Cycle
 [Expand]Design-Time Features
 [Expand]Functional Testing
 [Expand]Deployment
 [Expand]Task-Based Help
 [Expand]Frequently Asked Questions
 [Expand]API Reference
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
[Expand]End-User Documentation

Extend and Customize the Application Model in Code

You can customize the information loaded to the Application Model via the Model Editor. It allows you to edit the information at design time, forming Application Model layers in each project. The layers are superimposed onto one another in a certain order. Values from every successive layer override the corresponding values from the previous layer (see the Application Model Basics topic). There is one more approach you can use to customize the information stored in the Application Model. In most cases, this approach is less suitable because the changes to be made in the Application Model are performed in code. But this approach is useful when the feature that you implement in a module demands the modification of the information generated in the Application Model by default. When implementing a new feature, you may need to add custom nodes to the Application Model. You may also need to customize an existing node by adding custom properties to it. In this way, you can allow other developers or end-users to change the behavior of your code by modifying your custom nodes and properties in the Model Editor. This topic explains how to extend and customize the Application Model in Code. To learn how the Application Model's structure is formed refer to the Application Model Structure topic.

Several typical scenarios are provided in this topic. You can select one of them or combine them to handle more complex customizations.

Tip

If it is required to access properties exposed by an existing node, use the approach described in the Access the Application Model in Code topic.

Important

Always use a Node Generator or Generator Updater to customize the current node and its child nodes. To update nodes outside the current node hierarchy, create separate Node Generators or Generator Updaters.

Expanded Add a Custom Property to the Existing Node

To add new properties to an existing node, you should first define an interface and expose the required properties:

Then, extend the required node in your Module or Controller. Override the ModuleBase.ExtendModelInterfaces method or implement the IModelExtender interface, respectively.

Rebuild your solution and open the Model Editor to see how the code above affects the Application Model.

The IModelApplication node now exposes the MyCustomProperty property. To add the property to another node, substitute the interface corresponding to the required node, instead of the IModelApplication (see Application Model Structure).

You can decorate node properties with the following attributes.

Attribute Description
Browsable Indicates that a property is visible in the Model Editor. All properties added via the approach described above are visible, by default. To hide a property, decorate it with the Browsable attribute and pass false as the attribute's parameter.
Category Specifies the target property category. The properties of each node are grouped by their categories in the Model Editor's property grid. The default category is "Misc". To assign a category to a property, decorate the property with the Category attribute and pass a category name as the attribute's parameter. If the specified category does not exist, it will be added.
DataSourceProperty Specifies a name of the property that exposes a list of the target property's possible values. You will be able to choose a value via the drop-down list in the Model Editor's property grid. When the current property's node exposes a list of child nodes (implements the IModelList<ChildNodeType> interface, as illustrated in the Extend The Application Model with New Nodes section), you can pass "this" as the DataSourceProperty attribute parameter. As a result, the child nodes list will be the current property possible values list.
DefaultValue Specifies the target property's default value.
Editor Binds a custom editor to the property (see EditorAttribute).
Description Specifies the target property's description displayed in the Model Editor.
Localizable Specifies that the target property can be localized. To define a localizable property, decorate it with the Localizable attribute and pass true as the attribute's parameter.
ReadOnly To prohibit property value modification via the Model Editor, decorate the property with the ReadOnly attribute and pass true as the attribute's parameter. Alternatively, you can omit the property's setter. But, the ReadOnly attribute affects only the Model Editor, and does not restrict the property modification in code.
Required Indicates that a target property should have a value. The Model Editor will not allow you to save changes until you supply this property value.

Examples of some of these attributes in use will be provided later in this topic.

Note

Do not create the property named "Application". Otherwise, this property will hide the node's inherited IModelNode.Application property. Hiding the Application property causes the "Cannot compile the generated code" exception.

Expanded Extend the Application Model with New Nodes

The extension of the Application Model with new nodes is performed similarly to adding new properties. First, you should define interfaces representing your custom nodes and their properties. Note that you should derive from the IModelNode interface when you define an interface that specifies a separate node.

As you can see, each custom node is derived from the IModelNode interface. The IModelMyNodeWithChildNode node exposes a single IModelMyChildNode child node.

Note

When determining whether a property will be a child node or value, the existence of the setter in its declaration is taken into account. If the property has a setter, then it will not automatically be filled with values, and vice versa. So, the MyChildNode property has no setter (marked as ReadOnly in VB).

The IModelMyNodeWithChildNodes node exposes the list of IModelMyChildNode nodes, as it supports the IModelList<IModelMyChildNode> interface.

You can decorate interfaces, representing nodes, with the following attributes.

Attribute Description
Description Specifies the target node's description displayed in the Model Editor.
DisplayName Specifies the node's display name, which is used as the node's caption in the Model Editor.
DisplayProperty Specifies the node's property name, whose value is used as the node's caption in the Model Editor.
ImageName Specifies the node's image, which is used in the Model Editor. See the ImageNameAttribute topic for additional information.
KeyProperty Specifies the node's key property. The key property is used to identify nodes. Only a string property can be a key property. If the KeyProperty attribute is omitted, the Id key property is generated automatically. The use of this attribute is illustrated in the code above.

To add these nodes to a certain parent node in the Application Model, extend the required node's interface, as described in the Add a Custom Property to the Existing Node section of this topic.

Rebuild your solution and open the Model Editor to see how the code above affects the Application Model.

You can add child nodes to the MyNodeWithSeveralChildNodes node via the context menu.

Expanded Customize the Application Model via the Nodes Generator Class

In some scenarios, implementing logic to be executed when the custom node is added to the Application Model is a requirement. The so-called Generator classes serve this purpose. The Generator is the ModelNodesGeneratorBase descendant. The ModelNodesGeneratorBase class exposes the GenerateNodesCore virtual method. To implement required logic, override this method. To access the node for which the generator is invoked, use the method's node parameter. The following snippet illustrates Generator implementation.

Note

The node parameter exposes the Application property, providing you with access to the whole Application Model.

This Generator creates ten IModelMyChildNode nodes and assigns indexes to them. To apply the Generator to the required node, use the ModelNodesGeneratorAttribute attribute.

Each Node can have only one generator. However, additional customizations can be performed via the Generator Updaters

Rebuild your solution and open the Model Editor to see how the code above affects the Application Model.

Note

The Generator affects the Application Model zero layer. So, the GenerateNodesCore method will be automatically executed on demand when the data stored in the MyNodeWithSeveralChildNodes is required for the first time. For details on the Model layers, refer to the Application Model Basics topic. To ensure that the generator is executed only once, you can do the following.

  • Set the breakpoint inside the GenerateNodesCore method.
  • Run the Windows Forms application.
  • Invoke the run-time Model Editor. The application execution will be interrupted.
  • Continue the application execution and close the Model Editor.
  • Invoke the run-time Model Editor once again. The application execution will not be interrupted. The Application Model's zero layer already contains all the required information at this moment, so there is no need to invoke the Generator again.

Expanded Implement a Property Having a List of Predefined Values

Let's assume that the IModelMyNodeWithChildNodes node should expose the SelectedChildNode property, representing the "selected" child node. The user-friendly approach is to provide a drop-down, allowing you to choose one of the valid values in the Model Editor. So, the property should have a list of predefined values. This property can be implemented in the following manner.

Generally the DataSourceProperty attribute can be used to specify a name of the current node's property which exposes a list of the target property's possible values. Additionally, you can pass "this" as the DataSourceProperty attribute parameter (as illustrated in the code above). In this case, a list of the target property's possible values will be filled with the current node's child nodes.

Rebuild your solution, and open the Model Editor to see how the code above affects the Application Model.

You can add and remove child nodes, and the drop-down list will reflect changes instantly.

Note

To define a more complex logic for generating a list or predefined values, implement the supplementary calculated property holding the required list as described in the text section of this topic. Then, make this property hidden, by applying the Browsable(false) attribute to it. Finally, decorate your target property with the DataSourceProperty attribute and pass the supplementary hidden property name as the parameter. Note that the list items must be of the same type as the target property.

Expanded Use the Domain Logic to Implement the Calculated Property

To customize the node's properties behavior, the Domain Logic (which is a part of the Domain Components technology) can be used. The common use case of Domain Logic is implementing calculated properties. The following code illustrates how to implement the NumberOfChildNodes property, which gets the number of current node's child nodes.

The DomainLogicAttribute in the code above indicates that the MyNodeWithMultipleChildNodesLogic class represents the Domain Logic for the IModelMyNodeWithChildNodes node. This class exposes the Get_NumberOfChildNodes method, executed when getting the NumberOfChildNodes property value. This method returns the number of IModelMyChildNode child nodes exposed by the IModelMyNodeWithChildNodes node. For details on Domain Logic, refer to the Domain Components Basics topic.

Rebuild your solution, and open the Model Editor to see how the code above affects the Application Model.

You can add and remove child nodes, and the NumberOfChildNodes property value will reflect changes instantly.

Expanded Add the Generator Updaters

Each node can have a single Generator assigned. However, you can "attach" one or more Updaters to the Generator. The Generator Updater is the ModelNodesGeneratorUpdater<T> class' descendant. This class exposes the IModelNodesGeneratorUpdater.UpdateNode virtual method. To implement the required logic, override this method. To access the node for which the Updater is invoked, use the method's node parameter. The following snippet illustrates the implementation of two Generator Updaters.

Note

The node parameter exposes the Application property, providing you with access to the whole Application Model.

The first Updater sets the IModelMyChildNode.MyIntegerProperty values. The second sets the IModelMyNodeWithChildNodes.SelectedChildNode property value. All the Updaters should be registered in the overridden ModuleBase.AddGeneratorUpdaters method.

Rebuild your solution and open the Model Editor to see how the code above affects the Application Model.

Note

If you previously modified these property values in the Model Editor, you should reset differences for the MyNodeWithSeveralChildNodes node to see the changes. To do this, right-click this node and select Reset Differences. The reason for this is that the Updaters operate at the Application Model zero layer, and changes can be overridden in higher layers.

The example above illustrates how to customize a custom Nodes Generator's behavior. However, you can use the same approach to "attach" Generator Updaters to built-in Nodes Generators. The following topics provide complete examples of implementing Generator Updaters for built-in Generators.

Expanded See Also

How would you rate this topic?​​​​​​​