HELIO SDK

SDK for developing extensions to the HELIO visualization system.

Element SDK

The Element SDK allows creating controls, pages, etc. that can be used as building blocks of a HELIO project.

Example

import {
  createElement,
  createNamespace,
  createLibraryExtension,
  entities,
  props,
  RenderEntity,
} from '@hmiproject/helio-sdk';

// Create an extension namespace.
//
// This must use reverse domain name notation and will be used to
// reference new items in the extension.
//
// see: https://en.wikipedia.org/wiki/Reverse_domain_name_notation
const ns = createNamespace({ name: 'com.my-company' });

// Create a new HELIO Element in the namespace.
//
const customDashboardWidget = createElement(ns, {
  // This information will be used to display the element in the
  // IDEs, e.g. in the "Add Element" dialog.
  name: 'Demo Widget',
  description: 'Shows simple values on the dashboard',
  icon: { name: 'Airplane' },

  // Traits determine where this Element can be used.
  // For further information on the Traits system, consult the docs.
  traits: ['dashboard-widget'],

  // Each Element can store and use a set of properties. These will be
  // editable in the IDE and can be rendered inside the component.
  //
  // As these props may change over time, HELIO provides an automatic
  // migration framework that makes dealing with changing requirements
  // very easy.
  propsSchema: createPropsSchema()
    // V1: Initially, the element only contained a single prop called `label`.
    .initial({
      label: props.Entity({
        label: 'Label',
        defaultValue: entities.Translatable('Label'),
        valueType: 'String',
        optional: false,
      }),
    })
    // V2: A bit later, we needed to add a second prop called `value`.
    .migrate(
      {
        // The `label` prop is still used in the new version
        label: props.Entity({
          label: 'Label',
          defaultValue: entities.Translatable('Label'),
          valueType: 'String',
          optional: false,
        }),
        // Add a new `value` prop
        value: props.Entity({
          label: 'Value',
          defaultValue: entities.StaticValue(0),
          valueType: 'PrimitiveValue',
          optional: false,
        }),
      },
      // Whenever an old element instance is found in a project, HELIO
      // will automatically apply migration functions to it to make sure
      // data is in the most up-to-date state.
      //
      // Migration functions receive the previous props and need to return
      // updated props that match the new `propsSchema`.
      (prevProps) => {
        return {
          ...prevProps,
          // Provide a default `value` whenever we find an old instance
          // without that prop.
          value: entities.staticValue(0),
        };
      },
    ),

  // Whenever an instance of this element is rendered in the browser,
  // it will defer to the element's `Component`. This is a regular React
  // component that can implement arbitrary rendering logic to display
  // its UI. It also receives all the instance's `props` that were configured
  // in the IDE.
  Component: (props) => {
    return (
      // Make the element selectable in the IDE
      <div ref={props.$heRef}>
        <div>
          Label: <RenderEntity entity={props.label} />
        </div>
        <div>
          Value: <RenderEntity entity={props.value} />
        </div>
      </div>
    );
  },
});

// All new elements need to be wrapped into a `LibraryExtension`.
const extension = createLibraryExtension({
  name: 'My Company HELIO Control Library',
  description: 'Provides components for displaying KPIs in HELIO',
  version: '1.0.0',
  author: 'ACME Inc.',

  elements: [customDashboardWidget],
});

// Extensions MUST provide a default export with the library extension
export default extension;