Skip to content

Documents ​

File upload and management: select, analyse, upload, list, download and delete files.

Quick start ​

ts
// Documents is available as Portal.documents

API reference ​

documents ​

A Documents client: select, analyse, upload, list, download and delete files.

analyseFiles() ​

Omit input to analyse the internally tracked pending selection.

ts
const documentsFileAnalysis = await documents.analyseFiles(input);

Parameters

NameTypeRequiredDescription
inputFileList | File[] | DataTransferItemListNoOmit 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.

ts
documents.clearAllSessions();

clearSelectedFiles() ​

Clear the entire pending selection, hide the analysis panel, and re-render chips.

ts
documents.clearSelectedFiles();

collectFiles() ​

Expands a file list, drop or folder into a flat list of files.

ts
const files = await documents.collectFiles(input);

Parameters

NameTypeRequiredDescription
inputFileList | File[] | DataTransferItemListYes—

Returns

Resolves with File[].

configure() ​

Changes the upload rules; returns the client for chaining.

ts
const result = documents.configure(opts);

Parameters

NameTypeRequiredDescription
optsPortalDocumentsConfigYesUpload rules for a Documents client.

Returns

Returns this.

deleteDocument() ​

Deletes a document.

ts
await documents.deleteDocument(referenceNum);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.

Returns

Resolves when the call has completed.

downloadDocument() ​

Starts a browser download of a document.

ts
documents.downloadDocument(referenceNum);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.

fetchBlob() ​

Fetches a document's bytes (to preview it yourself).

ts
const result = await documents.fetchBlob(referenceNum);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.

Returns

Resolves with Blob.

getPendingSessions() ​

Uploads that were interrupted and can be resumed.

ts
const result = documents.getPendingSessions();

Returns

Returns unknown[].

getSelectedFiles() ​

Return a snapshot of the internally tracked pending file selection.

ts
const files = documents.getSelectedFiles();

Returns

Returns File[].

listDocuments() ​

Lists documents, paged, optionally of one category.

ts
const result = await documents.listDocuments(opts);

Parameters

NameTypeRequiredDescription
optsobjectNoOptional settings.
opts.categorystringNo—
opts.pagenumberNoThe page number, starting at 1.
opts.per_pagenumberNo—

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
documentsPortalDocumentRecord[]YesThe documents.
totalnumberYesThe total count.
pagenumberYesThe page number, starting at 1.
last_pagenumberYes—

log() ​

Writes a line to the configured log element (ui.logId).

ts
documents.log(msg, type);

Parameters

NameTypeRequiredDescription
msgstringYes—
typestringNoThe kind. One of info, success, warn, error, dim.

removeSelectedFile() ​

Remove a file from the pending selection by index and re-render chips.

ts
documents.removeSelectedFile(index);

Parameters

NameTypeRequiredDescription
indexnumberYes—

setAuthToken() ​

Sets the bearer token.

ts
const result = documents.setAuthToken(token);

Parameters

NameTypeRequiredDescription
tokenstringYesA token issued by the server (see the description above).

Returns

Returns this.

setMemberRef() ​

Sets the member whose documents are used.

ts
const result = documents.setMemberRef(ref);

Parameters

NameTypeRequiredDescription
refstringYesA reference.

Returns

Returns this.

uploadFiles() ​

Omit input to upload the internally tracked pending selection.

ts
const documentRecords = await documents.uploadFiles(input, onProgress);

Parameters

NameTypeRequiredDescription
inputFileList | File[] | DataTransferItemListNoOmit input to upload the internally tracked pending selection.
onProgress(evt: PortalDocumentsUploadEvent) => voidNoEverything 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 change
  • documents:analysis-complete — { analysis } — after analyseFiles()
  • documents:upload-complete — { succeeded, failed, documents } — on batch done
new ​
ts
const client = new window.Portal.documents.Client(opts);

Parameters

NameTypeRequiredDescription
optsPortalDocumentsClientOptionsNoConstructor 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").

ts
const value = window.Portal.documents.Client.formatBytes(bytes);

Parameters

NameTypeRequiredDescription
bytesnumberYesA size in bytes.

Returns

Returns a string.

formatDate() ​

Format an ISO date string into a localised date + short time string.

ts
const value = window.Portal.documents.Client.formatDate(iso);

Parameters

NameTypeRequiredDescription
isostringYesAn ISO date string.

Returns

Returns a string.

truncate() ​

Truncate a string to max characters, appending … if shortened.

ts
const value = window.Portal.documents.Client.truncate(str, max);

Parameters

NameTypeRequiredDescription
strstringYesThe text.
maxnumberYesTruncate 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.

