api.md

June 24, 2026 ยท View on GitHub

Table of Contents

ProjectFile

A project file fetched from TERA

id

The TERA compatible unique ID of the file NOTE: This is computed each time from the Base64 of the file path

Type: String

sbId

The raw Supabase UUID of the file

Type: String

name

Relative name path (can contain prefix directories) for the human readable file name

Type: String

icon

CSS class to use as the file icon

Type: String

path

Full path to the file This is also used as the unique identifier within the project

Type: String

url

Fully qualified URL to view / access / download the file from TERA This will usually open an edit UI within the TERA site

Type: String

teraUrl

Rewrite of the URL where the absolute URL has been removed in place of a relative path, assuming the owner project is active This is used to direct to the edit/view/download UI when the files project is active and is usually used in place of URL for TERA related operations

Type: String

parsedName

An object representing meta file parts of a file name

Type: Object

Properties

  • basename String The filename + extension (i.e. everything without directory name)
  • filename String The file portion of the name (basename without the extension)
  • ext String The extension portion of the name (always lower case)
  • dirName String The directory path portion of the name

created

A date representing when the file was created

Type: Date

createdFormatted

A human readable, formatted version of "created"

Type: String

modified

A date representing when the file was modifed

Type: Date

modifiedFormatted

A human readable, formatted version of "modified"

Type: String

accessed

A date representing when the file was last accessed

Type: Date

accessedFormatted

A human readable, formatted version of "accessed"

Type: String

size

Size, in bytes, of the file

Type: Number

sizeFormatted

A human readable, formatted version of the file size

Type: String

mime

The associated mime type for the file

Type: String

meta

Additional meta information for the file

Type: Object

isFolder

Whether this is a folder or not

Type: Boolean

files

If it is a folder, it will have an array of files in the folder

Type: Array<ProjectFile>

getContents

  • See: getProjectFile()

Fetch the raw file contents as a Blob

Parameters

  • options Object? Additional options to mutate behaviour

Returns Promise<Blob> The eventual raw file contents as a Blob

setContents

  • See: setProjectFileContents()

Overwrite the contents of a file with new content

Parameters

Returns Promise<void> A promise which resolves when the operation has completed

getRefs

  • See: getProjectLibrary()

Fetch the file contents as an array of Reflib refs

Returns Promise<Array> An eventual array of RefLib references

setRefs

  • See: setProjectLibrary()

Overwrite the contents of a file with a new collection of Reflib refs

Parameters

  • refs Array Collection of references for the selected library

Returns Promise<void> A promise which resolves when the operation has completed

serialize

Compress a file state down into a serializable entity By default this computes a Structured Clone which can be stringified

Returns Object A Structured Clone compatible representation of this ProjectFile instance

deserialize

Restore an entity created with serialize NOTE: This requires the 'tera' instance to be manually added to the 'data' object before calling deserialize, as it's not included in the serialized output.

Parameters

  • data Object An input object created via ProjectFiles.serialize() (MUST include a 'tera' property added manually)

Returns ProjectFile A ProjectFile instance setup against the deserialized data

TeraFy

Main Tera-Fy Client (class singleton) to be used in a frontend browser

settings

Various settings to configure behaviour

Type: Object

Properties

  • session String Unique session signature for this instance of TeraFy, used to sign server messages, if falsy getEntropicString(16) is used to populate
  • devMode Boolean Operate in Dev-Mode - i.e. force outer refresh when encountering an existing TeraFy instance + be more tolerant of weird iframe origins
  • verbosity Number Verbosity level, the higher the more chatty TeraFY will be. Set to zero to disable all debug() call output
  • mode ("detect" | "parent" | "child" | "popup") How to communicate with TERA. 'parent' assumes that the parent of the current document is TERA, 'child' spawns an iFrame and uses TERA there, 'detect' tries parent and switches to modeFallback if communication fails
  • modeFallback String Method to use when all method detection fails
  • modeOverrides Object<Object<Function>> Functions to run when switching to specific modes, these are typically used to augment config. Called as (config:Object)
  • modeTimeout Number How long entities have in 'detect' mode to identify themselves
  • siteUrl String The TERA URL to connect to
  • restrictOrigin String URL to restrict communications to
  • List Array<String> of sandbox allowables for the embedded if in embed mode
  • handshakeInterval Number Interval in milliseconds when scanning for a handshake
  • handshakeTimeout Number Interval in milliseconds for when to give up trying to handshake
  • debugPaths Array<(String | Array<String>)>? List of paths (in either dotted or array notation) to enter debugging mode if a change is detected in dev mode e.g. {debugPaths: ['foo.bar.baz']}. This really slows down state writes so should only be used for debugging

