Skip to main content
BuyLog In
XAF: Cross-Platform .NET App UI & Web API
Search in…
Docs > Concepts > Business Model Design > Data Types Supported by built-in Editors > Reference (Foreign Key, Complex Type) Properties
A newer version of this page is available. .
All docs
V19.1
eXpressApp Framework
Fundamentals
.NET Core 3.0 Support in XAF WinForms Applications
Getting Started
Concepts
Application Solution Components
Business Model Design
Business Model Design Basics
Built-in Business Classes for Most Popular Scenarios
Business Model Design with Entity Framework
Business Model Design with XPO
Non-Persistent Objects
PropertyChanged Event in Business Classes
Data Types Supported by built-in Editors
Key Properties
String Properties
Numeric Properties
Date and Time Properties
Boolean Properties
BLOB Image Properties
Collection Properties
Reference (Foreign Key, Complex Type) Properties
Reference Properties in XPO
Reference Properties in Entity Framework
File Attachment Properties
Type Properties
Enumeration Properties
Criteria Properties
Color Properties
Geolocation Properties
Miscellaneous Property Types
Mapping Complex Types to the Database
Types Info Subsystem
Connect an XAF Application to a Database Provider
Data Annotations in Data Model
Create and Update the Application's Database
Application Model
UI Construction
Controllers and Actions
Data Manipulation and Business Logic
Security System
Localization
System Module
Extra Modules
Debugging, Testing and Error Handling
Filtering
Application Life Cycle
Design-Time Features
Deployment
Task-Based Help
Frequently Asked Questions (FAQ)
API Reference
Download CHM

Reference (Foreign Key, Complex Type) Properties

  • 9 minutes to read

Reference properties are properties of Types that are added to the Application Model (when the property type is a persistent or non-persistent business class). Reference properties (and Collection Properties) allow you to set up relationships between business objects. In XAF, reference properties can be displayed in the following:

  • A lookup control;
  • A set of editors. Each editor displays an individual referenced object property;
  • A Detail Property Editor that represents the referenced object’s Detail View (WinForms and ASP.NET applications only);
  • A button editor that expands a referenced object Detail View in a separate modal window (typically used for aggregated objects).

The images below demonstrate how to display reference properties on different platforms:

Note

Refer to the Property Editors | Reference Properties section in the Feature Center demo installed with XAF to see Reference Property Editors in action. The Feature Center demo is installed in %PUBLIC%\Documents\DevExpress Demos 19.1\Components\eXpressApp Framework\FeatureCenter by default. The ASP.NET version of this demo is available online at https://demos.devexpress.com/XAF/FeatureCenter/.

Examples

UI-Independent Property Editors for Reference Properties

DetailPropertyEditor

The DetailPropertyEditor creates a Template that represents a Frame and contains a Detail View. The Detail View is determined automatically according to the object type and displays the object the reference property specifies. To specify a custom Detail View, use the IModelMemberViewItem.View property in the Model Editor.

The following controls visualize the DetailPropertyEditor:

Platform Control
WinForms NestedFrameTemplateV2
ASP.NET NestedFrameControlNew
Mobile MobileWindowTemplate

WinForms Property Editors for Reference Properties

Each WinForms Property Editor has a control that displays a corresponding property in a Detail View, and a repository item that displays a property in a List Editor that supports in-place editing. Both the control and repository item are shown below.

Editor Control Repository Item
ObjectPropertyEditor ObjectEdit - a ButtonEdit editor descendant the IntegerPropertyEditor uses. RepositoryItemObjectEdit - a descendant of the XtraEditors Library’s RepositoryItemButtonEdit item.
LookupPropertyEditor LookupEdit - a descendant of the XtraEditors Library’s PopupContainerEdit editor. RepositoryItemLookupEdit - a descendant of the XtraEditors Library’s RepositoryItemPopupContainerEdit item.

ObjectPropertyEditor

The ObjectPropertyEditor displays the aggregated reference properties. Clicking the editor’s button, double-clicking the editor, or pressing SPACEBAR invokes the Detail View. You can modify the referenced object in this Detail View and click OK to save changes. Refer to the Add Actions to a Popup Window and Dialog Controller topics for details on how to customize this window.

Tip

