Function useUi

const uiApi = useUi()
Copy

Returns {
    on: <T extends keyof UiMessagePayloads>(
        type: T,
        handler: (data: UiMessagePayloads[T]) => Promise<void>,
    ) => Promise<() => void>;
    onAppSetData: (
        handler: (data: UiAppSetDataPayload) => Promise<void>,
    ) => Promise<() => void>;
    onAppUpdateData: (
        handler: (data: UiAppUpdateDataPayload) => Promise<void>,
    ) => Promise<() => void>;
    onCanvasUpdated: (
        handler: (data: UiCanvasUpdatedPayload) => Promise<void>,
    ) => Promise<() => void>;
    onMeetingCanceled: (
        handler: (data: UiMeetingCanceledPayload) => Promise<void>,
    ) => Promise<() => void>;
    onSectionListUpdated: (
        handler: (data: UiSectionListUpdatedPayload) => Promise<void>,
    ) => Promise<() => void>;
    uiBroadcast: {};
    appLoaded(): Promise<void>;
    appResize(payload: UiAppResizeRequest): Promise<void>;
    cancelMeeting(): Promise<void>;
    canvasNavigateNextPage(): Promise<void>;
    canvasNavigatePage(payload: UiCanvasNavigatePageRequest): Promise<void>;
    canvasNavigatePreviousPage(): Promise<void>;
    captureAppError(payload: UiCaptureAppErrorRequest): Promise<void>;
    closeCanvasSectionExecution(): Promise<void>;
    completePostcall(payload: UiCompletePostcallRequest): Promise<void>;
    disablePostcallSubmit(): Promise<void>;
    embeddableReady(): Promise<void>;
    enablePostcallSubmit(): Promise<void>;
    open(payload: UiOpenRequest): Promise<void>;
    openCanvasOverlay(
        payload: {
            component_id?: string;
            edit_mode?: boolean;
            fullscreen?: boolean;
            id: string;
            position?: {
                bottom?: string | number;
                left?: string | number;
                right?: string | number;
                top?: string | number;
            };
            section_id?: string;
        },
    ): Promise<void>;
    preselectSfdcMeetingId(
        payload: UiPreselectSfdcMeetingIdRequest,
    ): Promise<UiPreselectSfdcMeetingIdResponse>;
    promptPia(payload: UiPromptPiaRequest): Promise<UiPromptPiaResponse>;
    resumeMeeting(): Promise<void>;
    selectAgendaContent(
        payload?: UiSelectAgendaRequest,
    ): Promise<UiSelectAgendaResponse>;
    selectCanvases(
        payload?: UiSelectCanvasesRequest,
    ): Promise<UiSelectCanvasesResponse>;
    selectCollectionContent(
        payload?: UiSelectCollectionPlayerRequest,
    ): Promise<UiSelectCollectionPlayerResponse>;
    selectContent(
        payload?: UiSelectContentRequest,
    ): Promise<UiSelectContentResponse>;
    setPostcallStyle(payload: UiSetPostcallStyleRequest): Promise<void>;
    stopMeeting(): Promise<void>;
    toast(payload: UiToastRequest): Promise<void>;
    updateCanvas(payload: UiUpdateCanvasRequest): Promise<CanvasRetrieve>;
    updateLocation(payload: UpdateLocationPitcherEvent): Promise<any>;
}

UI API object with methods described below.

• on: <T extends keyof UiMessagePayloads>(
      type: T,
      handler: (data: UiMessagePayloads[T]) => Promise<void>,
  ) => Promise<() => void>

• onAppSetData: (handler: (data: UiAppSetDataPayload) => Promise<void>) => Promise<() => void>

• onAppUpdateData: (
      handler: (data: UiAppUpdateDataPayload) => Promise<void>,
  ) => Promise<() => void>

• onCanvasUpdated: (
      handler: (data: UiCanvasUpdatedPayload) => Promise<void>,
  ) => Promise<() => void>

• onMeetingCanceled: (
      handler: (data: UiMeetingCanceledPayload) => Promise<void>,
  ) => Promise<() => void>

• onSectionListUpdated: (
      handler: (data: UiSectionListUpdatedPayload) => Promise<void>,
  ) => Promise<() => void>

