Function: useAdmin()

useAdmin(): object

API methods available in the CatalogIQ Admin.

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.

import { useAdmin } from '@pitcher/js-api'

const adminApi = useAdmin()

Returns

on

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

Subscribe to a given event type by its key.

Parameters

Parameter	Type	Description
type	"admin_env_changed"	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.

toast

toast: (payload) => Promise<void>

Show a toast message to the user. Compatible with the UI API version of this method.

Parameters

Parameter	Type
payload	AdminToastRequest

Returns

Promise<void>

Example

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

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	AdminCaptureAppErrorRequest	error object to send to Pitcher sentry instance

Returns

Promise<void>

Example

try {
  throw new Error('This is an error')
} catch (error) {
  useAdmin().captureAppError({
    app_name: 'my-admin-app',
    message: 'Failed to save settings',
    stack: error instanceof Error ? error.stack : String(error),
  })
}

close()

close(): Promise<void>

Closes the already open file that was opened via api or by the user.

Returns

Promise<void>

Example

adminApi.close()

createCanvas()

createCanvas(payload): Promise<CanvasRetrieve>

Creates a new canvas.

Parameters

Parameter	Type
payload	CanvasCreateRequest

Returns

Promise<CanvasRetrieve>

Example

adminApi.createCanvas({
   name: 'my new canvas';
 })

getAppConfig()

getAppConfig(payload): Promise<Record<string, any>>

Get the metadata object of an app with a given name.

Parameters

Parameter	Type	Description
payload	{ app_name: string; }	The payload object.
payload.app_name	string	name value from app.json of the app you want to get the metadata of.

Returns

Promise<Record<string, any>>

Example

useAdmin().getAppConfig({ app_name: 'my-app' })

getCanvas()

getCanvas(payload): Promise<CanvasRetrieve>

Fetches a canvas by id with the defined fields or all of them.

Parameters

Parameter	Type
payload	{ fields?: string; id: string; }
payload.fields?	string
payload.id	string

Returns

Promise<CanvasRetrieve>

Example

// The `filters` object is a reserved payload key to transfer the metadata dict over the wire.
adminApi.getCanvas({
 fields: 'id,name,metadata',
})

getCanvases()

getCanvases(payload): Promise<PaginatedData<CanvasRetrieve>>

Fetches a list of canvases to use in your app.

Parameters

Parameter	Type
payload	GetCanvasesParams & object

Returns

Promise<PaginatedData<CanvasRetrieve>>

Example

// The `filters` object is a reserved payload key to transfer the metadata dict over the wire.
adminApi.getCanvases({
  search: 'my search query',
  ordering: '-created_at',
  filters: {
    metadata__mydaterangefiltername__range: ['2023-12-10', '2023-12-22'],
    metadata__mymultiselectfiltername: ['optionAValue', 'optionCValue'],
  },
 fields: 'id,name,metadata',
})

getEnv()

getEnv(): Promise<AdminEnv>

Fetches the necessary info for the app to know where it is embedded.

Check out usePitcherApi().getEnv() for more information.

Returns

Promise<AdminEnv>

Example

adminApi.getEnv()

getFile()

getFile(payload): Promise<File>

Fetches a file by ID.

Parameters

Parameter	Type
payload	{ id: string; }
payload.id	string

Returns

Promise<File>

Example

adminApi.getFile({ id: 'my-file-id' })

getFiles()

getFiles(payload): Promise<PaginatedFileList>

Lists available files.

Parameters

Parameter	Type
payload	Record<string, any>

Returns

Promise<PaginatedFileList>

Example

adminApi.getFiles()

getInstanceMetadataTemplates()

getInstanceMetadataTemplates(payload?): Promise<PaginatedMetadataTemplateList>

Fetches a list of metadata templates to use in your app. Instance is auto-injected by admin app if in instance scope.

Parameters

Parameter	Type
payload?	GetInstanceMetadataTemplatesPayload

Returns

Promise<PaginatedMetadataTemplateList>

Example

adminApi.getInstanceMetadataTemplates()

getUsers()

getUsers(payload?): Promise<PaginatedData<User>>

Fetches a list of users from the admin API.

Parameters

Parameter	Type	Description
payload?	GetUsersParams	Optional parameters for filtering users

Returns

Promise<PaginatedData<User>>

Promise resolving to a paginated list of users

Example

const adminApi = useAdmin()
const users = await adminApi.getUsers({ page_size: 100 })

open()

open(payload): Promise<void>

Opens a file by id.

Parameters

Parameter	Type
payload	{ id: string; }
payload.id	string

Returns

Promise<void>

Example

adminApi.open({ id: 'my-file-id' })

openCanvasOverlay()

openCanvasOverlay(payload): Promise<void>

Opens a modal to view a canvas by ID.

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

You can also specify a position for the canvas overlay:

adminApi.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>

openCollectionPlayerOverlay()

openCollectionPlayerOverlay(payload): Promise<void>

Opens a modal to display collection player content.

Parameters

Parameter	Type
payload	AdminOpenCollectionPlayerOverlayRequest

Returns

Promise<void>

Example

adminApi.openCollectionPlayerOverlay({
  name: 'My Collection',
  groups: [
    {
      id: 'file-id-1',
      name: 'Group 1',
    },
    {
      id: 'group-2',
      name: 'Group 2',
      slides: [
        { file_id: 'file-id-2', slide_index: 0 },
        { file_id: 'file-id-3', slide_index: 1 },
      ],
    },
  ],
})

selectAgendaContent()

selectAgendaContent(payload?): Promise<AdminSelectAgendaResponse>

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

const api = useApi() // or useAdmin() if you know that you 're in Admin context

adminApi.selectAgendaContent({
 // optional payload
 initial_agenda: {
  name: 'test',
  groups: []
 }
})

Parameters

Parameter	Type
payload	AdminSelectAgendaRequest

Returns

Promise<AdminSelectAgendaResponse>

selectCanvases()

selectCanvases(payload?): Promise<AdminSelectCanvasesResponse>

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	AdminSelectCanvasesRequest	optional payload to preselect specific canvases

Returns

Promise<AdminSelectCanvasesResponse>

Promise with the user action and selected canvases

Example

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

selectCollectionContent()

selectCollectionContent(payload?): Promise<AdminSelectCollectionPlayerResponse>

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

const api = useApi() // or useAdmin() if you know that you 're in Admin context

adminApi.selectCollectionContent({
 // optional payload
 initial_data: {
  name: 'test',
  groups: []
 }
})

Parameters

Parameter	Type
payload	AdminSelectCollectionPlayerRequest

Returns

Promise<AdminSelectCollectionPlayerResponse>

selectContent()

selectContent(payload): Promise<AdminSelectContentResponse>

Opens a selector that allows you to select (and preselect) from your Pitcher uploaded content.

Parameters

Parameter	Type
payload	AdminSelectContentRequest

Returns

Promise<AdminSelectContentResponse>

Example

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

updateCanvas()

updateCanvas(payload): Promise<CanvasRetrieve>

Updates a canvas by ID and returns the defined fields or all of them.

Parameters

Parameter	Type
payload	PatchedCanvasUpdateRequest & object

Returns

Promise<CanvasRetrieve>

Example

// The fields param is appended to the URL as a query param.
onMounted(() => {
  adminApi.updateCanvas({
    id: '01HH4RCBH631K4JDHWAQB0RPR6',
    fields: 'id,name',
    name: 'To 3!',
  }).then((res) => {
    console.log(res)  // logs: { id: '01HH4RCBH631K4JDHWAQB0RPR6', name: 'To 3!' }
  })
})