README

oerlikon-app-frame-react-uplink

UplinkProvider

<UplinkProvider>{children}</UplinkProvider>

UplinkProvider connects your application to the app frame with a combination of postMessage and WebSocket and automatically selects the best communication gateway for your request.

The provider should be placed early in your application because its mandatory for all uplink hooks.

UplinkProvider takes three props:

crashOnError (optional) If true (default), the UplinkProvider will act as an Error Boundary and signals the app frame that your app is crashed.
formatErrorMessage (optional)
```
(error: Error) => error.message;
```
function that gets called just before an error is passed to the app frame and displayed in a error box.
onConnectionStatus (optional)
```
(status: 'connecting' | 'connected' | 'disconnected') => void
```
function that gets called each time the connection status changes.

Hooks

useUplink

const uplink = useUplink();

gives you access to the underlying Uplink Client instance that got created by the UplinkProvider. Ideally you shouldn't use this but instead one of the following, higher level hooks.

useUplinkCommand

const [dispatcher] = useUplinkCommand(command);

lets you issue a command that gets executed in the app frame.

If the command requires a payload, the dispatcher call has to be executed with said payload.

Possible command - payload combinations:

breadcrumbs

sets / updates the breadcrumb navigation

interface Payload {
  breadcrumbs: BreadcrumbItem[];
}

interface BreadcrumbsItem {
  label: string;
  to?: string;
  identifier?: string;
  subItems?: Array<Omit<BreadcrumbsItem, 'subItems'>>;
}

identifier is useful to identify which breadcrumb item was clicked by the user. See useUplinkEvent with breadcrumb-clicked.

to will force the iframe to reload under a different path. This should be used with care because it will reload your entire app. Implementing routing on top of to-main and from-menu would be a better choice.

Example:

const [setBreadcrumbs] = useUplinkCommand('breadcrumbs');

useEffect(() => {
  setBreadcrumbs({
    breadcrumbs: [
      {
        label: 'Home',
        identifier: 'home'
      }
    ]
  });
}, []);

enable-menu

Tells the app frame, that your app supports the sidebar menu
```
interface Payload {
  entryPoint?: string;
  title?: string;
}
```
entryPoint is the url segment that gets loaded to show your menu. Defaults to menu. So your menu has to be available at https://yoururl/menu. The create-oerlikon-app tool already manages this entrypoint for you.

title shows a small text in the sidebar menu above the sidebar frame.
disable-menu

Tells the app frame, that your app no longer supports the sidebar menu. If you haven't previously called enable-menu, this command has no effect.
change-menu

lets you open or close the sidebar menu. You cannot pin / unpin the menu.
```
interface Payload {
  open: boolean;
}
```
to-menu

a communication gateway that lets your main frame send a message to your menu frame. The payload that you send with this command is up to you. You could use this gateway to implement e.g. routing.
to-main

the same as to-menu but from your menu frame to your main frame.
change-path

will force the iframe that holds your application to reload with a new path. Using to-main and from-menu is a better way to implement routing.
```
interface Payload {
  path: string;
}
```
crash

will tell the app frame that your application is in a crashed, non-recoverable state. The user will be prompted with the options to close or reload your application
```
interface Payload {
  reason?: string;
}
```
your can pass an optional reason that will be displayed in the prompt.
terminate

will force the app frame to completly close your application without displaying any message.

this command has no payload.
enable-kiosk-mode-support

Tells the app frame that your app is supporting the kiosk feature. This will show an kiosk mode button in the top right action bar
disable-kiosk-mode-support

Inverse of enable-kiosk-mode-support
disable-kiosk-mode

will leave the kiosk mode if active

notification

will show a notification in the bottom left corner

You should use the respective package for this api.

interface Payload {
  text: string;
  severity?: 'success' | 'warning' | 'info' | 'error';
  autoHide?: number | false;
  identifier?: string | number;
  actions?: Array<{ label: string; identifier?: string }>;
}

useUplinkEvent

useUplinkEvent(eventName, payload => {});

Lets you listen for events that happen in the app frame. If the event has a payload, this payload will be provided as first argument of your callback function.

Possible eventName - payload combinations:

breadcrumb-clicked

Executed when a user clicked on one of your provided bredcrumb items. You have to provide breadcrumbs for this event to get dispatched.
```
interface Payload {
  breadcrumb: {
    label: string;
    identifier?: string;
  };
}
```
suspended

Executed when your app is moved in the background. You should listen to this event and immediatly stop all expensive computations. While in a suspended state, your app won't receive any events except resumed
resumed

Executed when your app moves from the background back in the foreground.
from-menu

When you send data from your menu frame with to-main to your main frame, this event will be dispatched.
from-main

Same as from-menu, but from your main main frame to your menu frame.
menu-change

Called when the menu state in the app frame changes. You could adjust your layout to the new iframe size in this callback.
```
interface Payload {
  pinned: boolean;
  open: boolean;
}
```
search

Executed when the user entered text in the search input field. This callback will trigger on every keypress. If you listen to this event, the app frame will automatically show the corresponding input field.
```
interface Payload {
  term: string;
}
```

user

Called with the currently logged in user information.

This event will execute immediatly and also on every change.

interface Payload {
  user_id: string;
  user_name: string;
  user_zone: string;
  name: string;
  given_name: string;
  family_name: string;
  email: string;
}

settings

Called with the current settings.

This event will execute immediatly and also on every change.

interface Payload {
  decimalPlaces: number;
  thousandSeparator: string;
  decimalSeparator: string;
  currency: string;
  lang: string;
  dateFormat: 'DMY' | 'MDY' | 'YMD';
  timeFormat: '12' | '24';
  timezone: string;
  folderColor: string;
}

access-token

Called with the current access-token.

This event will execute immediatly and also on every token renew.

important!!!

this event will likely change in the future. Keep an eye out for updates.
```
interface Payload {
  accessToken: string;
}
```
help

Called when the user presses the help button.

This event has no payload.
kiosk-mode

Called when the user enters or leaves the kiosk mode
```
interface Payload {
  active: boolean;
}
```
notification-action

Called when the user interacts with a notification action

You should use the respective package for this api.
```
interface Payload {
  label: string;
  identifier?: string;
}
```

useUplinkData

const data = useUplinkData(eventName, defaultValue);

This is an alternative and often preferred way to process event data inside your component. As soon as an event is dispatched, the return value (state) of this hook will change. You can provide a defaultValue to avoid a check for undefined in your component.

This works with all events listed for the useUplinkEvent hook, expect the ones without any payload. Currently this excludes the events help, suspended and resumed.

@oerlikon/react-uplinkdeprecated

Usage no npm install needed!