Develop a Custom Component Library for App Builder

Each library has the following structure:

your-library-directory
├── components/
│   └── component-internal-name/
│       ├── form.json
│       ├── metadata.json
│       └── layout.json
└── assets/(optional)

components/: Root directory for all custom components in the library.

• Each subdirectory represents a single component.

component-internal-name/: Directory for a custom component.

• This name will be utilized in the component declaration as ${COMPONENT_INTERNAL_NAME}.
• Used to associate configuration files with the component's runtime implementation.

form.json: Defines the component's configuration UI in the App Builder.

• Specifies:
  • Field definitions and default values.
  • Tabs and form layout.
  • Conditional logic using deps.
  • Async selectors and data sources.
• Does not define rendering or runtime behavior.

metadata.json: Defines display metadata for the component picker.

• Has no impact on runtime logic or render behavior.
• Has the following structure:

{
    "name": "Component Name",
    "icon": "briefcase"
}

• name: Human-readable label shown in the App Builder.
• icon: Internal name of the icon from the core application displayed next to the component.

layout.json: Defines component layout.

• Has the following structure:

{
    "flex-direction": "column",
    "justify-content": "flex-start",
    "align-items": "stretch",
    "justify-self": "",
    "align-self": "",
    "width": "",
    "height": "",
    "margin": "",
    "padding": "0",
    "background-color": "",
    "border-color": "",
    "border-radius": "",
    "border-width": "",
    "resizable": "off",
    "font-size": "13px",
    "font-family": "",
    "color": "",
    "size-type-width": "auto",
    "size-type-height": "auto",
    "background-image": "",
    "background-size": "",
    "background-repeat": ""
}

assets/: Optional directory that may contain the built code for the components.

The form.json file defines the settings panel displayed in the App Builder.

File Structure:

{
  "fields": {...},
  "settings": {
    "tabs": [
      {
        "name": "Tab Name",
        "components": [...]
      }
    ]
  }
}

The fields section defines field defaults and special field behavior:

{
  "fields": {
    "simple_field": {
      "default": "default_value"
    },
    "asset_field": {
      "variable": "image",
      "item_type": "asset"
    },
    "dataset_field": {
      "variable": "dataset_id",
      "item_type": "dataset",
      "default": ""
    }
  }
}

• default: Default field value.
• variable:  Variable name for special fields.
• item_type:  asset (files) or dataset (datasets).

Once you have configured component properties, proceed to write code that will integrate those components into the App Builder as described below.

1. Register the component in the global declarations registry:

MI.builder.Declarations['${LIBRARY_INTERNAL_NAME}.${COMPONENT_INTERNAL_NAME}'] = {
  "libraries": ['${LIBRARY_INTERNAL_NAME}']
};

• ${LIBRARY_INTERNAL_NAME}: Your library's internal name; e.g., core.
  • NOTE: The Internal name of the Library that will be created in MI must match this value.
• ${COMPONENT_INTERNAL_NAME}: Your component's internal name; e.g., navigation-tile.
  • NOTE: ${COMPONENT_INTERNAL_NAME} must match the name of the directory where the component is located.
• The full key: core.navigation-tile.

2. Define component's behavior with the constructor:

MI.builder.Components['${LIBRARY_INTERNAL_NAME}.${COMPONENT_INTERNAL_NAME}'] = function (uid, params) {
  this.uid = uid;
  this.settings = params.settings;
  this.stateKey = params.settings.stateKey??'';
  this.parentEl = null;
  // ...
};

• uid: Unique identifier for this component instance.
• params.settings: Configuration object containing values from form.json.
  • See Configure Component Properties in form.json for details.

3. Optionally, enable reactivity by subscribing to state changes:

if (this.stateKey > '') {
  MI.state.subscribe(this.stateKey, (state, oldState) => {
    if (
      this.parentEl &&
      JSON.stringify(state) !== JSON.stringify(oldState)
    ) {
      this.render(this.parentEl);
    }
  });
}

How it works:

• Subscribes only if stateKey is provided.
• Re-renders the component when state value changes.
• Avoids unnecessary renders when state is unchanged.

4. Render method:

this.render = (parentEl) => {
  this.parentEl = parentEl; // Store element reference
  this.parentEl.innerHTML = ''; // Clear existing content
  let state =
    this.stateKey > '' ? MI.state.getState(this.stateKey) : ''; // Retrieve state
  // Create wrapper div for React
  let divContainer = document.createElement('div'); 
  divContainer.setAttribute(
    'id',
    this.parentEl.getAttribute('id') + '-react-wrapper' // Create wrapper <div>
  );
  this.parentEl.appendChild(divContainer);
  // 5. Render React component
  MiComponents.render({
    containerId: divContainer.getAttribute('id'),
    props: {
      component: '${COMPONENT_INTERNAL_NAME}', // Mount React component
      settings: this.settings,                  
      state: state,                            
    },
  });
};

• Render flow:
  1. Store the parent element reference.
  2. Clear existing DOM content for this component instance.
  3. Retrieve state (if applicable).
  4. Create and append a wrapper <div> used as the React mount point.
  5. Calls MiComponents.render() to mount the React component with settings and state.

Once you have built a library with custom components, add it to App Builder by either uploading the asset directly as a ZIP file, or via a Git sync. You must also enter the code from the previous step into App Builder's Code tab to enable the library.