Form Customization (Form Hook)

The platform provides Form Hook and Data Hook — form-level customization mechanisms that implement field defaults, linkage, show/hide, read-only, required, option lists, and data transformation. These capabilities replace the legacy field-level customization (Field Hook / Dynamic Field Hook), which has been removed from the platform.

Target Audience

The target audience for this document is: developers and implementers of this system

Overview

Both Form Hook and Data Hook reference a Dynamic Logic object and are configured on the DynamicForm via three fields:

Field	Type	Description
formHook.name	DynamicLogic	Form-level hook: field defaults, linkage, show/hide, read-only, required, options
formHookTriggerFields	String	Comma-separated field names; changing any of these fields in the UI re-triggers the Form Hook
dataHook.name	DynamicLogic	Data-level hook: transforms list/detail response data

TIP

The legacy "field customization" (Dynamic Field Hook, Field dependencies hook, field quick-search logic) has been removed from the platform. Use Form Hook instead.

Form Hook

Trigger Points

The Form Hook executes at:

1. Form initialization — when a create/edit form loads, to set field defaults and properties.
2. Field change — when any field in formHookTriggerFields changes in the UI (initiated = true), for field linkage.
3. Detail/list rendering — when record details are opened or list data loads, to adjust field properties based on record content.

Injected Variables

Variable	Type	Description
form	tech.muyan.dynamic.form.DynamicForm	The current form
changedFields	java.util.List<String>	Field names that triggered this execution; empty list on initialization
initiated	boolean	true when triggered by a field change; false on form initialization
object	org.grails.web.json.JSONObject	Current record data (empty map on create, persisted record on update)
owner	tech.muyan.dynamic.form.DynamicForm	Owning organization (data permission)
userContext	tech.muyan.security.MuyanAuthentication	Current user information

Return Value

Form Hook returns a Map keyed by field name. Each field entry may contain:

Key	Type	Description
value	any	Default / new field value
display	String	hide, show, or readonly
required	boolean	Required flag (false makes the field nullable)
options / enumOptions	array	Option list for select fields
min / max	number	Validation range for numeric fields
editable	boolean	Whether the field is editable
helpText	String	Field help text
other FieldProps	any	Any supported field property (including field-group extInfo)

Example:

// Field linkage driven by the orderType field
if (changedFields.contains('orderType')) {
  def type = object?.orderType
  return [
    deliveryDate: [
      value    : type == 'URGENT' ? new Date() : null,
      display  : type == 'URGENT' ? 'show' : 'hide',
      required : type == 'URGENT' ? true : false
    ]
  ]
}
// Form initialization: default options for the status field
return [
  status: [
    value  : 'DRAFT',
    options: ['DRAFT', 'SUBMITTED', 'APPROVED']
  ]
]

Configuration

Configure via CSV seed data in DynamicForm.csv:

name(*),label,description,objectType.shortName(*),type.name(*),formHook.name,formHookTriggerFields,dataHook.name,extInfo,accessRequirement.name

Create order,,,Order,CREATE,order_form_hook,orderType,customer,,
List order,,,Order,LIST,,,order_list_data_hook,,

• formHook.name: name of the Form Hook Dynamic Logic
• formHookTriggerFields: comma-separated trigger field names
• dataHook.name: name of the Data Hook Dynamic Logic

Built-in Example

The built-in DynamicFormField FormHook (code data/groovy/formHook/dynamicFormFieldFormHook.groovy) demonstrates:

• initiated == false branch: sets default options for the "field type" field and group extInfo on form initialization
• initiated == true branch: iterates changedFields and back-fills labels of the changed fields

Data Hook

Data Hook transforms list/detail API responses. Injected variables:

Variable	Type	Description
ids	array	Record ids of the queried list
offset / cursor	number/String	Pagination info
max	number	Page size
owner	object	Owning organization (data permission)
conditions / parsedConditions	object	Query conditions
userContext	tech.muyan.security.MuyanAuthentication	Current user information

Returns a Map keyed by record id; each entry holds the field values to override or supplement for that record.

TIP

Data Hook results also serve AMIS forms: AMIS form data is fetched via GET /form/data/$formId, which applies the Data Hook transformation.

Related APIs

API	Description
POST /form/formHook/$formId	Fetch Form Hook data on form initialization
POST /form/$formId/refresh	Batch refresh field properties after field change
GET /data/$domainName/$id/withFormHook?formId=	Detail data + Form Hook result
GET /form/data/$formId	AMIS form data (with Data Hook transformation)