Function useAdmin

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

const adminApi = useAdmin()
Copy

Returns {
    on: (
        type: "admin_env_changed",
        handler: (data: AdminEnv) => Promise<void>,
    ) => Promise<() => void>;
    toast: (payload: AdminToastRequest) => Promise<void>;
    captureAppError(payload: AdminCaptureAppErrorRequest): Promise<void>;
    close(): Promise<void>;
    createCanvas(payload: CanvasCreateRequest): Promise<CanvasRetrieve>;
    getAppConfig(payload: { app_name: string }): Promise<Record<string, any>>;
    getCanvas(
        payload: { fields?: string; id: string },
    ): Promise<CanvasRetrieve>;
    getCanvases(
        payload: GetCanvasesParams & {
            fields?: string;
            filters?: Record<string, any>;
        },
    ): Promise<PaginatedData<CanvasRetrieve>>;
    getEnv(): Promise<AdminEnv>;
    getFile(payload: { id: string }): Promise<File>;
    getFiles(payload: Record<string, any>): Promise<PaginatedFileList>;
    getInstanceMetadataTemplates(
        payload?: GetInstanceMetadataTemplatesPayload,
    ): Promise<PaginatedMetadataTemplateList>;
    getUsers(payload?: GetUsersParams): Promise<PaginatedData<User>>;
    open(payload: { id: string }): 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>;
    selectAgendaContent(
        payload?: AdminSelectAgendaRequest,
    ): Promise<AdminSelectAgendaResponse>;
    selectCanvases(
        payload?: AdminSelectCanvasesRequest,
    ): Promise<AdminSelectCanvasesResponse>;
    selectCollectionContent(
        payload?: AdminSelectCollectionPlayerRequest,
    ): Promise<AdminSelectCollectionPlayerResponse>;
    selectContent(
        payload: AdminSelectContentRequest,
    ): Promise<AdminSelectContentResponse>;
    updateCanvas(
        payload: PatchedCanvasUpdateRequest & {
            fields?: string;
            id: string;
            instance_id?: string;
        },
    ): Promise<CanvasRetrieve>;
}

• on: (
      type: "admin_env_changed",
      handler: (data: AdminEnv) => Promise<void>,
  ) => Promise<() => void>

• toast: (payload: AdminToastRequest) => Promise<void>

• captureAppError:function

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

    Send an app error to Pitcher sentry instance.

    Parameters

    • 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({
        error,
        message: 'This is an app error',
      })
    }
    Copy

• close:function

  • close(): Promise<void>

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

    Returns Promise<void>

    Example

    adminApi.close()
    Copy

• createCanvas:function

  • createCanvas(payload: CanvasCreateRequest): Promise<CanvasRetrieve>

    Creates a new canvas.

    Parameters

    • payload: CanvasCreateRequest

    Returns Promise<CanvasRetrieve>

    Example

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

• getAppConfig:function

  • getAppConfig(payload: { app_name: string }): Promise<Record<string, any>>

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

    Parameters

    • payload: { app_name: string }

      The payload object.

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

• getCanvas:function

  • getCanvas(payload: { fields?: string; id: string }): Promise<CanvasRetrieve>

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

    Parameters

    • payload: { fields?: string; 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',
    })
    Copy

• getCanvases:function

  • getCanvases(
        payload: GetCanvasesParams & {
            fields?: string;
            filters?: Record<string, any>;
        },
    ): Promise<PaginatedData<CanvasRetrieve>>

    Fetches a list of canvases to use in your app.

    Parameters

    • payload: GetCanvasesParams & { fields?: string; filters?: Record<string, any> }

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

• getEnv:function

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

• getFile:function

  • getFile(payload: { id: string }): Promise<File>

    Fetches a file by ID.

    Parameters

    • payload: { id: string }

    Returns Promise<File>

    Example

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

• getFiles:function

  • getFiles(payload: Record<string, any>): Promise<PaginatedFileList>

    Lists available files.

    Parameters

    • payload: Record<string, any>

    Returns Promise<PaginatedFileList>

    Example

    adminApi.getFiles()
    Copy

• getInstanceMetadataTemplates:function

  • getInstanceMetadataTemplates(
        payload?: GetInstanceMetadataTemplatesPayload,
    ): 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

    • Optionalpayload: GetInstanceMetadataTemplatesPayload

    Returns Promise<PaginatedMetadataTemplateList>

    Example

    adminApi.getInstanceMetadataTemplates()
    Copy

• getUsers:function

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

    Fetches a list of users from the admin API.

    Parameters

    • Optionalpayload: 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 })
    Copy

• open:function

  • open(payload: { id: string }): Promise<void>

    Opens a file by id.

    Parameters

    • payload: { id: string }

    Returns Promise<void>

    Example

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

• 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(() => {
      adminApi.openCanvasOverlay({
        id: '01HH4RCBH631K4JDHWAQB0RPR6',
        edit_mode: false,
        fullscreen: true,
      })
    })
    Copy

    You can also specify a position for the canvas overlay:

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

• selectAgendaContent:function

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

    Parameters

    • payload: AdminSelectAgendaRequest = {}

    Returns Promise<AdminSelectAgendaResponse>

• selectCanvases:function

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

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

• selectCollectionContent:function

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

    Parameters

    • payload: AdminSelectCollectionPlayerRequest = {}

    Returns Promise<AdminSelectCollectionPlayerResponse>

• selectContent:function

  • selectContent(
        payload: AdminSelectContentRequest,
    ): Promise<AdminSelectContentResponse>

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

    Parameters

    • 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,
          },
        ],
      })
    Copy

• updateCanvas:function

  • updateCanvas(
        payload: PatchedCanvasUpdateRequest & {
            fields?: string;
            id: string;
            instance_id?: string;
        },
    ): Promise<CanvasRetrieve>

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

    Parameters

    • payload: PatchedCanvasUpdateRequest & {
          fields?: string;
          id: string;
          instance_id?: string;
      }

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