Third party custom field

A guide to implement a third party custom field.

A third party custom field is a text custom field that delegates the field rendering to a third party client.

It requires a remote JavaScript script containing specific code to connect the field in Sirius.

Implementation

Third party custom field must call window.sirius.registerCustomField(fieldId, setup) in order to connect the field to Sirius.

• The fieldId is the global ID of the field that can be found in custom fields administration, you can also specify an array of strings to setup field on multiple environments.
• The setup function is called at initialization. A teardown function can be returned in the setup function,it gives you opportunity to cleanup things if necessary.

To connect the field properly you have to implement the bi-directional communication.

From field to Sirius

To notify to Sirius that the value of the field has changed, you have to call the onChange function available in the setup parameters.

input.addEventListener("input", (event) => {
  onChange(event.currentTarget.value);
});

From Sirius to field

The value of the field can also change without an action of the user, at initialization, or through subscriptions. Sirius notifies that the field value has changed by calling every render listeners. render is also available in setup parameters.

render(({ value }) => {
  input.value = value;
});

Example

This example implements a simple text field. It is willingly simple, yours will be more complex.

// third-party.js
window.sirius.registerCustomField(
  "bG9jYWw6Q3VzdG9tRmllbGQ6Mg==", // Field ID
  ({
    container,
    onChange,
    render,
    placeholder,
    required,
    disabled,
    label,
    hint,
  }) => {
    // Create a simple input field.
    const input = document.createElement("input");

    // Set every attributes from field configuration.
    input.disabled = disabled;
    input.required = required;
    input.placeholder = placeholder || "";

    // Add field into the provided container that will
    // display the field in Sirius interface.
    container.appendChild(input);

    // Setup communication from field to Sirius by listening "input" event
    // and calling `onChange` function.
    input.addEventListener("input", (event) => {
      onChange(event.currentTarget.value);
    });

    // Setup communication from Sirius to field by listening for "render"
    // the value of the input is updated when it changed.
    render(({ value }) => {
      input.value = value;
    });
  },
);

API

window.sirius.registerCustomField

/** Options passed to setup function */
interface FieldSetupParams {
  /** Field id */
  id: string!
  /** Field container */
  container: HTMLDivElement;
  /** Field label */
  label: string | null;
  /** Field placeholder */
  placeholder: string | null;
  /** Field hint */
  hint: string | null;
  /** Field required */
  required: boolean;
  /** Field disabled */
  disabled: boolean;
  /** Change handler, must be called to update field value. */
  onChange(value: string): void;
  /** Render function, called when the field is updated. */
  render(params: { value: string }): void;
}

/** A function called when the field is unmounted, an opportunity to clean things. */
interface FieldTeardown {
  (): void;
}

/** A function called when the field is unmounted, an opportunity to clean things. */
interface FieldSetup {
  (options: FieldSetupParams): FieldTeardown;
}

interface Window {
  /** Entry point to setup a custom field */
  registerCustomField(fieldId: string | string[], setup: FieldSetup): void;
}