Multi Relate Field Type

1. Introduction

The multirelate field type is used to represent a relationship to multiple records from another module, typically for selecting multiple related entities (e.g., prospect lists, suppression lists).

2. Pre-requisite - Relationship definition

For a multirelate field to function correctly, a relationship must be defined between the module containing the field and the related module. This relationship can be either many-to-many or one-to-many.

Example from the Email Marketing module defining a many-to-many relationship link to Prospect Lists:

Note that this is only the link field definition. The actual relationship definition would be in a separate file.

        //related fields.
        'prospectlists' => [
            'name' => 'prospectlists',
            'vname' => 'LBL_PROSPECT_LISTS',
            'type' => 'link',
            'relationship' => 'email_marketing_prospect_lists',
            'source' => 'non-db',
        ],

3. Configuration Options

A multirelate field supports the following configuration options:

Option Description Required

Option	Description	Required
`name`	The field name.	Yes
`type`	Must be set to `multirelate`.	Yes
`vname`	The label key for display.	Yes
`module`	The related module name (e.g., `ProspectLists`).	Yes
`link`	The name of the link field or relationship.	Yes
`source`	Should be set to `non-db` (not stored directly in the database).	Yes
`rname`	The field name to display from the related module (e.g., `name`).	Yes
`filterOnEmpty`	Boolean. If true, applies filter when the field is empty.	No
`showFilter`	Boolean. Controls whether to show a filter UI.	No
`filter`	Array. Static or dynamic filters to apply to the related records. - See the Filter option documentation for details.	No
`metadata`	Array. UI metadata for displaying related records, such as: - `headerField`: Field to use as the header. - `subHeaderField`: Field to use as the sub-header. Supports specifying the field name, type (e.g., `enum`), and additional options such as the list of values to display.	No

name

The field name.

Yes

type

Must be set to multirelate.

Yes

vname

The label key for display.

Yes

module

The related module name (e.g., ProspectLists).

Yes

link

The name of the link field or relationship.

Yes

source

Should be set to non-db (not stored directly in the database).

Yes

rname

The field name to display from the related module (e.g., name).

Yes

filterOnEmpty

Boolean. If true, applies filter when the field is empty.

showFilter

Boolean. Controls whether to show a filter UI.

filter

Array. Static or dynamic filters to apply to the related records.

- See the Filter option documentation for details.

metadata

Array. UI metadata for displaying related records, such as:

- headerField: Field to use as the header.

- subHeaderField: Field to use as the sub-header. Supports specifying the field name, type (e.g., enum), and additional options such as the list of values to display.

4. Example

Taken from the Email Marketing module, the following example shows a multirelate field used to select multiple prospect lists:

'prospect_list_name' => [
    'name' => 'prospect_list_name',
    'vname' => 'LBL_TARGET_LISTS',
    'type' => 'multirelate',
    'required' => true,
    'link' => 'prospectlists',
    'source' => 'non-db',
    'module' => 'ProspectLists',
    'rname' => 'name',
    'metadata' => [
        'headerField' => [
            'name' => 'name',
        ],
        'subHeaderField' => [
            'name' => 'list_type',
            'type' => 'enum',
            'definition' => [
                'options' => 'prospect_list_type_dom',
            ]
        ],
    ],
    'filterOnEmpty' => true,
    'showFilter' => false,
    'filter' => [
        'attributes' => [
            'id' => 'campaign_id'
        ],
        'preset' => [
            'type' => 'prospectlists',
            'params' => [
                'parent_field' => 'propects_lists',
                'parent_module' => 'Campaigns',
            ],
        ],
        'static' => [
            'list_type' => ['seed', 'default']
        ]
    ],
],

5. Notes

The multirelate field is not stored directly in the database (source: non-db).
Used for many-to-many or one-to-many relationships where multiple selections are required.