Function: useUi()

useUi(): object

API methods available in the CatalogIQ default UI.

You can store the API object in a variable and call the methods directly.

Most methods have a snake_case and camelCase version of their name available.

const uiApi = useUi()

Returns

object

UI API object with methods described below.

on()

on: <T>(type, handler) => Promise<() => void>

Subscribe to a given event type by its key.

Type Parameters

Type Parameter
T extends keyof UiMessagePayloads

Parameters

Parameter	Type	Description
type	T	The event type/key to subscribe to.
handler	(data) => Promise<void>	The handler function to call when the event is emitted.

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

const unsubscribeFromSectionListUpdate = useUi().on('ui_section_list_updated', (event: object) => {
  // handle event
})

// later
unsubscribeFromSectionListUpdate.then(unsubscribe => unsubscribe())

onAppSetData()

onAppSetData: (handler) => Promise<() => void>

Subscribe to the app set data event. It is triggered when the app data is set. This event is triggered when the app is loaded and in certain other cases after loading.

This is the main event for the canvas app to receive data from the CatalogIQ instance and know about its environment.

Parameters

Parameter	Type
handler	(data) => Promise<void>

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

let user = null
let isEditMode = null
let activeCanvas = null
let isPrintMode = false
const unsubscribePromise = useUi().onAppSetData((data) => {
  user = data?.user
  isEditMode = data?.is_edit_mode
  activeCanvas = data?.canvas
  isPrintMode = data?.display_mode === 'print' || data?.client === 'dsr'
  // ...mode logic...
})

// later
unsubscribePromise.then(unsubscribe => unsubscribe())

onAppUpdateData()

onAppUpdateData: (handler) => Promise<() => void>

Subscribe to the app update data event. It is triggered when the user changes from edit mode to view mode or vice versa and when the call is started or ended.

Parameters

Parameter	Type
handler	(data) => Promise<void>

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

let inCall = false
let isEditMode = false
const unsubscribePromise = useUi().onAppUpdateData((data) => {
  isEditMode = data?.is_edit_mode
  inCall = data?.in_call
  // ...mode logic...
})

// later
unsubscribePromise.then(unsubscribe => unsubscribe())

onCanvasUpdated()

onCanvasUpdated: (handler) => Promise<() => void>

Subscribe to the canvas updated event. It is triggered when the current canvas of the app is updated.

Parameters

Parameter	Type
handler	(data) => Promise<void>

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

const unsubscribePromise = useUi().onCanvasUpdated((event: { canvas }) => {
  // handle event
})

// later
unsubscribePromise.then(unsubscribe => unsubscribe())

onMeetingCanceled()

onMeetingCanceled: (handler) => Promise<() => void>

Subscribe to the meeting canceled event.

Parameters

Parameter	Type	Description
handler	(data) => Promise<void>

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

const unsubscribeFromMeetingCanceled = useUi().onMeetingCanceled((event: {
  accountId?: string;
  eventId?: string;
}) => {
  // handle event
})

// later
unsubscribeFromMeetingCanceled.then(cancel => cancel())

onSectionListUpdated()

onSectionListUpdated: (handler) => Promise<() => void>

Subscribe to the section list updated event. It is triggered when the list of sections (products) in the current canvas is updated.

Parameters

Parameter	Type
handler	(data) => Promise<void>

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

const unsubscribePromise = useUi().onSectionListUpdated((event: { canvas }) => {
  // handle event
})

// later
unsubscribePromise.then(unsubscribe => unsubscribe())

uiBroadcast

uiBroadcast: object

appLoaded()

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>

Examples

useUi().appLoaded()

appResize()

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

Parameter	Type	Description
payload	UiAppResizeRequest	object containing requested height of the iframe as the number of pixels

Returns

Promise<void>

cancelMeeting()

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

Returns

Promise<void>

Example

useUi().cancelMeeting()

canvasNavigateNextPage()

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

Returns

Promise<void>

Example

useUi().canvasNavigateNextPage()

canvasNavigatePage()

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

Parameter	Type
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 })
  }
})

canvasNavigatePreviousPage()

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

Returns

Promise<void>

Example

useUi().canvasNavigatePreviousPage()

captureAppError()

Send an app error to Pitcher sentry instance.

Parameters

Parameter	Type	Description
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)
}

closeCanvasDrawer()

Close the Canvas Drawer modal. Only takes effect for apps running in canvas_drawer embed location

Note that this method simply closes the drawer 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().closeCanvasDrawer()

closeCanvasSectionExecution()

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()

completePostcall()

Completes the postcall stage (with successful submission or not)

Parameters

Parameter	Type
payload	UiCompletePostcallRequest

Returns

Promise<void>

Example

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

disablePostcallSubmit()

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()

embeddableReady()

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()

enablePostcallSubmit()

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

Returns

Promise<void>

Deprecated

Example

useUi().enablePostcallSubmit()

open()

Open a file in the CatalogIQ instance.

Parameters

Parameter	Type
payload	UiOpenRequest

Returns

Promise<void>

openCanvasOverlay()

Opens a modal to view a canvas by ID.

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

You can also specify a position for the canvas overlay:

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

Parameters

Parameter	Type
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; }
payload.component_id?	string
payload.edit_mode?	boolean
payload.fullscreen?	boolean
payload.id	string
payload.position?	{ bottom: string | number; left: string | number; right: string | number; top: string | number; }
payload.position.bottom?	string | number
payload.position.left?	string | number
payload.position.right?	string | number
payload.position.top?	string | number
payload.section_id?	string

Returns

Promise<void>

preselectSfdcMeetingId()

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

Parameter	Type
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)
})

printCanvas()

Trigger async print/download of a canvas with optional notification URL. Calls the downloader-test endpoint to convert the canvas to PDF.

Parameters

Parameter	Type	Description
payload	UiPrintCanvasRequest	Canvas ID and optional notify URL for async notifications

Returns

Promise<UiPrintCanvasResponse>

Promise with job ID and success status

Example

useUi().printCanvas({
  id: '01HH4RCBH631K4JDHWAQB0RPR6',
  notify_url: 'https://my-webhook.example.com/canvas-ready'
})

promptPia()

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

Parameters

Parameter	Type
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);

resumeMeeting()

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

Returns

Promise<void>

Example

useUi().resumeMeeting()

selectAgendaContent()

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: []
 }
})

Parameters

Parameter	Type
payload	UiSelectAgendaRequest

Returns

Promise<UiSelectAgendaResponse>

selectCanvases()

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

Parameter	Type	Description
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 []
  })

selectCollectionContent()

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: []
 }
})

Parameters

Parameter	Type
payload	UiSelectCollectionPlayerRequest

Returns

Promise<UiSelectCollectionPlayerResponse>

selectContent()

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

Parameter	Type	Description
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,
      },
    ],
  })

setPostcallStyle()

Change the height of the postcall form.

Parameters

Parameter	Type
payload	UiSetPostcallStyleRequest

Returns

Promise<void>

Example

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

stopMeeting()

Ends current meeting and shows postcall form.

Returns

Promise<void>

Example

useUi().stopMeeting()

toast()

Show a toast message to the user.

Parameters

Parameter	Type
payload	UiToastRequest

Returns

Promise<void>

Example

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

updateCanvas()

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

Parameters

Parameter	Type	Description
payload	UiUpdateCanvasRequest	parts of the canvas object to update with fields to return

Returns

Promise<CanvasRetrieve>

updateLocation()

Navigate to another page in the CatalogIQ instance.

Parameters

Parameter	Type
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: {},
    },
  },
})