Skip to main content

Widget metadata

Metadata is an object stored on the server-side, which describes the widget and sets some default properties regarding props, layouts, and other things.

Store widget metadata​

  {
    id: 387,
    port: 5678,
    name: 'PFX_Widget',
    domain: 'info',
    placement: 'header',
    widgetId: '201',
    widgetDetails: {
      title: 'PFX',
      type: 'Header',
      description: 'PFX widget',
      innerTags: [],
      tags: ['basic'],
      contextRules: {
        type: 'none'
      }
    },
    layout: {
      minW: 1,
      maxW: Infinity,
      minH: 5,
      maxH: Infinity
    },
    url: 'repo url',
    version: '0.0.1',
    defaultProps: {
      apiUrl: "_internal_api_",
    },
    settingsSchema: {
      uiSchema: {},
      jsonSchema: {},
      extraErrors: {},
      title: "Pie Chart Settings"
    }
  }

id​

  • Unique id for the widget

port​

  • The post is calculated as 5+port that make a widget available in the widget store

name​

  • Widget name, used in internal module federation tooling to generate meta on exposed submodules, see module-federation docs section
  • Can contain prefix - Core_ for common widgets or company name initials/abbreviation for custom widgets

domain​

  • Not really defined, could be connected with the widget families idea, to unify groups of widgets that share common props/apis/ways of communication

placement​

  • Connected to domain; see the list of domain-replacement pair here

widgetDetails​

  • Additional data that can be used by the composer.
type WidgetDetailsT = {
  title: string;
  type: string;
  description: string;
  innerTags: string[];
  tags: string[];
  contextRules?: {
    type: "none" | "dynamic" | "strict";
    keys?: string[];
  };
};

contextRules​

Some widgets require query params for proper working query param

And these params could be required and non-required.

Examples:

  • dynamic
contextRules: {
  type: "dynamic",
  keys: ["contactId", "branchId"]
}

Widget will appear in composer menu if url search params contains /dashboard?contactId=, /dashboard?branchId= or none of them.

  • strict
contextRules: {
  type: "strict",
  keys: ["contactId"]
}

Widget will appear in composer menu only if url search params contains /dashboard?contactId=

  • none
contextRules: {
  type: "none";
}

Widget doesn't depend on search params, behaviour by default.

  • Regular expressions

For wide consuming you can use regular expressions

contextRules: {
  type: "strict",
  keys: ["/^phone/i"]
}

/dashboard?phoneNumber=, /dashboard?phoneNum=, /dashboard?phoneUser=

widgetType​

  • Widget type: for the platform (widgetType === 0), for the dashboard (widgetType === 1) or universal (widgetType === 2) - which fits both.

layout​

  • Some default layout boundaries used connected with the react-grid-layout grid on the dashboard.
  • Default size of the widget could be set through this.

url​

  • Url should contain a string with a repository link.

version​

  • Widgets versioning is still TBD.

defaultProps​

  • Component props that widget instance will receive when dragged to the dashboard.
  • Usually, this set of props has 100% or close intersection with things a user can edit in widget settings in dashboard composer.

Platform widget metadata​

Company-specific widgets that customize particular UIs of the platform. They are stored on the customization backend. However, right now we use this type of widget for various workarounds outside of the dashboard > widgets model - like widgets in lightboxes and so on.

 {
    name: "DE_SideNav",
    widgetId: '149',
    domain: "navigation",
    placement: "SideNav",
    version: "0.0.1",
    defaultProps: {}
  },

domain and placement​

  • These props are used to find a particular component of the platform, which this custom widget should be replaced.

Platform APIs still in discussion​

Leftovers from the previous spec discussions, which could be useful in the future, when we will continue defining the platform and its capabilities.

Locales​

  • A set of ISO locale keys is available on the platform.
  • Locales are stored in the widget and should be accessible with ISO keys.
  • i18n implementation is TBD.

Widget External Datasources API (in discussion)​

Some widgets could be communicating with third party. The question is - should we make it mandatory to list such endpoints in the widgets metadata?

Right now we do not limit endpoints that could be set through the composer/widget props, so is there a point having the externalAPI section?