customlookup

---

The customlookup property allows you to create a data-driven, module-backed selector within Page Builder. Unlike basic input types, customlookup fields query your own logic using Miva modules. This enables support for custom business logic, filters, relationships, and other dynamic data sets.

customlookup Definition

{
  "code": "product_filter",
  "prompt": "Choose a Product Filter",
  "type": "customlookup",
  "placeholder": "Start typing to filter",
  "lookup": {
    "module_code": "custom_module",
    "module_function": "CustomLookup_Load",
    "selection_column": "id",
    "default_sort": "name",
    "title": "Select Filter",
    "columns": [
      {
        "code": "id",
        "header": "ID",
        "type": "numeric",
        "sortable": true,
        "searchable": true
      },
      {
        "code": "name",
        "header": "Name",
        "type": "text",
        "sortable": true,
        "searchable": true
      }
    ]
  }
}

Supported Fields

Field	Type	Required	Description
code	string	Yes	Unique key used in l.settings:instance.
prompt	string	Yes	Label shown in the admin interface.
type	string	Yes	Must be "customlookup".
required	boolean	No	If true, a value must be selected before saving.
placeholder	string	No	Hint text shown inside the input before a selection is made.
lookup	object	Yes	Defines the module/function used to generate the lookup UI.
preview_property_selector	string	No	Used to target preview DOM nodes.
visibility_conditions	object	No	Used for conditional UI logic.

Field Behavior: lookup

The lookup field defines how the selector retrieves and displays its data. The customlookup property is designed to call a module-defined function and render a result table or grid.

Sub-field	Required	Description
module_code	Yes	The Miva module that provides the lookup data
module_function	Yes	Function inside the module that generates the lookup result set
selection_column	Yes	Column key whose value is stored when a row is selected
default_sort	No	Column name used to sort data by default
title	No	Title shown on the modal (defaults to prompt if omitted)
columns	Yes	Array of columns shown in the data grid, including headers and types

Supported column types include:

• text
• numeric
• mappedtextvalues

Each column may also include:

• sortable (boolean)
• searchable (boolean)
• ondemandcolumn (boolean)

These define how the table behaves in the admin interface.

l.settings:instance Structure

The selected row’s selection_column value is stored:

:product_filter:value=12345

Only the selected value is saved. No additional object data is included.

Template Usage

<p>Selected Filter ID: &mvte:instance:product_filter:value;</p>

Use this value to load additional data as needed via template or module logic.

JavaScript Access

<script>
  var instance = <mvt:eval expr="miva_json_encode( l.settings:instance, '' )" />;
  var filterValue = instance.product_filter.value;
</script>

defaults Definition

To pre-populate a selected value, define it inside the defaults block:

"defaults": {
  "product_filter": {
    "value": 12345
  }
}

This will set the initial selection to the value matching "id" = 12345.

Best Practices

• Use for advanced, module-backed selectors such as filters, records, or external data.
• Keep the number of columns limited for usability.
• Always include selection_column — this is the only data stored.
• Use placeholder to guide users on how to interact with the lookup field.
• Return simple values — any needed enrichment should be handled by template logic or additional lookups.

Complete Example

{
  "code": "combination_facet",
  "prompt": "Facet to Apply",
  "type": "customlookup",
  "required": true,
  "lookup": {
    "module_code": "mv-mmx-combination-facet",
    "module_function": "FlexComponent_CombinationFacet_Lookup",
    "selection_column": "id",
    "default_sort": "disp_order",
    "columns": [
      {
        "code": "id",
        "header": "ID",
        "type": "numeric",
        "sortable": false,
        "searchable": false
      },
      {
        "code": "name",
        "header": "Name",
        "type": "text",
        "sortable": false,
        "searchable": false
      }
    ]
  }
}

Output

:combination_facet:value=42

Template

<mvt:assign name="g.facet_id" value="l.settings:instance:combination_facet:value" />