NameTypeRequiredDescription
idnumberYesRecord id.
member_reference_numstringYesThe member that owns it.
reference_numstringYesThe document's reference; pass to downloadDocument() / deleteDocument().
original_namestringYesThe file's name as uploaded.
stored_namestringYesThe name it is stored under.
file_pathstringYesThe storage path.
categorystringYesThe category it is filed under.
mime_typestring | nullYesThe file type.
file_sizenumberYesSize in bytes.
descriptionstring | nullYesAn optional description.
created_atstringYesISO creation time.
updated_atstringYesISO update time.

PortalDocumentsAnalysedFile ​

One file that passed analysis.

NameTypeRequiredDescription
fileFileYesThe file.
relative_pathstringYesPath within a dropped folder (or the file name).
size_bytesnumberYesSize in bytes.
mime_typestringYesThe file type.

PortalDocumentsClientOptions ​

Constructor options of new Portal.documents.Client(). Includes every PortalDocumentsConfig rule.

Extends PortalDocumentsConfig.

NameTypeRequiredDescription
baseUrlstringNoOverride the API base URL.
memberRefstringNoThe member the documents belong to.
authTokenstringNoA bearer token, when not signed in with a session.
uiPortalDocumentsUIOptionsNoUI element IDs that the API will bind and manage automatically.
isDevbooleanNoOptional flag to enable sandbox API

PortalDocumentsConfig ​

Upload rules for a Documents client.

NameTypeRequiredDescription
save_staticbooleanNoStore the file as a public static file instead of a private document.
size_limit_mbnumberNoLargest file allowed, in megabytes.
multiplebooleanNoAllow choosing several files.
allow_directorybooleanNoAllow choosing a whole folder (and keep its structure).
allowed_typesstring[]NoAllowed file types (extensions or MIME types). Empty/absent = any.
categoryPortalDocumentCategoryNoWhere the uploaded documents are filed.

PortalDocumentsFileAnalysis ​

The result of analyseFiles(): what would be uploaded and what was rejected.

NameTypeRequiredDescription
total_filesnumberYesHow many files were examined.
total_bytesnumberYesTheir total size in bytes.
total_size_labelstringYestotal_bytes as text, for example '1.5 MB'.
valid_filesPortalDocumentsAnalysedFile[]YesFiles that can be uploaded.
invalid_filesPortalDocumentsInvalidFile[]YesFiles that were rejected.
all_validbooleanYesTrue when no file was rejected.

PortalDocumentsInvalidFile ​

One file that failed analysis.

NameTypeRequiredDescription
namestringYesThe file name.
reasonstringYesWhy it was rejected (too large, type not allowed...).

PortalDocumentsUIOptions ​

The element ids a Documents client wires up for you. Every one is optional.

NameTypeRequiredDescription
dropZoneIdstringNoID 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.
fileInputIdstringNoID of a hidden <input type="file"> — the API binds change and applies multiple / webkitdirectory attributes from config.
selectedFilesListIdstringNoID 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.
analyseBtnIdstringNoID 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.
uploadBtnIdstringNoID 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.
clearFilesBtnIdstringNoID of a "Clear" button — the API binds click and calls clearSelectedFiles().
analysisPanelIdstringNoID of an element where analysis results are rendered after analyseFiles().
logIdstringNoID of a log container — the API appends timestamped log rows for upload lifecycle events. Call api.log() to write your own entries.
clearLogBtnIdstringNoID of a "Clear log" button — the API binds click and clears the log element.
progressIdstringNoID 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.

NameTypeRequiredDescription
type'batch_done'YesThe kind.
succeedednumberYesHow many succeeded.
failednumberYesHow many failed.
documentsPortalDocumentRecord[]YesThe documents.

PortalDocumentsUploadCompleteEvent ​

One file finished uploading.

NameTypeRequiredDescription
type'complete'YesThe kind.
documentPortalDocumentRecord | nullYes—
filenamestringYesThe file name.

PortalDocumentsUploadErrorEvent ​

One file failed.

NameTypeRequiredDescription
type'error'YesThe kind.
filenamestringYesThe file name.
errorstringYesThe reason, when it failed.

PortalDocumentsUploadEvent ​

Everything the onProgress callback of uploadFiles() can receive; switch on type.

One of:

PortalDocumentsUploadProgressEvent ​

Upload progress of one file.

NameTypeRequiredDescription
type'progress'YesAlways progress.
filenamestringYesThe file being uploaded.
loadednumberYesBytes sent so far.
totalnumberYesBytes in the file.
percentnumberYesThis file's progress, 0-100.
files_donenumberYesFiles finished in the batch.
files_totalnumberYesFiles in the batch.
overall_percentnumberYesThe batch's progress, 0-100.