• uiBroadcast: {}

• appLoaded:function

  • appLoaded(): Promise<void>

    Notify the CatalogIQ instance that the app is loaded and ready to get the data. Triggering this method will trigger the on_app_set_data event.

    Returns Promise<void>

    Example

    
    Copy

    Example

    useUi().appLoaded()
    Copy

• appResize:function

  • appResize(payload: UiAppResizeRequest): Promise<void>

    Resize the app iframe to a given height.

    Note that initial iframe height comes from the app.json manifest file. It can also be adjusted by the user when adding app component to the canvas. In case when the app must be temporarily resized to show larger ui elements it can read the user-set height from the on_app_set_data event.

    Parameters

    • payload: UiAppResizeRequest

      object containing requested height of the iframe as the number of pixels

    Returns Promise<void>

• cancelMeeting:function

  • cancelMeeting(): Promise<void>

    Cancels current meeting and the event remains unrealized (like it never happened).

    Returns Promise<void>

    Example

    useUi().cancelMeeting()
    Copy

• canvasNavigateNextPage:function

  • canvasNavigateNextPage(): Promise<void>

    Navigate to the next page in the current canvas. Noop if the current page is the last one.

    Returns Promise<void>

    Example

    useUi().canvasNavigateNextPage()
    Copy

• canvasNavigatePage:function

  • canvasNavigatePage(payload: UiCanvasNavigatePageRequest): Promise<void>

    Navigate to a specific canvas place in the current canvas. Despite the event and parameter name, it takes the component id that we want to put in view.

    Parameters

    • payload: UiCanvasNavigatePageRequest

    Returns Promise<void>

    Example

    const uiApi = useUi() // our useApi()
    
    let activeCanvas = null
    const unsubscribe = uiApi.on_app_set_data((data) => {
      activeCanvas = data?.canvas
    })
    
    document.getElementById('my-button').addEventListener('click', () => {
      const target = activeCanvas?.content?.data?.find((i: any) => i.data.app_name === 'my-target-app-id') || null
      if (target) {
        uiApi.canvasNavigatePage({ page: target.id })
      }
    })
    Copy

• canvasNavigatePreviousPage:function

  • canvasNavigatePreviousPage(): Promise<void>

    Navigate to the previous page in the current canvas. Noop if the current page is the first one.

    Returns Promise<void>

    Example

    useUi().canvasNavigatePreviousPage()
    Copy

• captureAppError:function

  • captureAppError(payload: UiCaptureAppErrorRequest): Promise<void>

    Send an app error to Pitcher sentry instance.

    Parameters

    • payload: UiCaptureAppErrorRequest

      error object to send to Pitcher sentry instance

    Returns Promise<void>

    Example

    try {
      throw new Error('This is an error')
    } catch (error) {
      useUi().captureAppError(error)
    }
    Copy

• closeCanvasSectionExecution:function

  • closeCanvasSectionExecution(): Promise<void>

    Close the Canvas Section Execution modal. Only takes effect for canvas_section_execution app modules

    Note that this method simply closes the modal and will result in the app calling it being unmounted from the DOM and destroyed. Make sure your app has finished updating data before you call this method.

    Returns Promise<void>

    Example

    useUi().closeCanvasSectionExecution()
    Copy

• completePostcall:function

  • completePostcall(payload: UiCompletePostcallRequest): Promise<void>

    Completes the postcall stage (with successful submission or not)

    Parameters

    • payload: UiCompletePostcallRequest

    Returns Promise<void>

    Example

    useUi().completePostcall({ was_successfully_submitted: true })
    Copy

• disablePostcallSubmit:function

  • disablePostcallSubmit(): Promise<void>

    Mark the postcall form as not possible to submit by the user. Useful while processing the form data.

    Returns Promise<void>

    Deprecated

    Example

    useUi().disablePostcallSubmit()
    Copy

• embeddableReady:function

  • embeddableReady(): Promise<void>

    This event is used for appJson.module.canvas.start_in_loading_mode: true apps. A loading curtain is displayed until you call this event.

    Returns Promise<void>

    Example

    useUi().embeddableReady()
    Copy

