kimaai.admin.fieldComponents

When it fires

In the browser, in the KimaAI settings app, each time it draws fields: a settings page, a section card, a Connections panel, the entry form of a list. A field of the settings schema names its component by key ('component' => 'MyAddonPostcodeField'), and the app looks the key up in what this filter returns. A field whose key is not there is not shown. So an add-on that adds its own settings page with kimaai_settings_schema_files can draw a field with its own component.

The filter runs many times while someone works in the settings. Return the same components each time and define them once, outside the callback: a new function on every call is a new component to React, which draws the field anew and loses the focus while someone types. A key KimaAI uses itself replaces its component wherever KimaAI uses it, so give yours keys of their own.

The script that adds the filter is loaded on the KimaAI settings page (hook suffix toplevel_page_kimaai) with wp-hooks and wp-element as dependencies, so it runs before the settings app draws its first page. The guide “Your own setting field” (docs/guides/field-components.md) builds a whole add-on: its settings file, the component as a setting row, the script and the props a component gets.

Parameters

NameTypeDescription
componentsObjectThe React components by key, KimaAI’s own (TextField, ToggleField, SelectField and others) and those added with registerFieldComponent().

Returns

Object: The components by key.

Example

(function (wp) {
  function PostcodeField(props) {
    return wp.element.createElement('input', {
      type: 'text',
      'aria-label': props.label,
      value: props.value || '',
      inputMode: 'numeric',
      maxLength: 5,
      onChange: function (event) {
        props.onChange(event.target.value.replace(/\D/g, ''));
      },
    });
  }

  wp.hooks.addFilter('kimaai.admin.fieldComponents', 'my-addon/postcode-field', function (components) {
    return Object.assign({}, components, {MyAddonPostcodeField: PostcodeField});
  });
})(window.wp);

A field with 'component' => 'MyAddonPostcodeField' and 'props' => ['label' => 'Postcode'] is now drawn with this input, which keeps only digits. props.value is the stored value (or the field’s default), props.onChange sets a new one, which the page saves with its other settings. The field’s props from the schema arrive as props too, label here.

  • kimaai_settings_schema_files: adds the settings page with the field.
  • kimaai_trigger_button_click: a button on that page, without a component of your own.

What are your feelings