events

Event emitter subscription endpoint

Type: Mitt

dom

DOMElements for this TeraFy instance

Type: Object

Properties

  • el DOMElement The main tera-fy div wrapper
  • iframe DOMElement The internal iFrame element (if settings.mode == 'child')
  • popup Window The popup window context (if settings.mode == 'popup')
  • stylesheet DOMElement The corresponding stylesheet

methods

List of function stubs mapped from the server to here This array is forms the reference of TeraFy.METHOD() objects to provide locally which will be mapped via TeraFy.rpc(METHOD, ...args)

Type: Array<String>

plugins

Loaded plugins via Use()

Type: Array<TeraFyPlugin>

namespaces

Active namespaces we are subscribed to Each key is the namespace name with the value as the local reactive \ observer \ object equivalent The key string is always of the form ${ENTITY}::${ID} e.g. projects:1234

Type: Object

send

Send a message + wait for a response object

Parameters

  • message Object Message object to send

Returns Promise<any> A promise which resolves when the operation has completed with the remote reply

sendRaw

Send raw message content to the server This function does not return or wait for a reply - use send() for that

Parameters

  • message Object Message object to send

rpc

Call an RPC function in the server instance

Parameters

  • method String The method name to call
  • args ...any? Optional arguments to pass to the function

Returns Promise<any> The resolved output of the server function

acceptMessage

Accept an incoming message

Parameters

Returns Promise A promise which will resolve when the message has been processed

acceptPostboxes

Listening postboxes, these correspond to outgoing message IDs that expect a response

init

Initialize the TERA client singleton This function can only be called once and will return the existing init() worker Promise if its called against

Parameters

  • options Object? Additional options to merge into settings via set

Returns Promise<TeraFy> An eventual promise which will resolve with this terafy instance

detectMode

Populate settings.mode Try to communicate with a parent frame, if none assume we need to fallback to child mode

Returns Promise<String> A promise which will resolve with the detected mode to use

injectComms

Find an existing active TERA server OR initialize one

Returns Promise A promise which will resolve when the loading has completed and we have found a parent TERA instance or initialized a child

handshakeLoop

Keep trying to handshake until the target responds

Parameters

  • options Object? Additional options to mutate behaviour

Properties

  • handshakeInterval Number? Interval in milliseconds when scanning for a handshake, defaults to global setting
  • handshakeTimeout Number? Interval in milliseconds for when to give up trying to handshake, defaults to global setting

Returns Promise A promise which will either resolve when the handshake is successful OR fail with 'TIMEOUT'

injectStylesheet

Inject a local stylesheet to handle TERA server functionality

Returns Promise A promise which will resolve when the loading has completed and we have found a parent TERA instance or initialized a child

injectMethods

Inject all server methods defined in methods as local functions wrapped in the rpc function

Returns Promise A promise which resolves when the operation has completed

debug

Debugging output function This function will only act if settings.devMode is truthy

Parameters

  • msg ...any? Output to show
  • method ("INFO" | "LOG" | "WARN" | "ERROR") Logging method to use (optional, default 'LOG')
  • verboseLevel Number The verbosity level to trigger at. If settings.verbosity is lower than this, the message is ignored (optional, default 1)

set

Set or merge settings This function also routes 'special' keys like devMode to their internal handlers

Parameters

  • key (String | Object) Either a single setting key to set or an object to merge

  • value any The value to set if key is a string

  • options Object? Additional options to mutate behaviour

    • options.ignoreNullish Boolean If falsy, this forces the setting of undefined or null values rather than ignoring them when specifying values by string (optional, default true)

Returns TeraFy This chainable terafy instance

setIfDev

  • See: set()

Set or merge settings - but only in dev mode and only if the value is not undefined

Parameters

  • key (String | Object) Either a single setting key to set or an object to merge
  • value any The value to set if key is a string
  • options Object? Additional options to mutate behaviour

