1.15.6Main Tera-Fy Client (class singleton) to be used in a frontend browser
Various settings to configure behaviour
Type: Object
(String)
: Unique session signature for this instance of TeraFy, used to sign server messages, if falsy
getEntropicString(16)
is used to populate
(Boolean)
: Operate in Dev-Mode - i.e. force outer refresh when encountering an existing TeraFy instance + be more tolerent of weird iframe origins
(Number)
: Verbosity level, the higher the more chatty TeraFY will be. Set to zero to disable all
debug()
call output
(("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
(String)
: Method to use when all method detection fails
(Object<Object<Function>>)
: Functions to run when switching to specific modes, these are typically used to augment config. Called as
(config:Object)
(Number)
: How long entities have in 'detect' mode to identify themselves
(String)
: The TERA URL to connect to
(String)
: URL to restrict communications to
(Number)
: Interval in milliseconds when sanning for a handshake
(Number)
: Interval in milliseconds for when to give up trying to handshake
Event emitter subscription endpoint
Type: Mitt
DOMElements for this TeraFy instance
Type: Object
(DOMElement)
: The main tera-fy div wrapper
(DOMElement)
: The internal iFrame element (if
settings.mode == 'child'
)
(DOMElement)
: The corresponding stylesheet
Accept an incoming message
(MessageEvent)
Raw message event to process
Promise:
A promise which will resolve when the message has been processed
Listening postboxes, these correspond to outgoing message IDs that expect a response
Create + transmit a new project state patch base on the current and previous states The transmitted patch follows the JSPatch standard This function accepts an entire projectState instance, computes the delta and transmits that to the server for merging
(Object)
The local projectState to accept
(Object)
The previous projectState to examine against
Promise:
A promise which will resolve when the operation has completed
Client function which accepts a patch from the server and applies it to local project state The patch should follow the JSPatch standard This function is expected to be sub-classed by a plugin
(Array)
A JSPatch patch to apply
Promise:
A promise which will resolve when the operation has completed
Keep trying to handshake until the target responds
(Object?)
Additional options to mutate behaviour
(Number?)
: Interval in milliseconds when sanning for a handshake, defaults to global setting
(Number?)
: Interval in milliseconds for when to give up trying to handshake, defaults to global setting
Promise:
A promise which will either resolve when the handshake is successful OR fail with 'TIMEOUT'
Inject all server methods defined in methods as local functions wrapped in the rpc function
Debugging output function
This function will only act if settings.devMode is truthy
(...any?)
Output to show
(("INFO" | "LOG" | "WARN" | "ERROR")
= 'LOG')
Logging method to use
(Number
= 1)
The verbosity level to trigger at. If
settings.verbosity
is lower than this, the message is ignored
Set or merge settings
This function also routes 'special' keys like devMode to their internal handlers
(any)
The value to set if
key
is a string
TeraFy:
This chainable terafy instance
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
(("toggle" | "proxy" | Boolean)
= 'toggle')
Optional boolean to force dev mode or specify other behaviour
TeraFy:
This chainable terafy instance
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()
(any)
Promise:
A promise which will resolve if the there is a user and they are logged in
Data structure for a file filter
(Boolean?)
: Restrict to library files only
(String?)
: CSV of @momsfriendlydevco/match expressions to filter the filename by (filenames are the basename sans extension)
(String?)
: CSV of @momsfriendlydevco/match expressions to filter the basename by
(String?)
: CSV of @momsfriendlydevco/match expressions to filter the file extension by
Project entry within TERA
A project file fetched from TERA
Restore an entity created with serialize
ProjectFile:
A ProjectFile instance setup against the deserializzed data
Relative name path (can contain prefix directories) for the human readable file name
Type: String
Full path to the file This is also used as the unique identifier within the project
Type: String
Fully qualified URL to view / access / download the file from TERA This will usually open an edit UI within the TERA site
Type: String
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
An object representing meta file parts of a file name
Type: Object
A human readable, formatted version of "modified"
Type: String
A human readable, formatted version of "accessed"
Type: String
Overwrite the contents of a file with new content
Promise:
A promise which resolves when the operation has completed
Compress a file state down into a serializable entity By default this computes a Structured Clone which can be stringified
Object:
A Structured Clone compatible representation of this ProjectFile instance
Ask the user to select a project from those available - if one isn't already active Note that this function will percist in asking the uesr even if they try to cancel
(Object?)
Additional options to mutate behaviour
| Name | Description |
|---|---|
options.autoSetActiveProject Boolean
(default true)
|
After selecting a project set that project as active in TERA |
options.title String
(default "Select a project to work with")
|
The title of the dialog to display |
options.noSelectTitle String
(default 'Select project')
|
Dialog title when warning the user they need to select something |
options.noSelectBody String
(default 'A project needs to be selected to continue')
|
Dialog body when warning the user they need to select something |
Promise<Project>:
The active project
Prompt the user to select a project from those available
(Object?)
Additional options to mutate behaviour
| Name | Description |
|---|---|
options.title String
(default "Select a project to work with")
|
The title of the dialog to display |
options.allowCancel Boolean
(default true)
|
Advertise cancelling the operation, the dialog can still be cancelled by closing it |
options.setActive Boolean
(default false)
|
Also set the project as active when selected |
Promise<Project>:
The active project
Return the current, full snapshot state of the active project
Promise<Object>:
The current project state snapshot
Overwrite the entire project state with a new object
You almost never want to use this function directly, see setProjectState(path, value) for a nicer wrapper
(Object)
The new state to replace the current state with
Promise:
A promise which resolves when the operation has completed
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']`
(any)
The value to set
Promise:
A promise which resolves when the operation has been dispatched to the server
Set a nested value within the project state - just like setProjectState() - but only if no value for that path exists
(any)
The value to set
(Object?)
Additional options to mutate behaviour, see setProjectState() for the full list of supported options
Promise<Boolean>:
A promise which resolves to whether any changes were made - True if defaults were applied, false otherwise
Subscribe to project state changes
This will dispatch an RPC call to the source object applyProjectStatePatchLocal() function with the patch
If the above call fails the subscriber is assumed as dead and unsubscribed from the polling list
Promise<Function>:
A promise which resolves when a subscription has been created, call the resulting function to unsubscribe
Create a new file This creates an empty file which can then be written to
(String)
The name + relative directory path component
Promise<ProjectFile>:
The eventual ProjectFile created
Fetch a project file by its name
(String)
The name + relative directory path component
((Object | String)?)
Additional options to mutate behaviour, if a string is given
options.subkey
is assumed
| Name | Description |
|---|---|
options.subkey String?
|
If specified only the extracted subkey is returned rather than the full object |
options.cache Boolean
(default true)
|
Use the existing file cache if possible, set to false to force a refresh of files from the server first |
Promise<ProjectFile>:
The eventual fetched ProjectFile (or requested subkey)
Fetch the raw contents of a file by its ID
(String?)
File ID to retrieve the contents of
(Object?)
Additioanl options to mutate behaviour
| Name | Description |
|---|---|
options.format (
(default 'blob')
|
The format to retrieve the file in |
any:
The file contents in the requested format
Fetch the files associated with a given project
(Object)
Options which mutate behaviour
| Name | Description |
|---|---|
options.autoRequire Boolean
(default true)
|
Run
requireProject()
automatically before continuing
|
options.lazy Boolean
(default true)
|
If true, use the fastest method to retrieve the file list such as the cache. If false, force a refresh each time |
options.meta Boolean
(default true)
|
Pull meta information for each file entity |
Promise<Array<ProjectFile>>:
A collection of project files for the given project
Prompt the user to select a library to operate on
(Object?)
Additional options to mutate behaviour
| Name | Description |
|---|---|
options.title String
(default "Select a file")
|
The title of the dialog to display |
options.hint (String | Array<String>)?
|
Hints to identify the file to select in array order of preference |
options.save Boolean
(default false)
|
Set to truthy if saving a new file, UI will adjust to allowing overwrite OR new file name input |
options.filters FileFilters?
|
Optional file filters |
options.allowUpload Boolean
(default true)
|
Allow uploading new files |
options.allowRefresh Boolean
(default true)
|
Allow the user to manually refresh the file list |
options.allowDownloadZip Boolean
(default true)
|
Allow the user to download a Zip of all files |
options.allowCancel Boolean
(default true)
|
Allow cancelling the operation. Will throw
'CANCEL'
as the promise rejection if acationed
|
options.autoRequire Boolean
(default true)
|
Run
requireProject()
automatically before continuing
|
options.filter FileFilters?
|
Optional file filters |
Promise<ProjectFile>:
The eventually selected file, if in save mode new files are created as stubs
Save (or overwrite) a file within a project
((String | ProjectFile)?)
ProjectFile or ID of the same to overwrite, if omitted a file is prompted for
(Object?)
Additional options to mutate behaviour
| Name | Description |
|---|---|
options.id (String | ProjectFile)?
|
Alternate method to specify the file ID to save as, if omitted one will be prompted for |
options.autoRequire Boolean
(default true)
|
Run
requireProject()
automatically before continuing
|
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
(default 'Save citation library')
|
Dialog title if
id
is unspecified and a prompt is necessary
|
options.meta Object?
|
Optional meta data to merge into the file data |
Promise:
A promise which will resolve when the write operation has completed
Fetch + convert a project file into a library of citations
(String)
File ID to read
(Object?)
Additional options to mutate behaviour
| Name | Description |
|---|---|
options.format String
(default 'json')
|
Format for the file. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object) |
options.autoRequire Boolean
(default true)
|
Run
requireProject()
automatically before continuing
|
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 |
(Promise<Array<Ref>> | Promise<any>):
A collection of references (default bevahiour) or a whatever format was requested
Prompt the user to select a library to operate on and return a array of references in a given format
(Object?)
Additional options to mutate behaviour
| Name | Description |
|---|---|
options.title String
(default "Select a citation library")
|
The title of the dialog to display |
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', 'dedisputed' |
options.allowUpload Boolean
(default true)
|
Allow uploading new files |
options.allowRefresh Boolean
(default true)
|
Allow the user to manually refresh the file list |
options.allowDownloadZip Boolean
(default true)
|
Allow the user to download a Zip of all files |
options.allowCancel Boolean
(default true)
|
Allow cancelling the operation. Will throw
'CANCEL'
as the promise rejection if acationed
|
options.autoRequire Boolean
(default true)
|
Run
requireProject()
automatically before continuing
|
options.filters FileFilters?
|
Optional file filters, defaults to citation library selection only |
(...any?)
Additional options - see
getProjectLibrary()
Promise<Array<Ref>>:
A collection of references from the selected file
Save back a citation library from some input
(String?)
File ID to save back to, if omitted a file will be prompted for
(Object?)
Additional options to mutate behaviour
| Name | Description |
|---|---|
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
(default 'json')
|
Input format used. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object) |
options.autoRequire Boolean
(default true)
|
Run
requireProject()
automatically before continuing
|
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
(default 'Save citation library')
|
Dialog title if
id
is unspecified and a prompt is necessary
|
options.overwrite Boolean
(default true)
|
Allow existing file upsert |
options.meta Object?
|
Optional meta data to merge into the file data |
Promise:
A promise which resolves when the save operation has completed
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
(Object)
The log entry to create
Promise:
A promise which resolves when the operation has completed
Set the active page title This is usually called by a tool nested within the tera-tools.com embed
Display simple text within TERA
(Object?)
Additional options to mutate behaviour
| Name | Description |
|---|---|
options.body String
(default "Alert!")
|
The body text to display |
options.isHtml Boolean
(default false)
|
If falsy the text is rendered as plain-text otherwise it will be assumed as HTML content |
options.title String
(default 'TERA')
|
The title of the alert box |
options.buttons (
(default 'ok')
|
Button set to use or falsy to disable |
Promise:
A promise which resolves when the alert has been dismissed
Present a simple ok/cancel dialog to the user
(Object?)
Additional options to mutate behaviour
| Name | Description |
|---|---|
options.body String
(default "Confirm?")
|
The body text to display |
options.isHtml Boolean
(default false)
|
If falsy the text is rendered as plain-text otherwise it will be assumed as HTML content |
options.title String
(default 'TERA')
|
The title of the confirmation box |
Promise:
A promise which resolves with
Promise.resolve('OK')
or rejects with
Promise.reject('CANCEL')
Display, update or dispose of windows for long running tasks All options are cumulative - i.e. they are merged with other options previously provided
((Object | Boolean)?)
Additional options to mutate behaviour, if boolean false
{close: true}
is assumed
| Name | Description |
|---|---|
options.title String
(default 'TERA')
|
Window title, can only be set on the initial call |
options.body String
(default '')
|
Window body text, can only be set on the initial call |
options.bodyHtml Boolean
(default false)
|
Treat body text as HTML |
options.close Boolean
(default false)
|
Close the existing dialog, if true the dialog is disposed and options reset |
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 |
Promise:
A promise which resolves when the dialog has been updated
Prompt the user for an input, responding with a Promisable value
(Object?)
Additional options to mutate behaviour
| Name | Description |
|---|---|
options.body String?
|
Optional additional body text |
options.value String?
|
Current or default value to display pre-filled |
options.title String
(default 'Input required')
|
The dialog title to display |
options.bodyHtml Boolean
(default false)
|
If truthy, treat the body as HTML |
options.placeholder String?
|
Optional placeholder text |
options.required Boolean
(default true)
|
Treat nullish or empty inputs as a cancel operation |
Promise<any>:
Either the eventual user value or a throw with
Promise.reject('CANCEL')
Display HTML content full-screen within TERA This function is ideally called within a requestFocus() wrapper
((DOMElement | String | false))
Either a prepared DOM element or string to compile, set to falsy to remove existing content
Open a popup window containing a new site
(String)
The URL to open
(Object?)
Additional options to mutate behaviour
| Name | Description |
|---|---|
options.width Number
(default 500)
|
The desired width of the window |
options.height Number
(default 600)
|
The desired height of the window |
options.center Boolean
(default true)
|
Attempt to center the window on the screen |
options.permissions Object?
|
Additional permissions to set on opening, defaults to a suitable set of permission for popups (see code) |
WindowProxy:
The opened window object (if
noopener
is not set in permissions)
Trigger a fatal error, killing the outer TERA site
(String?)
Text to display