• enablePostcallSubmit:function

  • enablePostcallSubmit(): Promise<void>

    Mark the postcall form as possible to submit by the user.

    Returns Promise<void>

    Deprecated

    Example

    useUi().enablePostcallSubmit()
    Copy

• open:function

  • open(payload: UiOpenRequest): Promise<void>

    Open a file in the CatalogIQ instance.

    Parameters

    • payload: UiOpenRequest

    Returns Promise<void>

• openCanvasOverlay:function

  • openCanvasOverlay(
        payload: {
            component_id?: string;
            edit_mode?: boolean;
            fullscreen?: boolean;
            id: string;
            position?: {
                bottom?: string | number;
                left?: string | number;
                right?: string | number;
                top?: string | number;
            };
            section_id?: string;
        },
    ): Promise<void>

    Opens a modal to view a canvas by ID.

    onMounted(() => {
      uiApi.openCanvasOverlay({
        id: '01HH4RCBH631K4JDHWAQB0RPR6',
        edit_mode: false,
        fullscreen: true,
      })
    })
    Copy

    You can also specify a position for the canvas overlay:

    uiApi.openCanvasOverlay({
      id: '01HH4RCBH631K4JDHWAQB0RPR6',
      position: {
        top: '10px',
        left: '20px',
        right: '20px',
        bottom: '10px'
      }
    })
    Copy

    Parameters

    • payload: {
          component_id?: string;
          edit_mode?: boolean;
          fullscreen?: boolean;
          id: string;
          position?: {
              bottom?: string | number;
              left?: string | number;
              right?: string | number;
              top?: string | number;
          };
          section_id?: string;
      }

    Returns Promise<void>

• preselectSfdcMeetingId:function

  • preselectSfdcMeetingId(
        payload: UiPreselectSfdcMeetingIdRequest,
    ): Promise<UiPreselectSfdcMeetingIdResponse>

    Preselect a meeting in the top meeting bar by Salesforce Meeting ID. From there, the user can easily start the meeting with a single click.

    Parameters

    • payload: UiPreselectSfdcMeetingIdRequest

    Returns Promise<UiPreselectSfdcMeetingIdResponse>

    Example

    const objectFetchedFromSalesforce = {
      // fetch dynamically from Salesforce or provide in another way
      EventId: '00U1r00000D1J1zEAF',
    }
    ui.preselectSfdcMeetingId({ eventId: objectFetchedFromSalesforce.EventId }).then((response) => {
      // e.g. display advanced meeting details inside your app
      console.log(response.event)
    })
    Copy

• promptPia:function

  • promptPia(payload: UiPromptPiaRequest): Promise<UiPromptPiaResponse>

    Sends a query to the Pitcher Intelligent Assistant (PIA) and handles the streamed response.

    Parameters

    • payload: UiPromptPiaRequest

    Returns Promise<UiPromptPiaResponse>

    Example

    // Subscribe to PIA's streamed responses
    const cleanup = await useUi().on(
      UI_MESSAGE_TYPES.UI_PROMPT_PIA_RESPONSE_STREAMED,
      async ({ chunk, partial_response, id }) => {
        console.log(`PIA response chunk for stream ${id}: ${chunk}`);
        console.log(`PIA response so far for stream ${id}: ${partial_response}`);
      }
    );
    // Prompt PIA with a question and ensure cleanup is called afterwards
    useUi().promptPia({ prompt: "What's my most presented file?", id: 'my-prompt-id-to-discern-with-stream-event' })
      .finally(cleanup);
    Copy

• resumeMeeting:function

  • resumeMeeting(): Promise<void>

    Resumes the meeting and attempts to go at the last presented route / component.

    Returns Promise<void>

    Example

    useUi().resumeMeeting()
    Copy

• selectAgendaContent:function

  • selectAgendaContent(
        payload?: UiSelectAgendaRequest,
    ): Promise<UiSelectAgendaResponse>

    Opens the agenda selector modal to allow the user to select agenda content and handle the outcome.

    const api = useApi() // or useUi() if you know that you 're in UI context
    
    uiApi.selectAgendaContent({
     // optional payload
     initial_agenda: {
      name: 'test',
      groups: []
     }
    })
    Copy

    Parameters

    • payload: UiSelectAgendaRequest = {}

    Returns Promise<UiSelectAgendaResponse>