Returns TeraFy This chainable terafy instance

use

Include a TeraFy client plugin

Parameters

  • source (Function | Object | String) Either the JS module class, singleton object or URL to fetch it from. Eventually constructed as invoked as (teraClient:TeraFy, options:Object)
  • options Object? Additional options to mutate behaviour during construction (pass options to init() to initialize later options)

Returns TeraFy This chainable terafy instance

mixin

Internal function used by use() to merge an external declared singleton against this object

Parameters

  • target Object Installed class instance to extend
  • source Object Initialized source object to extend from

toggleDevMode

Set or toggle devMode This function also accepts meta values:

'toggle' - Set dev mode to whatever the opposing value of the current mode
'proxy'  - Optimize for using a loopback proxy

Parameters

  • devModeEnabled ("toggle" | "proxy" | Boolean) Optional boolean to force dev mode or specify other behaviour (optional, default 'toggle')

Returns TeraFy This chainable terafy instance

toggleFocus

Fit the nested TERA server to a full-screen This is usually because the server component wants to perform some user activity like calling $prompt

Parameters

  • isFocused (String | Boolean) Whether to fullscreen the embedded component (optional, default 'toggle')

getEntropicString

Generate random entropic character string in Base64

Parameters

  • maxLength Number Maximum length of the generated string (optional, default 32)

Returns String

selectProjectFile

Require a user login to TERA If there is no user OR they are not logged in a prompt is shown to go and do so This is an pre-requisite step for requireProject()

Parameters

  • options

Returns Promise A promise which will resolve if the there is a user and they are logged in

mountNamespace

Make a namespace available locally This generally creates whatever framework flavoured reactive/observer/object is supported locally - generally with writes automatically synced with the master state

Parameters

  • name String The alias of the namespace, this should be alphanumeric + hyphens + underscores

Returns Promise<Reactive> A promise which resolves to the reactive object

Actual namespace mounting function designed to be overridden by plugins

Parameters

  • name String The alias of the namespace, this should be alphanumeric + hyphens + underscores

Returns Promise A promise which resolves when the mount operation has completed

unmountNamespace

Release a locally mounted namespace This function will remove the namespace from namespaces, cleaning up any memory / subscription hooks

Parameters

  • name String The name of the namespace to unmount

Returns Promise A promise which resolves when the operation has completed

Actual namespace unmounting function designed to be overridden by plugins

Parameters

  • name String The name of the namespace to unmount

Returns Promise A promise which resolves when the operation has completed

handshake

Return basic server information as a form of validation

Properties

  • date Date Server date

Returns Promise<Object> Basic promise result

setServerVerbosity

RPC callback to set the server verbosity level

Parameters

  • verbosity Number The desired server verbosity level

User

User / active session within TERA

Properties

  • id String Unique identifier of the user
  • email String The email address of the current user
  • name String The provided full name of the user
  • isSubscribed Boolean Whether the active user has a TERA subscription

getUser

Fetch the current session user

Returns Promise<User> The current logged in user or null if none

getCredentials

Provide an object of credentials for 3rd party services like Firebase/Supabase

Returns Object An object containing 3rd party service credentials

requireUser

Require a user login to TERA If there is no user OR they are not logged in a prompt is shown to go and do so This is an pre-requisite step for requireProject()

Parameters

  • options Object? Additional options to mutate behaviour

    • options.forceRetry Boolean Forcibly try to refresh the user state (optional, default false)

Returns Promise<User> The current logged in user or null if none

Project

Project entry within TERA

getProject

Get the currently active project, if any

Returns Promise<(Project | null)> The currently active project, if any

getProjects

Get a list of projects the current session user has access to

Returns Promise<Array<Project>> Collection of projects the user has access to

setActiveProject

Set the currently active project within TERA

Parameters

  • project (Object | String) The project to set as active - either the full Project object or its ID

requireProject

Ask the user to select a project from those available - if one isn't already active Note that this function will persist in asking the user even if they try to cancel

Parameters

  • options Object? Additional options to mutate behaviour

    • options.autoSetActiveProject Boolean After selecting a project set that project as active in TERA (optional, default true)
    • options.title String The title of the dialog to display (optional, default "Select a project to work with")
    • options.noSelectTitle String Dialog title when warning the user they need to select something (optional, default 'Select project')
    • options.noSelectBody String Dialog body when warning the user they need to select something (optional, default 'A project needs to be selected to continue')

