Custom Menu Items

In the HelloWorld and Coffee To Go examples in the WebRunnableBundle the menuItems function was implemented to export the service package icon into the Service Launcher card, from where user can run it. There are other places, where the service package functionality can be triggered. As for now, it is allowed to add service packages custom icons into the dock area and into the Spring Board card:

There is an example in the SDK package named menuitems that showcases how to implement this.

MenuItem implementation

In order to implement any custom icon for the service package, a MenuItem should be exported in the runnable bundle.

export interface MenuItem {
  id: string;
  menuId: MenuIdentifier; // ServicesLauncher | SettingsMenu | DockElement | SpringBoardMenu
  title: string;
  description?: string;
  styleHints?: MenuItemStyleHints;
  position: number;
  component?: MenuComponentType;
  callback?: MenuCallbackType;
  testId?: string;
  svgIcon?: (props: { width: number; height: number }) => React.ReactElement;
}

Depending on the type of MenuItem, its optional fields may be additionally ignored or required.

For ServicesLauncher type fields svgIcon, callback and title are required and component is ignored.

For most of other types svgIcon is ignored, component is required and callback is optional.

The component parameter, when needed, should be implemented as a React Component which should match the following type definition: React.Component<MenuComponentProps>.

position field defines in which order icons will be rendered in set of icons of one type for one service package.

MenuComponentProps contains fields:

{
  device: Entity;
  user: Entity;
  menuItem: MenuItem;
  data?: any;
}

It allows component to get the device and user Entity, get the properties of its MenuItem and receive container-specific data.

For the menu items that are rendered by the component, the callback parameter, if defined, will not be used automatically as in case of ServicesLauncher type. The UI interaction has to be implemented inside the component implementation. But it might be useful to define reaction in callback function outside and use it inside the component:

onClick = () => {
  if (this.props.menuItem.callback) {
    this.props.menuItem.callback(this.props);
  }
};

title and description will not be rendered automatically for the icons, that require component. But it is possible to use them inside of the component renderer by accessing props.menuItem.

Dock area

In order to add a custom icon into the dock area, a runnable bundle of a service package should export a MenuItem of type SettingsMenu as shown below:

menuItems: () => [
  {
    id: "MenuItem_Dock",
    menuId: MenuIdentifier.DockElement,
    title: "Menu Icons",
    testId: "MenuIcon_testId_Dock",
    position: 1,
    component: MenuIconComponent,
    description: "DockElement example icon",
    callback: doSomething
  }
];

Here is the renderer example with style for the icon component to align it well with the other icons on the dock area:

interface CSSPropertiesObject {
  [name: string]: React.CSSProperties;
}

private renderDocker(): React.ReactNode {
  return (
    <ThemeContext.Consumer>
      {({theme}) => {
        const iconStyle: CSSPropertiesObject = {
          container: {
            width: theme.sizeOf.dockItemSize,
            height: theme.sizeOf.dockItemSize,
            flex: 1,
            flexDirection: "row",
            alignItems: "center",
            justifyContent: "center"
          },
          image: {
            width: theme.sizeOf.dockIconSize,
            height: theme.sizeOf.dockIconSize
          }
        };
        return (
          <View onClick={this.onClick} style={iconStyle.container}>
            <Image source={logo} style={iconStyle.image} />
          </View>
        );
      }}
    </ThemeContext.Consumer>
  );
}

ThemeContext should be used to get the sizes, margins and colors of the client common elements. In this case dockItemSize and dockIconSize were used to get the standard docker item sizes.

The data property in props of component inside the docker area container will be undefined.

Spring Board card area

MenuItem for Spring Board card should be defined like this:

{
  id: "MenuItem_Spring",
  menuId: MenuIdentifier.SpringBoardMenu,
  title: "Menu Icons",
  testId: "MenuIcon_testId_Spring",
  position: 1,
  component: MenuIconComponent,
  description: "SpringBoardMenu example icon",
  callback: doSomething
}

The data property in props of component inside the Spring Board card area container will be undefined.