You can focus the ObjectPropertyEditor and press SPACEBAR or ENTER to invoke the ObjectPropertyEditor‘s Detail View.

LookupPropertyEditor

The LookupPropertyEditor displays non-aggregated reference properties and provides a drop-down list with the LookupControlTemplate Template. You can choose an object from this list and assign it to the current reference property.

Tip

LookupPropertyEditor Hotkeys

Hotkey Description
ALT+DOWN Expands the drop-down list.
CTRL+SHIFT + Click Invokes a Detail View for the selected object in the drop-down list.

ASP.NET Property Editors for Reference Properties

Each ASP.NET Property Editor has controls that display a property in a Detail View‘s View and Edit mode (see DetailView.ViewEditMode). These controls are listed below.

Editor View Mode Control Edit Mode Control
ASPxObjectPropertyEditor LinkButton XafASPxButtonEdit - a ASPxButtonEdit editor descendant.
ASPxGridLookupPropertyEditor LinkButton ASPxGridLookup
ASPxLookupPropertyEditor LinkButton ASPxLookupDropDownEdit or ASPxLookupFindEdit

ASPxObjectPropertyEditor

The ASPxObjectPropertyEditor displays aggregated reference properties. This Property Editor inherits the ASPxObjectPropertyEditorBase class, which creates a Link button, a NavigateToObject Action and raises the Action’s Execute event when a user clicks Link. The Execute event handler invokes a separate window that displays a read-only Detail View of the object the current property references.

The ASPxObjectPropertyEditor creates a ButtonEdit and an ObjectWindow PopupWindowShowAction and raises the Action’s Execute event when the button is clicked. A separate window is invoked in the Execute event handler which displays a Detail View representing the object the property references. Clicking OK saves changes made to the object and assigns it to the property (if it is unassigned). Refer to the Add Actions to a Popup Window and Dialog Controller topics for details on how to customize the invoked window.

The ASPxObjectPropertyEditor is not designed to update other editors when its pop-up control is closed in inline edit mode, so the ImmediatePostDataAttribute does not affect it.

ASPxGridLookupPropertyEditor

Used for non-aggregated reference properties.

This Property Editor inherits the ASPxObjectPropertyEditorBase class, which creates a LinkButton and a NavigateToObject Simple Action, and raises the Action’s Execute event when a user clicks the link button. The Execute event handler creates a window which displays a read-only Detail View of the referenced object.

With the ASPxGridLookupPropertyEditor, users can create and modify referenced objects using the Add and Edit buttons. The Clear button clears the editor value. To hide this button, set the IModelCommonMemberViewItem.AllowClear property to False in the Model Editor.

The ASPxGridLookupPropertyEditor uses the default Lookup List View’s Application Model settings (ObjectName_LookupListView) or a View the IModelMemberViewItem.View property specifies. To specify which columns are visible in the ASPxGridLookupPropertyEditor, locate the corresponding List View’s Columns node in the Model Editor (for example, View | Contact_LookupListView | Columns) and change the columns list.

The ASPxGridLookupPropertyEditor displays the value of a property the IModelCommonMemberViewItem.LookupProperty model option specifies, by default. You can format the display value using the IModelCommonMemberViewItem.DisplayFormat property. When setting the display value format, you can use format specifiers and property names. For instance, {0:FirstName}, {0:Birthday:MM.yyyy} or {0:Manager.Birthday}. This format also works in the View edit mode. The underlying ASPxGridLookup control’s TextFormatString and DisplayFormatString properties depend on the DisplayFormat property value. Thus, the DisplayFormat property determines which lookup columns participate in Incremental Filtering.

ASPxGridLookupPropertyEditor Specificities

  • ASPxGridLookupPropertyEditor does not create inline grid Actions (for example, the Edit Action).
  • ASPxGridLookupPropertyEditor does not support objects that do not exist in the data source.
  • The Lookup List View’s EditorType value should be set to the ASPxGridListEditor type. Otherwise, a runtime exception occurs.
  • The property type should have a key field. The underlying ASPxGridLookup control requires a key field for edit and select operations. Otherwise, a runtime exception occurs.

Refresh the ASPxGridLookupPropertyEditor’s Data Source