Returns Promise<Project> The active project

selectProject

Prompt the user to select a project from those available

Parameters

  • options Object? Additional options to mutate behaviour

    • options.title String The title of the dialog to display (optional, default "Select a project to work with")
    • options.allowCancel Boolean Advertise cancelling the operation, the dialog can still be cancelled by closing it (optional, default true)
    • options.setActive Boolean Also set the project as active when selected (optional, default false)

Returns Promise<Project> The active project

getNamespace

Get a one-off snapshot of a namespace without mounting it This can be used for simpler apps which don't have their own reactive / observer equivalent

Parameters

  • name String The alias of the namespace, this should be alphanumeric + hyphens + underscores

Returns Promise<Object> A promise which resolves to the namespace POJO state

setNamespace

Set (or merge by default) a one-off snapshot over an existing namespace This can be used for simpler apps which don't have their own reactive / observer equivalent and just want to quickly set something

Parameters

  • name String The name of the namespace

  • state Object The state to merge

  • options Object? Additional options to mutate behaviour

    • options.method ("merge" | "set") How to handle the state. 'merge' (merge a partial state over the existing namespace state), 'set' (completely overwrite the existing namespace) (optional, default 'merge')

Returns Promise<Object> A promise which resolves to the namespace POJO state

listNamespaces

Return a list of namespaces available to the current project

Properties

  • name String The name of the namespace

Returns Promise<Array<Object>> Collection of available namespaces for the current project

getProjectState

Return the current, full snapshot state of the active project

Parameters

  • options Object? Additional options to mutate behaviour

    • options.autoRequire Boolean Run requireProject() automatically before continuing (optional, default true)

  • Paths Array<String> to subscribe to e.g. ['/users/'],

Returns Promise<Object> The current project state snapshot

setProjectState

Set a nested value within the project state Paths can be any valid Lodash.set() value such as:

- Dotted notation - e.g. `foo.bar.1.baz`
- Array path segments e.g. `['foo', 'bar', 1, 'baz']`

Parameters

  • path (String | Array<String>) The sub-path within the project state to set

  • value any The value to set

  • options Object? Additional options to mutate behaviour

    • options.save Boolean Save the changes to the server immediately, disable to queue up multiple writes (optional, default true)

Returns Promise A promise which resolves when the operation has been dispatched to the server

setProjectStateDefaults

  • See: setProjectState()

Set a nested value within the project state - just like setProjectState() - but only if no value for that path exists

Parameters

  • path (String | Array<String>) The sub-path within the project state to set
  • value any The value to set
  • options Object? Additional options to mutate behaviour, see setProjectState() for the full list of supported options

Returns Promise<Boolean> A promise which resolves to whether any changes were made - True if defaults were applied, false otherwise

setProjectStateRefresh

Force refetching the remote project state into local This is only ever needed when saving large quantities of data that need to be immediately available

Returns Promise A promise which resolves when the operation has completed

FileFilters

Data structure for a file filter

Properties

  • library Boolean? Restrict to library files only
  • filename String? CSV of @momsfriendlydevco/match expressions to filter the filename by (filenames are the basename sans extension)
  • basename String? CSV of @momsfriendlydevco/match expressions to filter the basename by
  • ext String? CSV of @momsfriendlydevco/match expressions to filter the file extension by

selectProjectFile

Prompt the user to select a library to operate on

Parameters

  • options Object? Additional options to mutate behaviour

    • options.title String The title of the dialog to display (optional, default "Select a file")
    • options.hint (String | Array<String>)? Hints to identify the file to select in array order of preference
    • options.save Boolean Set to truthy if saving a new file, UI will adjust to allowing overwrite OR new file name input (optional, default false)
    • options.saveFilename String? File name to save as, if omitted the hinting system is used otherwise 'My File.unknown' is assumed
    • options.filters FileFilters? Optional file filters
    • options.allowUpload Boolean Allow uploading new files (optional, default true)
    • options.allowRefresh Boolean Allow the user to manually refresh the file list (optional, default true)
    • options.allowDownloadZip Boolean Allow the user to download a Zip of all files (optional, default true)
    • options.allowCancel Boolean Allow cancelling the operation. Will throw 'CANCEL' as the promise rejection if actioned (optional, default true)
    • options.autoRequire Boolean Run requireProject() automatically before continuing (optional, default true)
    • options.showHiddenFiles Boolean Whether hidden data.json files should be shown (optional, default false)

