RTE-Controller

RTE UI controller is a module to be used in the UI resource itself to facilitate the integration with RTE world.

How to Use?

Install

cd path/to/your project
npm i rte-controller --save-dev

Use

Create RteContext instance

• If the RTE App is running as a HTTP Server

import { createDefaultRteContext } from '@agora-rte/rte-controller';

const rteContext = await createDefaultRteContext({
  uri: 'http://127.0.0.1:8001/',
  graph_id: '0',
  extension_group: 'default_ui_gateway_extension_ts_group',
  extension: 'default_ui_gateway_extension_ts',
});

• If the RTE App is running in the rendering thread of electron, you can specify uri to localhost or empty. Then rte-controller will transfer message between javascript function calls with the Exported RTE object.

import { createDefaultRteContext } from '@agora-rte/rte-controller';

const rteContext = await createDefaultRteContext({
  uri: 'http://127.0.0.1:8001/',
  graph_id: '0',
  extension_group: 'default_ui_gateway_extension_ts_group',
  extension: 'default_ui_gateway_extension_ts',
});

Use with RTE layout template

Create RteContext first.

import { mountRteUiWidgets } from '@agora-rte/rte-controller';

// Mount fetched UI widgets into DOM.
await mountRteUiWidgets(
  rteContext,
  document.getElementById('ui-container') as HTMLElement,
);

Use with your own layout

Create RteContext first.

ReactDOM.render(
  <>
    <div
      style={{
        width: '400px',
        backgroundColor: 'lightgray',
      }}
    >
      <ExtensionContainer
        rteContext={rteContext}
        extension='extension_a'
      ></ExtensionContainer>
    </div>
    <div
      style={{
        width: '600px',
        backgroundColor: 'yellow',
      }}
    >
      <ExtensionContainer
        rteContext={rteContext}
        extension='extension_b'
      ></ExtensionContainer>
    </div>
  </>,
  targetRenderContainer,
);

You can use widgetProps in ExtensionContainer to define any props, which will be passed to the widget component directly. For example:

<ExtensionContainer
  extension='default_ui_extension_ts'
  rteContext={rteContext}
  widgetProps={{
    renderItem: (): React.ReactElement => {
      return <div>aaa</div>;
    },
  }}
></ExtensionContainer>

Define widget props in the UI Extension

You can define the widget props in the UI Extension, and rte-controller will fetch it from the UI Extension in rendering the widget. For example:

{
  "extension_group": {
    "addon": "default_extension_group",
    "name": "ui_extension_group"
  },
  "extension": {
    "addon": "default_ui_extension_ts",
    "name": "default_ui_extension_ts"
  },
  "prop": {
    "widget_props": "{\"mode\": \"demo\"}"
  }
}

The widget_props will be parsed in JSON format.

Customize the timing of receiving message

By default, rte-controller will start to receive message when all the widgets are mounted.

You can customize with setWidgetMountedListener() in RteContext. For example:

import {
  RteContext,
  RteUiWidgetInfo,
} from '@agora-rte/rte-controller';

rteContext.setWidgetMountedListener(
  (
    rteContext: RteContext,
    widget: RteUiWidgetInfo,
    error?: Error,
  ): void => {
    console.log(
      `The widget is ready, ${JSON.stringify(widget)}, error: ${error}`,
    );

    // Calling 'readyToReceiveExtensionMessage()' to open the message channel between the App and RTE Extension, and will receive events from RTE Extension if any.
    setTimeout(() => {
      rteContext.readyToReceiveExtensionMessage();
    }, 5000);
  },
);

Keep in mind that you have to call readyToReceiveExtensionMessage() yourself when the App is ready to receive messages from RTE Extension.

Subscribe events

You can subscribe event from RTE Extension like the UI Widget with subscribeEvent() in RteContext. For example:

rteContext.subscribeEvent({
  extension: 'default_ui_extension_ts',
  handler: (msg: RteUiWidgetMsg) => {
    console.log(
      `Receive message from default_ui_extension_ts: ${JSON.stringify(
        msg,
      )}`,
    );
  },
});

The extension and type are used to filter the events, you have to specify at least one. And of course, you can specify both of them.

And you can use unsubscribeEvent() to cancel the subscription.