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

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

appFullscreenChange()

appFullscreenChange(payload): Promise<void>

Tell the CatalogIQ UI that the app is showing something fullscreen, or has stopped. While the app reports is_fullscreen: true, the UI lays the app's page over its own top bar and sidebar, so content the app draws over its whole window covers the whole screen. Report is_fullscreen: false as soon as the app leaves fullscreen: the UI shows no exit of its own while covered.

For now the UI honours it only from the Canvas Renderer app (canvas-renderer) opened as a page of the UI's sidebar (ui_app module), which sends it while a collection player in its canvas is fullscreen, so that no app that misses its false can leave the rep stuck until Pitcher is relaunched. From any other app, and anywhere else such as an app embedded in a canvas, the message is ignored, as it is by a UI that predates it. It does not use the browser's Fullscreen API.

Parameters

Parameter	Type	Description
payload	UiAppFullscreenChangeRequest	object saying whether the app is now fullscreen

Returns

Promise<void>

Example

useUi().appFullscreenChange({ is_fullscreen: true })
// later, when the app leaves fullscreen
useUi().appFullscreenChange({ is_fullscreen: false })

appLoaded()

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>

Examples

useUi().appLoaded()

appResize()

appResize(payload): 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

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

Returns

Promise<void>

cancelMeeting()

cancelMeeting(): Promise<void>

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

Returns

Promise<void>

Example

useUi().cancelMeeting()

canvasNavigateNextPage()

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

canvasNavigatePage()

canvasNavigatePage(payload): 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

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

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

captureAppError()

captureAppError(payload): Promise<void>

Send an app error to Pitcher sentry instance.

Sentry files it under one issue per app + message and tags it app_name, so send your app's name as app_name (app is also read) and a stable message, and keep ids and other varying values in other fields. Without a name the error groups under unknown with every other unnamed app's. The whole payload is attached to the event.

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({
    app_name: 'my-app',
    message: 'Failed to load accounts',
    stack: error instanceof Error ? error.stack : String(error),
  })
}

closeCanvasDrawer()

closeCanvasDrawer(): Promise<void>

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

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

closeGlobalPopup()

closeGlobalPopup(): Promise<void>

Closes the currently open global popup app.

Returns

Promise<void>

Example

const api = useApi()
api.closeGlobalPopup()

completePostcall()

completePostcall(payload): Promise<void>

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

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

embeddableReady()

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

enablePostcallSubmit()

enablePostcallSubmit(): Promise<void>

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

Returns

Promise<void>

Deprecated

Example

useUi().enablePostcallSubmit()

open()

open(payload): Promise<void>

Open a file in the CatalogIQ instance.

Parameters

Parameter	Type
payload	UiOpenRequest

Returns

Promise<void>

openCanvasOverlay()

openCanvasOverlay(payload): Promise<void>

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'
  }
})

If your app just created this canvas and is opening it only so the rep can run its completion wizard, set discard_on_wizard_cancel so that cancelling the wizard deletes the empty shell instead of leaving it in the rep's pitchdecks:

const canvas = await api.createCanvas(...)
uiApi.openCanvasOverlay({ id: canvas.id, edit_mode: true, discard_on_wizard_cancel: true })

Pass it ONLY for a canvas created moments ago — never when re-opening one the rep already has.

If your app navigates the shell instead of opening an overlay (update_location to /canvases/saved-canvases/<id>/build/<mode>), the equivalent is the discard_on_wizard_cancel query param on that route: query: { discard_on_wizard_cancel: '1' }. Accepted opt-in values are '1', 'true', '' and a bare key; ANY other value is ignored and nothing is discarded, so a wrong guess no-ops rather than deleting a canvas.

Parameters

Parameter	Type	Description
payload	{ component_id?: string; discard_on_wizard_cancel?: boolean; 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.discard_on_wizard_cancel?	boolean	PIT-8622 — delete this canvas if the rep cancels its completion wizard. Opt-in, for apps that POST the canvas themselves before handing it to the shell.
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>

openCollectionPlayerOverlay()

openCollectionPlayerOverlay(payload): Promise<void>

Opens the collection player overlay to view a collection of files/slides.

This method opens the native Pitcher collection player interface with the specified files and slides. You can show entire files or specific pages from files.

Parameters

Parameter	Type	Description
payload	UiOpenCollectionPlayerOverlayRequest	Object containing groups array and collection name

Returns

Promise<void>

Example

// Open collection with full files
useUi().openCollectionPlayerOverlay({
  groups: [
    { id: 'file-123-abc', name: 'Product Overview' },
    { id: 'file-456-def', name: 'Pricing Slides' }
  ],
  name: 'Sales Deck'
})

// Open collection with specific slides/pages
useUi().openCollectionPlayerOverlay({
  groups: [
    {
      id: 'file-123-abc',
      name: 'Product Overview',
      slides: [
        { file_id: 'file-123-abc', slide_index: 0 },
        { file_id: 'file-123-abc', slide_index: 2 }
      ]
    }
  ],
  name: 'Custom Sales Presentation'
})

openGlobalPopup()

openGlobalPopup(appName, extraContext?): Promise<UiOpenGlobalPopupResponse>

Opens a global popup app by name.

Parameters

Parameter	Type	Description
appName	string	The name of the app to open (must have app_type: 'ui-global-popup')
extraContext?	Record<string, any>	Extra context to pass to the app

Returns

Promise<UiOpenGlobalPopupResponse>

Promise with the result of the operation

Example

const api = useApi()
api.openGlobalPopup('my-popup-app')
api.openGlobalPopup('my-popup-app', { customData: 'value' })

openSharingSettings()

openSharingSettings(payload): Promise<UiOpenSharingSettingsResponse>

Parameters

Parameter	Type
payload	UiOpenSharingSettingsRequest

Returns

Promise<UiOpenSharingSettingsResponse>

preselectSfdcMeetingId()

preselectSfdcMeetingId(payload): 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

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

printCanvas(payload): Promise<UiPrintCanvasResponse>

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

promptPia(payload): Promise<UiPromptPiaResponse>

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

resumeMeeting(): Promise<void>

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

Returns

Promise<void>

Example

useUi().resumeMeeting()

selectAgendaContent()

selectAgendaContent(payload?): 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: []
 }
})

Parameters

Parameter	Type
payload	UiSelectAgendaRequest

Returns

Promise<UiSelectAgendaResponse>

selectCanvases()

selectCanvases(payload?): 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

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

selectCollectionContent(payload?): 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: []
 }
})

Parameters

Parameter	Type
payload	UiSelectCollectionPlayerRequest

Returns

Promise<UiSelectCollectionPlayerResponse>

selectContent()

selectContent(payload?): 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

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

setPostcallStyle(payload): Promise<void>

Change the height of the postcall form.

Parameters

Parameter	Type
payload	UiSetPostcallStyleRequest

Returns

Promise<void>

Example

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

stopMeeting()

stopMeeting(): Promise<void>

Ends current meeting and shows postcall form.

Returns

Promise<void>

Example

useUi().stopMeeting()

toast()

toast(payload): Promise<void>

Show a toast message to the user.

Parameters

Parameter	Type
payload	UiToastRequest

Returns

Promise<void>

Example

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

updateCanvas()

updateCanvas(payload): Promise<CanvasRetrieve>

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

updateLocation(payload): Promise<any>

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