@oerlikon/react-uplink
## UplinkProvider
Last updated 5 months ago by oerlikon-admin .
ISC · Original npm · Tarball · package.json
$ cnpm install @oerlikon/react-uplink 
SYNC missed versions from official npm registry.

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.

Current Tags

  • 1.0.0-alpha.27                                ...           latest (5 months ago)

3 Versions

  • 1.0.0-alpha.27                                ...           5 months ago
  • 1.0.0-alpha.26                                ...           5 months ago
  • 1.0.0-alpha.25                                ...           6 months ago
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (0)
None
Dev Dependencies (4)
Dependents (0)
None

Copyright 2014 - 2017 © taobao.org |