Returns Promise<ProjectFile> The eventually selected file, if in save mode new files are created as stubs

getProjectFiles

Fetch the files associated with a given project

Parameters

  • options Object Options which mutate behaviour

    • options.autoRequire Boolean Run requireProject() automatically before continuing (optional, default true)
    • options.lazy Boolean If true, use the fastest method to retrieve the file list such as the cache. If false, force a refresh each time (optional, default true)
    • options.meta Boolean Pull meta information for each file entity (optional, default true)

Returns Promise<Array<ProjectFile>> A collection of project files for the given project

getProjectFileContents

Fetch the raw contents of a file by its ID

Parameters

  • id String? File ID to retrieve the contents of

  • options Object? Additional options to mutate behaviour

    • options.format ("blob" | "json") The format to retrieve the file in (optional, default 'blob')

Returns any The file contents in the requested format

getProjectFile

Fetch a project file by its name

Parameters

  • name String The file name (or path if inside a directory)

  • options (Object | String)? Additional options to mutate behaviour, if a string is given options.subkey is assumed

    • options.subkey String? If specified only the extracted subkey is returned rather than the full object
    • options.cache Boolean Use the existing file cache if possible, set to false to force a refresh of files from the server first (optional, default true)

Returns Promise<ProjectFile> The eventual fetched ProjectFile (or requested subkey)

createProjectFile

Create a new file This creates an empty file which can then be written to

Parameters

  • name String The name + relative directory path component

Returns Promise<ProjectFile> The eventual ProjectFile created

moveProjectFile

Moves a project file to a new name/path. The file's unique ID (UUID) remains the same, but its 'name' (relative path) and associated properties will be updated.

Parameters

  • sourceId String The unique ID (UUID) of the file to move.

  • newName String The new relative name for the file (e.g., "documents/report-final.pdf" or "image.png"). This path is relative to the project's root file directory.

  • options Object? Additional options to mutate behaviour.

    • options.autoRequire Boolean Run requireProject() automatically before continuing. (optional, default true)
    • options.overwrite Boolean If true (default), moving a file to a newName that already exists will overwrite the existing file. This aligns with the default behavior of the underlying Supabase storage move operation. If set to false, the function would ideally check and prevent overwrite, but current implementation relies on underlying storage behavior. (optional, default true)

Returns Promise<(ProjectFile | null)> A promise which resolves to the updated ProjectFile object for the moved file if found after the operation, or null if the file could not be located post-move (e.g., if its ID changed unexpectedly or it was deleted).

deleteProjectFile

Remove a project file by its ID

Parameters

  • id String The File ID to remove

Returns Promise A promise which resolves when the operation has completed

setProjectFileContents

Save (or overwrite) a file within a project

Parameters

  • id (String | ProjectFile)? ProjectFile or ID of the same to overwrite, if omitted a file is prompted for

  • contents (File | Blob | FormData | Object | Array) The new file contents

  • options Object? Additional options to mutate behaviour

    • options.id (String | ProjectFile)? Alternate method to specify the file ID to save as, if omitted one will be prompted for
    • options.autoRequire Boolean Run requireProject() automatically before continuing (optional, default true)
    • options.hint (String | Array<String>)? Hint(s) to store against the library. Generally corresponds to the current operation being performed - e.g. 'deduped'
    • options.filename String? Suggested filename if id is unspecified
    • options.title String Dialog title if id is unspecified and a prompt is necessary (optional, default 'Save citation library')
    • options.meta Object? Optional meta data to merge into the file data

Returns Promise A promise which will resolve when the write operation has completed

createProjectFolder

Creates a new "folder" within the project's file storage. Folders in Supabase storage are typically represented by creating a placeholder file (e.g., .emptyFolderPlaceholder) within the desired path. This operation is idempotent: if the folder (via its placeholder) already exists, it will not error.

