Sending events with your widgets

Custom widgets emit events through the framework adapter’s click(), valueChanged(), onLoad(), onFilter(), or onBlur() methods. Each method optionally accepts a detail payload.

this.adapter.click('twitter');     // fires the wired click event with detail = 'twitter'
this.adapter.valueChanged(newVal); // pushes a new value AND emits onChange
this.adapter.onFilter('toyota');   // emits onFilter with detail = 'toyota'

Event names are wired in the widget definition, not in the component:

gui.actions.custom('productShare', { onClick: 'shareEvent' });

When your widget calls this.adapter.click('twitter'), the engine emits an event with name: 'shareEvent' and detail: 'twitter' to the form’s formEvent callback.

Receiving the event

The application-side handler receives a FormEvent object with the event name, the current form data, and an optional detail payload passed from the widget. In this example, productShare passes the network id (e.g. 'twitter', 'facebook', 'linkedin') as detail:

React

const SHARE_URLS: Record<string, (url: string) => string> = {
  twitter: (url) => `https://x.com/intent/tweet?text=${encodeURIComponent('Check out this product!')}&url=${encodeURIComponent(url)}`,
  facebook: (url) => `https://www.facebook.com/sharer/sharer.php?u=${encodeURIComponent(url)}`,
  linkedin: (url) => `https://www.linkedin.com/sharing/share-offsite/?url=${encodeURIComponent(url)}`,
};

function handleFormEvent(event: Core.FormEvent) {
  if (event.name === 'shareEvent') {
    const network = event.detail as string;
    const buildUrl = SHARE_URLS[network];
    if (buildUrl) {
      window.open(buildUrl(window.location.href), '_blank', 'noopener,noreferrer');
    }
  }
}

<React.FormComponent
  formDef={formDef}
  formConfig={formConfig}
  formEvent={handleFormEvent}
  // ...other props
/>

Angular

@Component({
  imports: [Angular.FormComponent],
  template: `
    <gui-form
      [formDef]="formDef"
      [formConfig]="formConfig"
      (formEvent)="handleFormEvent($event)"
    ></gui-form>
  `,
})
export class AppComponent {
  SHARE_URLS: Record<string, (url: string) => string> = {
    twitter: (url) => `https://x.com/intent/tweet?text=${encodeURIComponent('Check out this product!')}&url=${encodeURIComponent(url)}`,
    facebook: (url) => `https://www.facebook.com/sharer/sharer.php?u=${encodeURIComponent(url)}`,
    linkedin: (url) => `https://www.linkedin.com/sharing/share-offsite/?url=${encodeURIComponent(url)}`,
  };

  handleFormEvent(event: Core.FormEvent) {
    if (event.name === 'shareEvent') {
      const network = event.detail as string;
      const buildUrl = this.SHARE_URLS[network];
      if (buildUrl) {
        window.open(buildUrl(window.location.href), '_blank', 'noopener,noreferrer');
      }
    }
  }
}

Lit

const SHARE_URLS: Record<string, (url: string) => string> = {
  twitter: (url) => `https://x.com/intent/tweet?text=${encodeURIComponent('Check out this product!')}&url=${encodeURIComponent(url)}`,
  facebook: (url) => `https://www.facebook.com/sharer/sharer.php?u=${encodeURIComponent(url)}`,
  linkedin: (url) => `https://www.linkedin.com/sharing/share-offsite/?url=${encodeURIComponent(url)}`,
};

@customElement('app-page')
export class AppPage extends LitElement {
  override render() {
    return html`
      <gui-form
        .formDef=${this.formDef}
        .formConfig=${this.formConfig}
        @form-event=${(e: CustomEvent<Core.FormEvent>) =>
          this.handleFormEvent(e.detail)}
      ></gui-form>
    `;
  }

  handleFormEvent(event: Core.FormEvent) {
    if (event.name === 'shareEvent') {
      const network = event.detail as string;
      const buildUrl = SHARE_URLS[network];
      if (buildUrl) {
        window.open(buildUrl(window.location.href), '_blank', 'noopener,noreferrer');
      }
    }
  }
}

See also

• Features / Form Events — every event hook.
• Form Definition API / Events — wiring onClick and friends in the form definition.
• Action Widget — the productShare widget that fires the example event.