SmartClient 14.0: Relation Fields and Shuttle Interface

SmartClient 14.0 fully automates the display, editing, and update of data relationships – including one-to-many, many-to-one, and many-to-many. You simply declare the relationship in your DataSource, and SmartClient does the rest. No coding required.

This capability is powered by three major features: Relation Fields, MultiPickerItem, and the Shuttle Interface. Together, they provide a declarative, scalable, and user-friendly approach to managing relational data.

Relation Fields

In both databases and object-oriented systems, a relation connects an object to one or more other objects. A classic example is an order with multiple line items (1-to-many). More complex are many-to-many relationships, such as students enrolled in multiple courses, with each course having multiple students.

A common setup involves three tables: one for each main entity (for example, Employees and Teams) and a connector table (such as TeamMembers) linking them.

With SmartClient, you can add a multi-valued field (for example, teams in the Employees table) that uses a foreignKey through the link table to the related table. A fetch automatically looks up the related records in the pivot table and populates the array of IDs. The includeFrom setting can bring in display values like names.

When you update that array, SmartClient automatically updates the link table, adding, removing, or replacing relationships, with no extra code required. This means you can manage many-to-many associations entirely through declarative configuration.

<field 
    name="EmployeeId" 
    title="Employee" 
    displayField="EmployeeName" 
    foreignDisplayField="Name"
    foreignKey="teamMembers_relation.employees_relation.EmployeeId" 
    multiple="true" 
/>
<field 
    name="EmployeeName" 
    hidden="true" 
    includeFrom="employees_relation.Name" 
    multiple="true" 
/>

This setup connects teams to employees (a Many-to-Many relation) and handles everything from value resolution to text display with no additional logic.

Key Features

Declarative configuration: Just declare a field as a relation to another DataSource. Whether your backend is SQL, JPA, REST, or anything else, SmartClient automatically handles all data retrieval and update operations.
Instant, Codeless UI: Bind a grid or form to a DataSource with Relation Fields, and SmartClient instantly renders UI controls for viewing and editing those relationships, no additional code needed.

See the Relation Field showcase for live examples.

Editing Related Records: Shuttle Interface and `MultiPickerItem`

To complement Relation Fields, SmartClient 14.0 introduces two powerful UI components for managing many-to-many relationships: the Shuttle Interface and MultiPickerItem. Each is designed for different usage contexts, one for inline form editing, the other for full dual-grid interaction.

`MultiPickerItem`

MultiPickerItem is a compact UI control for selecting multiple related records. It’s automatically used in forms when a field has a multi-valued foreignKey and requires no manual configuration. It provides an intuitive UX for choosing related records. That includes displaying selected values as a comma-separated list and opening a pop-up list for editing selections using checkboxes.

The foreignKey relationships allow you to add additional fields to tables that refer back to an existing table. These link tables can automatically populate an array of values from the existing table.

In forms, MultiPickerItem is used automatically when the field has a multi-valued foreignKey. In editable grids, you can enable it by specifying:

editorType: "MultiPickerItem"

The example below shows MultiPickerItem in an editable grid. Selected values appear inline, and the pop-up allows users to select from a related DataSource using checkboxes.

Applying “is one of” filter using MultiPickerItem

Explore the MultiPicker Fields sample.

A related component, SetFilterItem, is used in search forms and filter UIs. It provides a simple, checkbox-based UI for selecting multiple filter values, and supports inclusion and exclusion operators such as “is one of” and “is not one of”. This makes it easy for users to define in-set or not-in-set filters without needing custom logic.

SetFilterItem is automatically shown when users choose these operators in a filtering context. It’s designed to help users define in-set or not-in-set criteria without needing to understand the data structure underneath.

You can see this in action in the image below, where the Category field uses SetFilterItem to build filter criteria visually.

You can see this in action in the Set Filtering sample, where fields like Category and Units use SetFilterItem to build filter criteria visually.

Explore the Set Filtering sample.

Shuttle Interface

The Shuttle Interface is a full dual-grid control ideal for visual editing of many-to-many relationships. It displays all available records on the left and selected records on the right. Users can drag, double-click, or use arrow controls to move records between panels.

Shuttle is available as a standalone component that can be embedded directly in forms, modals, or any layout, and a ShuttleItem, a subclass of MultiPickerItem that uses the Shuttle appearance.