Documents
File upload and management: select, analyse, upload, list, download and delete files.
Quick start
// Documents is available as Portal.documentsAPI reference
documents
A Documents client: select, analyse, upload, list, download and delete files.
analyseFiles()
Omit input to analyse the internally tracked pending selection.
const documentsFileAnalysis = await documents.analyseFiles(input);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
input | FileList | File[] | DataTransferItemList | No | Omit input to analyse the internally tracked pending selection. |
Returns
Resolves with a PortalDocumentsFileAnalysis: The result of analyseFiles(): what would be uploaded and what was rejected.
clearAllSessions()
Forgets all interrupted uploads.
documents.clearAllSessions();clearSelectedFiles()
Clear the entire pending selection, hide the analysis panel, and re-render chips.
documents.clearSelectedFiles();collectFiles()
Expands a file list, drop or folder into a flat list of files.
const files = await documents.collectFiles(input);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
input | FileList | File[] | DataTransferItemList | Yes | — |
Returns
Resolves with File[].
configure()
Changes the upload rules; returns the client for chaining.
const result = documents.configure(opts);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
opts | PortalDocumentsConfig | Yes | Upload rules for a Documents client. |
Returns
Returns this.
deleteDocument()
Deletes a document.
await documents.deleteDocument(referenceNum);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
Returns
Resolves when the call has completed.
downloadDocument()
Starts a browser download of a document.
documents.downloadDocument(referenceNum);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
fetchBlob()
Fetches a document's bytes (to preview it yourself).
const result = await documents.fetchBlob(referenceNum);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
Returns
Resolves with Blob.
getPendingSessions()
Uploads that were interrupted and can be resumed.
const result = documents.getPendingSessions();Returns
Returns unknown[].
getSelectedFiles()
Return a snapshot of the internally tracked pending file selection.
const files = documents.getSelectedFiles();Returns
Returns File[].
listDocuments()
Lists documents, paged, optionally of one category.
const result = await documents.listDocuments(opts);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
opts | object | No | Optional settings. |
opts.category | string | No | — |
opts.page | number | No | The page number, starting at 1. |
opts.per_page | number | No | — |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
documents | PortalDocumentRecord[] | Yes | The documents. |
total | number | Yes | The total count. |
page | number | Yes | The page number, starting at 1. |
last_page | number | Yes | — |
log()
Writes a line to the configured log element (ui.logId).
documents.log(msg, type);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
msg | string | Yes | — |
type | string | No | The kind. One of info, success, warn, error, dim. |
removeSelectedFile()
Remove a file from the pending selection by index and re-render chips.
documents.removeSelectedFile(index);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
index | number | Yes | — |
setAuthToken()
Sets the bearer token.
const result = documents.setAuthToken(token);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
token | string | Yes | A token issued by the server (see the description above). |
Returns
Returns this.
setMemberRef()
Sets the member whose documents are used.
const result = documents.setMemberRef(ref);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
ref | string | Yes | A reference. |
Returns
Returns this.
uploadFiles()
Omit input to upload the internally tracked pending selection.
const documentRecords = await documents.uploadFiles(input, onProgress);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
input | FileList | File[] | DataTransferItemList | No | Omit input to upload the internally tracked pending selection. |
onProgress | (evt: PortalDocumentsUploadEvent) => void | No | Everything the onProgress callback of uploadFiles() can receive; switch on type. |
Returns
Resolves with an array of PortalDocumentRecord.
window.Portal.documents
Portal.documents — file upload and management.
Client
Construct a Documents API client.
All PortalDocumentsConfig options can be passed directly to the constructor. Pass a ui object with element IDs to let the API wire up the drop zone, file input, chip list, action buttons, log, and progress bar automatically.
DOM events dispatched on document:
documents:selection-changed—{ count, files }— on every selection changedocuments:analysis-complete—{ analysis }— afteranalyseFiles()documents:upload-complete—{ succeeded, failed, documents }— on batch done
new
const client = new window.Portal.documents.Client(opts);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
opts | PortalDocumentsClientOptions | No | Constructor options of new Portal.documents.Client(). |
Returns
Returns a PortalDocumentsClientInstance: A Documents client: select, analyse, upload, list, download and delete files.
formatBytes()
Format a byte count into a human-readable string (e.g. "1.5 MB").
const value = window.Portal.documents.Client.formatBytes(bytes);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
bytes | number | Yes | A size in bytes. |
Returns
Returns a string.
formatDate()
Format an ISO date string into a localised date + short time string.
const value = window.Portal.documents.Client.formatDate(iso);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
iso | string | Yes | An ISO date string. |
Returns
Returns a string.
truncate()
Truncate a string to max characters, appending … if shortened.
const value = window.Portal.documents.Client.truncate(str, max);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
str | string | Yes | The text. |
max | number | Yes | Truncate a string to max characters, appending … if shortened. |
Returns
Returns a string.
Types
PortalDocumentCategory
The folder/purpose a document belongs to. Known values are listed; any string is accepted.
One of:
'documents''dashboard''settings''support''financials''assistant''listings''commerce''subscriber''subscribers_catalog''forms''direct_payments''feedback''appointments''events''sponsorships'string
PortalDocumentRecord
A stored document.
| Name | Type | Required | Description |
|---|---|---|---|
id | number | Yes | Record id. |
member_reference_num | string | Yes | The member that owns it. |
reference_num | string | Yes | The document's reference; pass to downloadDocument() / deleteDocument(). |
original_name | string | Yes | The file's name as uploaded. |
stored_name | string | Yes | The name it is stored under. |
file_path | string | Yes | The storage path. |
category | string | Yes | The category it is filed under. |
mime_type | string | null | Yes | The file type. |
file_size | number | Yes | Size in bytes. |
description | string | null | Yes | An optional description. |
created_at | string | Yes | ISO creation time. |
updated_at | string | Yes | ISO update time. |
PortalDocumentsAnalysedFile
One file that passed analysis.
| Name | Type | Required | Description |
|---|---|---|---|
file | File | Yes | The file. |
relative_path | string | Yes | Path within a dropped folder (or the file name). |
size_bytes | number | Yes | Size in bytes. |
mime_type | string | Yes | The file type. |
PortalDocumentsClientOptions
Constructor options of new Portal.documents.Client(). Includes every PortalDocumentsConfig rule.
Extends PortalDocumentsConfig.
| Name | Type | Required | Description |
|---|---|---|---|
baseUrl | string | No | Override the API base URL. |
memberRef | string | No | The member the documents belong to. |
authToken | string | No | A bearer token, when not signed in with a session. |
ui | PortalDocumentsUIOptions | No | UI element IDs that the API will bind and manage automatically. |
isDev | boolean | No | Optional flag to enable sandbox API |
PortalDocumentsConfig
Upload rules for a Documents client.
| Name | Type | Required | Description |
|---|---|---|---|
save_static | boolean | No | Store the file as a public static file instead of a private document. |
size_limit_mb | number | No | Largest file allowed, in megabytes. |
multiple | boolean | No | Allow choosing several files. |
allow_directory | boolean | No | Allow choosing a whole folder (and keep its structure). |
allowed_types | string[] | No | Allowed file types (extensions or MIME types). Empty/absent = any. |
category | PortalDocumentCategory | No | Where the uploaded documents are filed. |
PortalDocumentsFileAnalysis
The result of analyseFiles(): what would be uploaded and what was rejected.
| Name | Type | Required | Description |
|---|---|---|---|
total_files | number | Yes | How many files were examined. |
total_bytes | number | Yes | Their total size in bytes. |
total_size_label | string | Yes | total_bytes as text, for example '1.5 MB'. |
valid_files | PortalDocumentsAnalysedFile[] | Yes | Files that can be uploaded. |
invalid_files | PortalDocumentsInvalidFile[] | Yes | Files that were rejected. |
all_valid | boolean | Yes | True when no file was rejected. |
PortalDocumentsInvalidFile
One file that failed analysis.
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The file name. |
reason | string | Yes | Why it was rejected (too large, type not allowed...). |
PortalDocumentsUIOptions
The element ids a Documents client wires up for you. Every one is optional.
| Name | Type | Required | Description |
|---|---|---|---|
dropZoneId | string | No | ID of a drop-zone element — the API wires up drag-and-drop automatically. If fileInputId is also set, clicking the zone opens the file picker. |
fileInputId | string | No | ID of a hidden <input type="file"> — the API binds change and applies multiple / webkitdirectory attributes from config. |
selectedFilesListId | string | No | ID of a container element where selected-file chips are rendered. Chips include a remove (×) button managed by the API. A documents:selection-changed event fires on document on every change. |
analyseBtnId | string | No | ID of an "Analyse" button. The API binds the click, calls analyseFiles(), renders into analysisPanelId (if set), and dispatches documents:analysis-complete on document. Auto-disabled when empty. |
uploadBtnId | string | No | ID of an "Upload" button. The API binds the click, calls uploadFiles(), manages disabled state, and dispatches documents:upload-complete on document when the batch finishes. Auto-disabled when empty. |
clearFilesBtnId | string | No | ID of a "Clear" button — the API binds click and calls clearSelectedFiles(). |
analysisPanelId | string | No | ID of an element where analysis results are rendered after analyseFiles(). |
logId | string | No | ID of a log container — the API appends timestamped log rows for upload lifecycle events. Call api.log() to write your own entries. |
clearLogBtnId | string | No | ID of a "Clear log" button — the API binds click and clears the log element. |
progressId | string | No | ID of a progress container — the API auto-shows the element and updates .progress-bar-fill, .progress-pct, .progress-label, .status-bar descendants automatically. |
PortalDocumentsUploadBatchDoneEvent
The whole batch finished.
| Name | Type | Required | Description |
|---|---|---|---|
type | 'batch_done' | Yes | The kind. |
succeeded | number | Yes | How many succeeded. |
failed | number | Yes | How many failed. |
documents | PortalDocumentRecord[] | Yes | The documents. |
PortalDocumentsUploadCompleteEvent
One file finished uploading.
| Name | Type | Required | Description |
|---|---|---|---|
type | 'complete' | Yes | The kind. |
document | PortalDocumentRecord | null | Yes | — |
filename | string | Yes | The file name. |
PortalDocumentsUploadErrorEvent
One file failed.
| Name | Type | Required | Description |
|---|---|---|---|
type | 'error' | Yes | The kind. |
filename | string | Yes | The file name. |
error | string | Yes | The reason, when it failed. |
PortalDocumentsUploadEvent
Everything the onProgress callback of uploadFiles() can receive; switch on type.
One of:
- PortalDocumentsUploadProgressEvent
- PortalDocumentsUploadCompleteEvent
- PortalDocumentsUploadErrorEvent
- PortalDocumentsUploadBatchDoneEvent
PortalDocumentsUploadProgressEvent
Upload progress of one file.
| Name | Type | Required | Description |
|---|---|---|---|
type | 'progress' | Yes | Always progress. |
filename | string | Yes | The file being uploaded. |
loaded | number | Yes | Bytes sent so far. |
total | number | Yes | Bytes in the file. |
percent | number | Yes | This file's progress, 0-100. |
files_done | number | Yes | Files finished in the batch. |
files_total | number | Yes | Files in the batch. |
overall_percent | number | Yes | The batch's progress, 0-100. |