There are instances when a ASPxGridLookupPropertyEditor‘s data source should be refreshed. For example, when you implement cascading filter for lookup List Views. To refresh this data source, use the PropertyEditor.Refresh, ViewItem.Refresh, or ViewItem.RefreshDataSource methods. The following Controller, which demonstrates how to do this, refreshes the data source of the Manager Property Editor after the Department property is changed.

using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Web.Editors.ASPx;
// ...
public class RefreshDataSourceController : ObjectViewController<DetailView, Contact> {
    protected override void OnActivated() {
        base.OnActivated();
        View.ObjectSpace.ObjectChanged += ObjectSpace_ObjectChanged;
    }
    private void ObjectSpace_ObjectChanged(object sender, ObjectChangedEventArgs e) {
        if(e.PropertyName != "Department") return;
        ASPxGridLookupPropertyEditor lookup = View.FindItem("Manager") as ASPxGridLookupPropertyEditor;
        if(lookup != null) {
            lookup.RefreshDataSource();
        }
    }
    protected override void OnDeactivated() {
        View.ObjectSpace.ObjectChanged -= ObjectSpace_ObjectChanged;
        base.OnDeactivated();
    }
}

ASPxLookupPropertyEditor

The ASPxLookupPropertyEditor displays non-aggregated reference properties.

This Property Editor inherits the ASPxObjectPropertyEditorBase class, which creates the Link button and a NavigateToObject SimpleAction, and raises the Action’s Execute event when a user clicks the link button. The Execute event handler creates a window which displays a read-only Detail View of the referenced object. Users can clear the editor value with the Clear button. To hide this button, set the IModelCommonMemberViewItem.AllowClear property to False in the Model Editor.

The ASPxLookupPropertyEditor creates an ASPxLookupFindEdit or ASPxLookupDropDownEdit control. The ASPxLookupFindEdit control is created in the following cases when the search functionality is enabled:

  • When the number of displayed records exceeds the IModelOptions.LookupSmallCollectionItemCount value;
  • When the BOModel | Class | Member or Views | <DetailView> | Items | <PropertyEditor> node’s LookupEditorMode property is set to AllItemsWithSearch or Search.

Otherwise, the ASPxLookupPropertyEditor creates the ASPxLookupDropDownEdit control.

Access the ASPxLookupPropertyEditor’s Inner Controls

You can access the ASPxLookupDropDownEdit and ASPxLookupFindEdit controls using the ASPxLookupPropertyEditor class’s DropDownEdit and FindEdit properties. These properties provide access to the inner ASPxComboBox and ASPxButtonEdit controls which can be accessed through the DropDown and Editor properties, respectively.

using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Web.Editors.ASPx;
using DevExpress.Web;
// ...
public class InitializeLookupControlsController : ObjectViewController<DetailView, Contact> {
    protected override void OnActivated() {
        base.OnActivated();
        ASPxLookupPropertyEditor managerEditor = View.FindItem("Manager") as ASPxLookupPropertyEditor;
        if(managerEditor != null) {
            if(managerEditor.Control == null) {
                managerEditor.ControlCreated += managerEditor_ControlCreated;
            }
            else {
                InitializeLookupControls(managerEditor);
            }
        }
    }
    private void managerEditor_ControlCreated(object sender, EventArgs e) {
        InitializeLookupControls(((ASPxLookupPropertyEditor)sender));
    }
    private void InitializeLookupControls(ASPxLookupPropertyEditor lookupEditor) {
        if(lookupEditor.FindEdit != null) {
            ASPxButtonEdit buttonEdit = lookupEditor.FindEdit.Editor;
            // ... 
        }
        if(lookupEditor.DropDownEdit != null) {
            ASPxComboBox comboBox = lookupEditor.DropDownEdit.DropDown;
            // ... 
        }
    }
}

Mobile Property Editors for Reference Properties

Each Mobile Property Editor has widgets that display a property in a Detail View‘s View and Edit mode (see DetailView.ViewEditMode). These widgets are listed below.

Editor View Mode Control Edit Mode Control Description
MobileObjectPropertyEditor Label that displays text using the div HTML element. Button that uses the dxButton widget. Displays aggregated reference properties.
MobileLookupPropertyEditor Label that displays text using the div HTML element. Lookup that uses the dxLookup widget. Displays non-aggregated reference properties.

Note