• selectCanvases:function

  • selectCanvases(
        payload?: UiSelectCanvasesRequest,
    ): Promise<UiSelectCanvasesResponse>

    Allows the user to select (and preselect) canvases from the instance.

    This method allows you to prompt the user to select canvases from the CatalogIQ instance and use that canvas selection in your application.

    Parameters

    • payload: UiSelectCanvasesRequest = {}

      optional payload to preselect specific canvases

    Returns Promise<UiSelectCanvasesResponse>

    Promise with the user action and selected canvases

    Example

    const api = useApi() // or useUi() if you know that you 're in UI context
    api
      .selectCanvases({
        allowed_types: ['canvas','canvas-template','section','section-template'] // default ['canvas']
        selections: [
          { id: "01HCZ623YYRFJQ0F7B69VWE510" },
          { id: "02HCZ623YYRFJQ0F7B69VWE510" },
        ], // default []
      })
    Copy

• selectCollectionContent:function

  • selectCollectionContent(
        payload?: UiSelectCollectionPlayerRequest,
    ): Promise<UiSelectCollectionPlayerResponse>

    Opens the collection player selector modal to allow the user to select collection player content and handle the outcome.

    const api = useApi() // or useUi() if you know that you 're in UI context
    
    uiApi.selectCollectionContent({
     // optional payload
     initial_data: {
      name: 'test',
      groups: []
     }
    })
    Copy

    Parameters

    • payload: UiSelectCollectionPlayerRequest = {}

    Returns Promise<UiSelectCollectionPlayerResponse>

• selectContent:function

  • selectContent(
        payload?: UiSelectContentRequest,
    ): Promise<UiSelectContentResponse>

    Allows the user to select (and preselect) content from the instance.

    Opens the content selector dialog to allow the user to select content and handle the outcome. This method allows you to prompt the user to select content from the CatalogIQ instance and use that content in your application.

    Parameters

    • payload: UiSelectContentRequest = {}

      optional payload to preselect specific content

    Returns Promise<UiSelectContentResponse>

    Promise with the user action and selected content

    Example

    const api = useApi() // or useUi() if you know that you 're in UI context
    api
      .selectContent({
        selections: [
          { fileId: "01HCZ623YYRFJQ0F7B69VWE510", type: "file" },
          {
            fileId: "01HD3XGZ5FN90QJGK7CH8TBZDF",
            type: "page",
            pageIndex: 2,
          },
        ],
      })
    Copy

• setPostcallStyle:function

  • setPostcallStyle(payload: UiSetPostcallStyleRequest): Promise<void>

    Change the height of the postcall form.

    Parameters

    • payload: UiSetPostcallStyleRequest

    Returns Promise<void>

    Example

    useUi().setPostcallStyle({ height: 100 })
    Copy

• stopMeeting:function

  • stopMeeting(): Promise<void>

    Ends current meeting and shows postcall form.

    Returns Promise<void>

    Example

    useUi().stopMeeting()
    Copy

• toast:function

  • toast(payload: UiToastRequest): Promise<void>

    Show a toast message to the user.

    Parameters

    • payload: UiToastRequest

    Returns Promise<void>

    Example

    useUi().toast({ type: 'info', message: 'Hello, world!' })
    Copy

• updateCanvas:function

  • updateCanvas(payload: UiUpdateCanvasRequest): Promise<CanvasRetrieve>

    Modify the currently loaded canvas. On the web it sends an update_canvas request to the server.

    Parameters

    • payload: UiUpdateCanvasRequest

      parts of the canvas object to update with fields to return

    Returns Promise<CanvasRetrieve>

• updateLocation:function

  • updateLocation(payload: UpdateLocationPitcherEvent): Promise<any>

    Navigate to another page in the CatalogIQ instance.

    Parameters

    • payload: UpdateLocationPitcherEvent

    Returns Promise<any>

    Example

    const canvasId = '1234567890abcdef12345678' // obtain target canvasId
    useUi().updateLocation({
      action: 'restore',
      routes: {
        'slotty-ui': {
          path: '/canvases/saved-canvases/' + canvasId + '/build/present',
          query: {},
        },
      },
    })
    Copy