Parameters

  • folderPath String The relative path of the folder to create (e.g., "myDocuments/reports").

  • options Object? Additional options.

    • options.autoRequire Boolean Automatically run requireProject() to ensure an active project context. (optional, default true)
  • Throws Error If no project is active (and autoRequire is false), or if folderPath is invalid, or if the creation fails.

Returns Promise<void> A promise that resolves when the folder is created or ensured.

deleteProjectFolder

Deletes a "folder" and all its contents from the project's file storage. This involves listing all files under the given folder path (prefix) and removing them.

Parameters

  • folderPath String The relative path of the folder to delete (e.g., "myDocuments/reports").

  • options Object? Additional options.

    • options.autoRequire Boolean Automatically run requireProject() to ensure an active project context. (optional, default true)
  • Throws Error If no project is active (and autoRequire is false), or if folderPath is invalid, or if deletion fails.

Returns Promise<null> A promise that resolves with null when the folder and its contents are deleted.

selectProjectLibrary

Prompt the user to select a library to operate on and return a array of references in a given format

Parameters

  • options Object? Additional options to mutate behaviour

    • options.title String The title of the dialog to display (optional, default "Select a citation library")
    • options.hint (String | Array<String>)? Hints to identify the library to select in array order of preference. Generally corresponds to the previous stage - e.g. 'deduped', 'review1', 'review2', 'demisted'
    • options.allowUpload Boolean Allow uploading new files (optional, default true)
    • options.allowRefresh Boolean Allow the user to manually refresh the file list (optional, default true)
    • options.allowDownloadZip Boolean Allow the user to download a Zip of all files (optional, default true)
    • options.allowCancel Boolean Allow cancelling the operation. Will throw 'CANCEL' as the promise rejection if actioned (optional, default true)
    • options.autoRequire Boolean Run requireProject() automatically before continuing (optional, default true)
    • options.filters FileFilters? Optional file filters, defaults to citation library selection only

  • options ...any? Additional options - see getProjectLibrary()

Returns Promise<Array<Ref>> A collection of references from the selected file

getProjectLibrary

Fetch + convert a project file into a library of citations

Parameters

  • id String File ID to read

  • options Object? Additional options to mutate behaviour

    • options.format String Format for the file. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object) (optional, default 'json')
    • options.autoRequire Boolean Run requireProject() automatically before continuing (optional, default true)
    • options.filter Function? Optional async file filter, called each time as (File:ProjectFile)
    • options.find Function? Optional async final stage file filter to reduce all candidates down to one subject file

Returns (Promise<Array<Ref>> | Promise<any>) A collection of references (default behaviour) or a whatever format was requested

setProjectLibrary

Save back a citation library from some input

Parameters

  • id String? File ID to save back to, if omitted a file will be prompted for

  • refs (Array<RefLibRef> | Blob | File)? Collection of references for the selected library or the raw Blob/File

  • options Object? Additional options to mutate behaviour

    • options.id String? Alternate method to specify the file ID to save as, if omitted one will be prompted for
    • options.refs (Array<RefLibRef> | Blob | File)? Alternate method to specify the refs to save as an array or raw Blob/File
    • options.format String Input format used. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object) (optional, default 'json')
    • options.autoRequire Boolean Run requireProject() automatically before continuing (optional, default true)
    • options.hint String? Hint to store against the library. Generally corresponds to the current operation being performed - e.g. 'deduped'
    • options.filename String? Suggested filename if id is unspecified
    • options.title String Dialog title if id is unspecified and a prompt is necessary (optional, default 'Save citation library')
    • options.overwrite Boolean Allow existing file upsert (optional, default true)
    • options.meta Object? Optional meta data to merge into the file data

Returns Promise A promise which resolves when the save operation has completed

projectLog

Create a log entry for the currently active project

The required log object can be of various forms. See https://tera-tools.com/api/logs.json for the full list

Parameters

  • log Object The log entry to create

Returns Promise A promise which resolves when the operation has completed

setPage

Set the active page title This is usually called by a tool nested within the tera-tools.com embed

Parameters

  • options (Object | String) Context information about the page, if this is a string, its assumed to populate url

    • options.path String? The URL path segment to restore on next refresh
    • options.title String? The page title associated with the path

uiAlert

Display simple text within TERA

