Advanced Binding (to Business Objects)

• Jan 23, 2019
• 8 minutes to read

This topic describes the specifics of binding a lookup editor to a business object.

Unlike the standard lookup mode, which means that the editor’s edit value is of a simple data type (e.g., integer), the binding of the lookup editor to a business object employs its own business object identification mechanism. This mechanism implies that a business object has a key field(s) that ensures object uniqueness. You must specify this key field name(s) using the RepositoryItemLookUpEditBase.KeyMember property.

The business object identification mechanism functions as follows. When the editor’s dropdown is invoked showing the records of the lookup data source, the editor should find a match for its edit value (a business object) among the lookup records. A value(s) from the business object’s key field(s) is obtained and compared with key field values of each lookup record. Once the match is found, it is highlighted in the dropdown.

When an end-user selects a certain lookup record in the dropdown, this record (the object that encapsulates this record) is assigned to the lookup editor’s edit value. Ensure that the data type of lookup records is accepted by the editor’s edit value.

The following properties need to be specified when binding a lookup editor to a business object:

• RepositoryItemLookUpEditBase.DataSource - This identifies the lookup data source - a list of records (objects) displayed in the editor’s dropdown.

• RepositoryItemLookUpEditBase.KeyMember - Specifies a key field (or multiple key fields) used for business object identification.

  The RepositoryItemLookUpEditBase.KeyMember property is supported for all lookup editors, in standalone and inplace modes.

• RepositoryItemLookUpEditBase.DisplayMember - Specifies the field (from the lookup data source) whose values are displayed in the lookup editor’s edit box.

For standalone lookup editors, these properties are available from the editor’s Properties object (e.g., LookUpEdit.Properties). In-place lookup editors are presented by corresponding RepositoryItem class descendants - RepositoryItemLookUpEdit, RepositoryItemGridLookUpEdit, RepositoryItemSearchLookUpEdit and RepositoryItemTreeListLookUpEdit. Thus, the described properties are explicitly available.

Certain lookup editors may need additional customization (e.g., customize columns in the dropdown, specify the dropdown window’s width and height, enable text editing, etc.). See the Lookup Editors and Main Settings topic and the LookUpEdit, GridLookUpEdit, SearchLookUpEdit and TreeListLookUpEdit class descriptions for more information.

For a standalone lookup editor, its edit value is specified by the BaseEdit.EditValue inherited property (this property is bindable). For an inplace editor, its value is provided by a cell in which the editor is embedded.

Example

Assume that you have two types of business objects (Product and Category), defined as follows:

C#

public class Product {
    public Category Category { get; set; }
    public string ProductName { get; set; }
}

public class Category {
    public int ID { get; set; }
    public string Name { get; set; }
}

VB.NET

Public Class Product
    Public Property Category() As Category
    Public Property ProductName() As String
End Class

Public Class Category
    Public Property ID() As Integer
    Public Property Name() As String
End Class

A Data Grid is bound to a list of Product business objects.

C#

gridControl1.DataSource = new List<Product> {
    new Product(){ ProductName="Chang", Category = new Category() { ID = 0 } },
    new Product(){ ProductName="Ipoh Coffee", Category = new Category() { ID = 0 } },
    new Product(){ ProductName="Ravioli Angelo", Category = new Category() { ID = 1 } },
    new Product(){ ProductName="Filo Mix", Category = new Category() { ID = 1 } },
    new Product(){ ProductName="Tunnbröd", Category = new Category() { ID = 1 } },
    new Product(){ ProductName="Konbu", Category = new Category() { ID = 2 } },
    new Product(){ ProductName="Boston Crab Meat", Category = new Category() { ID = 2 } }
};

VB.NET

gridControl1.DataSource = New List(Of Product) From {
    New Product() With {
        .ProductName = "Chang", .Category = New Category() With {.ID = 0}
    },
    New Product() With {
        .ProductName = "Ipoh Coffee", .Category = New Category() With {.ID = 0}
    },
    New Product() With {
        .ProductName = "Ravioli Angelo", .Category = New Category() With {.ID = 1}
    },
    New Product() With {
        .ProductName = "Filo Mix", .Category = New Category() With {.ID = 1}
    },
    New Product() With {
        .ProductName = "Tunnbröd", .Category = New Category() With {.ID = 1}
    },
    New Product() With {
        .ProductName = "Konbu", .Category = New Category() With {.ID = 2}
    },
    New Product() With {
        .ProductName = "Boston Crab Meat", .Category = New Category() With {.ID = 2}
    }
}

Note that the Category.Name field in the grid’s data source may not even be initialized.

If you run the example without additional customization, the grid will look like the image below.

A lookup editor will be used to display category names in the Category column and allow an end-user to edit this column by selecting categories from a dropdown list.

All available categories are stored in the following list, which will be a lookup data source for the grid’s inplace lookup editor (RepositoryItemLookUpEdit).

C#

