AttachmentGridForCustomWidget

Reference

• The AttachmentGridForCustomWidget component is a wrapper around AttachmentsGrid that exposes attachment management capabilities — upload, download, delete, and bulk-delete — for use inside the custom widget framework.
• It can be used in dashboard, view, or home layouts of a custom widget.

Props

1. instanceId

   • Type: string
   • Description: ID of the instance whose attachments are displayed. Required when isCreateLayout is false.

2. instanceTypeName

   • Type: string
   • Description: Name of the instance type. Used to load allowed file types for upload validation.

3. customFields

   • Type: array
   • Default: []
   • Description: Additional column definitions to display alongside the default attachment columns.

4. addAttachmentLabel

   • Type: string
   • Default: null
   • Description: Custom label for the add attachment button. Falls back to the default label when null.

5. hideAddButton

   • Type: boolean
   • Default: false
   • Description: Hides the add attachment button when true.

6. hideDownloadAllButton

   • Type: boolean
   • Default: false
   • Description: Hides the download-all button when true.

7. hideDeleteButton

   • Type: boolean
   • Default: false
   • Description: Hides the bulk-delete header button and the per-row delete action when true.

8. hideCheckboxColumn

   • Type: boolean
   • Default: false
   • Description: Hides the row-selection checkbox column when true, regardless of bulk-delete or download configuration.

9. showCarouselButton

   • Type: boolean
   • Default: false
   • Description: Shows the image carousel button when true.

10. uploadPopupFields

    • Type: array
    • Default: []
    • Description: Additional fields to render inside the upload popup form.

11. allowedFiletypes

    • Type: array
    • Default: []
    • Description: List of allowed file extensions for upload (e.g. ['.pdf', '.png']). Overrides type-level defaults when provided.

12. fileTypesFilter

    • Type: array
    • Default: []
    • Description: List of file type names used to filter which attachments are fetched and displayed (e.g. ['Picture', 'Document']). When empty, attachments of all file types are shown.

13. defaultFileType

    • Type: string
    • Default: ''
    • Description: File type pre-selected for every file added in the upload popup (e.g. 'Document'). Takes precedence over the automatic selection that applies when only one file type is available. Users can still change the file type per file before uploading. When omitted, no default is applied.

14. isCreateLayout

    • Type: boolean
    • Default: false
    • Description: Set to true when the widget is embedded in a create/new-instance form. In this mode attachments are staged locally and no API fetch is made on mount.

15. isMultiSelect

    • Type: boolean
    • Default: true
    • Description: Controls whether more than one file can be selected in a single upload. When true (default) the file picker and drag-and-drop accept multiple files. Set to false to restrict uploads to a single file at a time — the OS file picker then allows only one file and the drop hint text switches to its singular form.

16. onUploadResult

    • Type: function
    • Description: Callback invoked after an upload attempt. Receives the upload result object.

17. instanceEditDispatch

    • Type: function
    • Description: Dispatch function from the parent instance edit context. Required when isCreateLayout is true so staged attachments are tracked in the parent form state.

18. versionId

    • Type: string
    • Description: Version ID used to scope attachment fetching to a specific instance version.

19. allowedOperations

    • Type: object
    • Description: Allowed operations object (e.g. FileUpload, Delete) that controls which actions are available in the grid.

20. leftHeaderButtonsConfig

    • Type: object
    • Description: Unified config object for header buttons. Takes full precedence over hideAddButton, hideDownloadAllButton, and showCarouselButton when provided.
    • Shape:

      {
        addAttachment: { show: true, label: 'Add File' },
        bulkDelete:    { show: true },
        download:      { show: true },
        imageCarousel: { show: false },
      }

Notes

• All extra props are spread onto AttachmentsGrid, so any undocumented prop accepted by AttachmentsGrid can be passed through.
• When isCreateLayout is true, provide instanceEditDispatch so staged files are tracked by the parent form.
• Use leftHeaderButtonsConfig when you need fine-grained control over which header buttons are visible; it supersedes the individual hide* props.
• hideDeleteButton suppresses both the bulk-delete header button and the per-row delete icon in the actions column.
• hideCheckboxColumn removes row-selection checkboxes entirely, regardless of bulk-delete or download button configuration.
• allowedFiletypes and fileTypesFilter are independent: the former restricts which file extensions can be uploaded, the latter filters which file type categories are shown in the grid.
• defaultFileType only pre-fills the file type dropdown in the upload popup; each file's type can still be changed individually before uploading.
• isMultiSelect defaults to true; set it to false only when the widget should accept a single file per upload. It affects file selection only, not how existing attachments are displayed in the grid.

Usage Example — View layout (read existing attachments)

function MyAttachmentsWidget(pageContext) {
  const { protrakComponents } = React.useContext(customWidgetContext);
  const { AttachmentGridForCustomWidget } = protrakComponents;

  return (
    <AttachmentGridForCustomWidget
      instanceId={pageContext.instanceId}
      instanceTypeName={pageContext.instanceTypeName}
    />
  );
}

Usage Example — Hide add & download buttons

function ReadOnlyAttachmentsWidget(pageContext) {
  const { protrakComponents } = React.useContext(customWidgetContext);
  const { AttachmentGridForCustomWidget } = protrakComponents;

  return (
    <AttachmentGridForCustomWidget
      instanceId={pageContext.instanceId}
      instanceTypeName={pageContext.instanceTypeName}
      hideAddButton={true}
      hideDownloadAllButton={true}
    />
  );
}

Usage Example — Read-only grid (no delete, no checkboxes)

function ReadOnlyNoSelectWidget(pageContext) {
  const { protrakComponents } = React.useContext(customWidgetContext);
  const { AttachmentGridForCustomWidget } = protrakComponents;

  return (
    <AttachmentGridForCustomWidget
      instanceId={pageContext.instanceId}
      instanceTypeName={pageContext.instanceTypeName}
      hideAddButton={true}
      hideDownloadAllButton={true}
      hideDeleteButton={true}
      hideCheckboxColumn={true}
    />
  );
}

Usage Example — Restrict allowed file types with a custom upload label

function DocumentsOnlyWidget(pageContext) {
  const { protrakComponents } = React.useContext(customWidgetContext);
  const { AttachmentGridForCustomWidget } = protrakComponents;

  return (
    <AttachmentGridForCustomWidget
      instanceId={pageContext.instanceId}
      instanceTypeName={pageContext.instanceTypeName}
      addAttachmentLabel="Add Document"
      allowedFiletypes={['.pdf', '.docx', '.xlsx']}
      onUploadResult={(result) => console.log('Upload result:', result)}
    />
  );
}

Usage Example — Show only pictures and default new uploads to the Picture file type

function PicturesWidget(pageContext) {
  const { protrakComponents } = React.useContext(customWidgetContext);
  const { AttachmentGridForCustomWidget } = protrakComponents;

  return (
    <AttachmentGridForCustomWidget
      instanceId={pageContext.instanceId}
      instanceTypeName={pageContext.instanceTypeName}
      fileTypesFilter={['Picture']}
      defaultFileType="Picture"
    />
  );
}

Usage Example — Restrict upload to a single file at a time

function SingleFileAttachmentWidget(pageContext) {
  const { protrakComponents } = React.useContext(customWidgetContext);
  const { AttachmentGridForCustomWidget } = protrakComponents;

  return (
    <AttachmentGridForCustomWidget
      instanceId={pageContext.instanceId}
      instanceTypeName={pageContext.instanceTypeName}
      isMultiSelect={false}
    />
  );
}