Parameters

  • text String? Text to display, if specified this populates options.body

  • options Object? Additional options to mutate behaviour

    • options.body String The body text to display (optional, default "Alert!")
    • options.isHtml Boolean If falsy the text is rendered as plain-text otherwise it will be assumed as HTML content (optional, default false)
    • options.title String The title of the alert box (optional, default 'TERA')
    • options.buttons ("ok" | false) Button set to use or falsy to disable (optional, default 'ok')

Returns Promise A promise which resolves when the alert has been dismissed

uiConfirm

Present a simple ok/cancel dialog to the user

Parameters

  • text String? Text to display, if specified this populates options.body

  • options Object? Additional options to mutate behaviour

    • options.body String The body text to display (optional, default "Confirm?")
    • options.isHtml Boolean If falsy the text is rendered as plain-text otherwise it will be assumed as HTML content (optional, default false)
    • options.title String The title of the confirmation box (optional, default 'TERA')

Returns Promise A promise which resolves with Promise.resolve('OK') or rejects with Promise.reject('CANCEL')

uiJson

Present some JSON to the user

Parameters

  • data (String | Object) Data to display

  • options Object? Additional options to mutate behaviour

    • options.body String The body text to display above the JSON (optional, default "")
    • options.isHtml Boolean If falsy the text is rendered as plain-text otherwise it will be assumed as HTML content (optional, default false)
    • options.json (String | Object)? The JSON data to display
    • options.title String The title of the confirmation box (optional, default 'TERA')

Returns Promise A promise which resolves with Promise.resolve('OK')

uiPanic

Trigger a fatal error, killing the outer TERA site

Parameters

  • text String? Text to display

uiProgress

Display, update or dispose of windows for long running tasks All options are cumulative - i.e. they are merged with other options previously provided

Parameters

  • options (Object | Boolean)? Additional options to mutate behaviour, if boolean false {close: true} is assumed

    • options.title String Window title, can only be set on the initial call (optional, default 'TERA')
    • options.backdrop String Set to 'static' to prevent user being able to click outside the modal to close (optional, default true)
    • options.body String Window body text, can only be set on the initial call (optional, default '')
    • options.bodyHtml Boolean Treat body text as HTML (optional, default false)
    • options.close Boolean Close the existing dialog, if true the dialog is disposed and options reset (optional, default false)
    • options.text String? The text of the task being conducted
    • options.progress Number? The current progress of the task being conducted, this is assumed to be a value less than maxProgress
    • options.maxProgress Number? The maximum value that the progress can be

Returns Promise A promise which resolves when the dialog has been updated

uiPrompt

Prompt the user for an input, responding with a Promisable value

Parameters

  • text String? Text to display, if specified this populates options.body

  • options Object? Additional options to mutate behaviour

    • options.body String? Optional additional body text
    • options.isHtml Boolean If truthy, treat the body as HTML (optional, default false)
    • options.value String? Current or default value to display pre-filled
    • options.title String The dialog title to display (optional, default 'Input required')
    • options.placeholder String? Optional placeholder text
    • options.required Boolean Treat nullish or empty inputs as a cancel operation (optional, default true)

Returns Promise<any> Either the eventual user value or a throw with Promise.reject('CANCEL')

uiThrow

Catch an error using the TERA error handler

Parameters

  • error (Error | Object | String) Error to handle, generally an Error object but can be a POJO or a scalar string

Returns Void This function is fatal

uiWindow

Open a popup window containing a new site

Parameters

  • url String The URL to open

  • options Object? Additional options to mutate behaviour

    • options.width Number The desired width of the window (optional, default 500)
    • options.height Number The desired height of the window (optional, default 600)
    • options.center Boolean Attempt to center the window on the screen (optional, default true)
    • options.permissions Object? Additional permissions to set on opening, defaults to a suitable set of permission for popups (see code)

Returns WindowProxy The opened window object (if noopener is not set in permissions)

uiSplat

Display HTML content full-screen within TERA This function is ideally called within a requestFocus() wrapper

Parameters

  • content (DOMElement | String | false) Either a prepared DOM element or string to compile, set to falsy to remove existing content

  • options Object? Additional options to mutate behaviour

    • options.logo (Boolean | String) Add a logo to the output, if boolean true the Tera-tools logo is used otherwise specify a path or URL (optional, default false)