var categories = new List<Category> {
    new Category(){ ID = 0, Name = "Beverages" },
    new Category(){ ID = 1, Name = "Grains" },
    new Category(){ ID = 2, Name = "Seafood" },
};
//...

RepositoryItemLookUpEdit riLookUp = new RepositoryItemLookUpEdit();
riLookUp.DataSource = categories;

VB.NET

Dim categories = New List(Of Category) From {
    New Category() With {.ID = 0, .Name = "Beverages"},
    New Category() With {.ID = 1, .Name = "Grains"},
    New Category() With {.ID = 2, .Name = "Seafood"}
}

A lookup editor is assigned to the grid control’s Category column. Thus, the editor’s edit value will be a Category business object.

C#

gridView.Columns["Category"].ColumnEdit = riLookUp;

VB.NET

gridView1.Columns("Category").ColumnEdit = riLookUp

To allow the lookup mechanism to find a match between the editor’s value (a Category business object) and Category business objects in the lookup data source, a key field (“ID”) is assigned to the RepositoryItemLookUpEditBase.KeyMember property.

C#

riLookUp.KeyMember = "ID";

VB.NET

riLookUp.KeyMember = "ID"

Now, the lookup mechanism is able to find a match by comparing the ID field value of the editor’s bound business object with the ID field values in the lookup data source.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/lookup-editor-advanced-business-objects-binding-using-keymember-t377757

Form1.cs

using DevExpress.XtraEditors.Repository;
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Windows.Forms;

namespace Lookup_KeyMember {
    public partial class Form1 : Form {
        public Form1() {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e) {
            var categories = new List<Category> {
                new Category(){ ID = 0, Name = "Beverages" },
                new Category(){ ID = 1, Name = "Grains" },
                new Category(){ ID = 2, Name = "Seafood" },
            };

            gridControl1.DataSource = new List<Product> {
                new Product(){ ProductName="Chang", Category = new Category() { ID = 0 } },
                new Product(){ ProductName="Ipoh Coffee", Category = new Category() { ID = 0 } },
                new Product(){ ProductName="Ravioli Angelo", Category = new Category() { ID = 1 } },
                new Product(){ ProductName="Filo Mix", Category = new Category() { ID = 1 } },
                new Product(){ ProductName="Tunnbröd", Category = new Category() { ID = 1 } },
                new Product(){ ProductName="Konbu", Category = new Category() { ID = 2 } },
                new Product(){ ProductName="Boston Crab Meat", Category = new Category() { ID = 2 } }
            };

            RepositoryItemLookUpEdit riLookUp = new RepositoryItemLookUpEdit();
            riLookUp.KeyMember = "ID";
            riLookUp.DisplayMember = "Name";
            riLookUp.DataSource = categories;

            gridView1.Columns["Category"].ColumnEdit = riLookUp;
        }
    }

    public class Product {
        public Category Category { get; set; }
        public string ProductName { get; set; }
    }

    public class Category {
        public int ID { get; set; }
        public string Name { get; set; }
    }
}

Form1.vb

Imports DevExpress.XtraEditors.Repository
Imports System
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Data
Imports System.Drawing
Imports System.Linq
Imports System.Text
Imports System.Threading.Tasks
Imports System.Windows.Forms

Namespace Lookup_KeyMember
    Partial Public Class Form1
        Inherits Form

        Public Sub New()
            InitializeComponent()
        End Sub

        Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs) Handles MyBase.Load
            Dim categories = New List(Of Category) From { _
                New Category() With {.ID = 0, .Name = "Beverages"}, _
                New Category() With {.ID = 1, .Name = "Grains"}, _
                New Category() With {.ID = 2, .Name = "Seafood"} _
            }

            gridControl1.DataSource = New List(Of Product) From { _
                New Product() With { _
                    .ProductName="Chang", .Category = New Category() With {.ID = 0} _
                }, _
                New Product() With { _
                    .ProductName="Ipoh Coffee", .Category = New Category() With {.ID = 0} _
                }, _
                New Product() With { _
                    .ProductName="Ravioli Angelo", .Category = New Category() With {.ID = 1} _
                }, _
                New Product() With { _
                    .ProductName="Filo Mix", .Category = New Category() With {.ID = 1} _
                }, _
                New Product() With { _
                    .ProductName="Tunnbröd", .Category = New Category() With {.ID = 1} _
                }, _
                New Product() With { _
                    .ProductName="Konbu", .Category = New Category() With {.ID = 2} _
                }, _
                New Product() With { _
                    .ProductName="Boston Crab Meat", .Category = New Category() With {.ID = 2} _
                } _
            }

            Dim riLookUp As New RepositoryItemLookUpEdit()
            riLookUp.KeyMember = "ID"
            riLookUp.DisplayMember = "Name"
            riLookUp.DataSource = categories

            gridView1.Columns("Category").ColumnEdit = riLookUp
        End Sub
    End Class

    Public Class Product
        Public Property Category() As Category
        Public Property ProductName() As String
    End Class

    Public Class Category
        Public Property ID() As Integer
        Public Property Name() As String
    End Class
End Namespace