JavaScript API

Included in the "Web" folder of the ExpeDat distribution package is a JavaScript library and sample HTML for automating the creation and execution of expedat:// URLs.

EXP.js	JavaScript library implementing the functions described below.
EXP.html	Simple HTML example showing how `EXP.js` can be used.

The functions below can be used to create and activate an "expedat://" URL, allowing JavaScript developers to dynamically create ExpeDat links and trigger actions. These functions only construct URLs, they do not interpret them. See the expedat:// URLs chapter for information about meaning and function.

EXP_IsURL()

This function simply tests whether the given string starts with "expedat://".

function EXP_IsURL( string /* The string to test */ )

Returns true if the string matches, false if it does not. No other validation is performed.

EXP_MakeURL()

An expedat:// URL string is created and returned based on the given parameters.

function EXP_MakeURL( server, /* DNS or IP, and port, of ExpeDat server [REQUIRED] */ path, /* Path to the targeted ExpeDat file or folder */ username, /* Username, null for anonymous, blank to prompt */ password, /* Password, null for anonymous, blank to prompt */ encrypt, /* True if content must be encrypted, null to omit */ compress, /* True of content should be compressed, null to omit */ handler, /* Server Object Handler, null to omit */ action, /* Action to perform: g, f, s, n, x, r */ limitui /* True if URL data should not be copied to the UI */ )

On success, a valid expedat:// URL is returned. Use EXP_IsURL() to test this. On failure, a string describing the error is returned.

server	The DNS name or IP address of the ExpeDat server, followed by a colon and the server's UDP port number (e.g. "`example.com:8080`").
path	The path to the targeted file or folder on the ExpeDat server.
username	If non-`null`, a "u=" key will be included with this value. Use an empty string `""` to prompt the user, or `null` to omit the "`u=`" key entirely.
password	If non-`null`, a "p=" key will be included with this value.
encrypt	If non-`null` and non-empty, an "e=" key will be included with this value. A non-zero numerical value will force encryption for this transaction. Any other value, or `null`, will use the encryption state currently set in the client.
compress	If non-`null` and non-empty, a "c=" key will be included with this value. A non-zero numerical value will enable compression for this transaction. A zero value will disable compression for this transaction. `null`, will use the compression state currently set in the client.
handler	If non-`null`, an "h=" key will be included with this value. When non-empty, the server will be requested to use the specified Object Handler to process this request. If the request appears to be a listing of a remote folder and the specified handler exists in the `ExpeDat Desktop` Handlers menu, then that handler will be selected for future requests. Otherwise the Handlers menu will not be changed by this action.
action	If non-`null`, an "a=" key will be included with this value. Must be one of g, f, s, n, d, or r. `null` will omit the '`a=`' key which is currently equivalent to a value of '`g`'.
limitui	If non-null and non-empty, a "l=" key will be included with this value.

Only the server parameter is required to have a value. All other parameters may be null.

Due their variable nature, Return URLs and Multiple Targets are not directly supported by this function. Instead, use EXP_MakeURL() to create the base URL, then append "r=", "s=", or "t=" keys as needed.

EXP_DoURL()

This function executes the given expedat:// URL by setting this.location. It calls EXP_IsURL() but performs no other validation. Note that the browser will not inform us of whether the URL itself was successful. All further user interaction is handled by the web browser and ExpeDat client.

function EXP_DoURL( url /* The URL to activate */ )

Returns null if the string was passed to this.location, or an error message if EXP_IsURL() returned false.

EXP_DoAction()

Combines EXP_MakeURL() and EXP_DoURL() to execute an ExpeDat action based on the given parameters.

function EXP_DoAction( server, /* DNS or IP of ExpeDat server [REQUIRED] */ path, /* Path to the targeted ExpeDat file or folder */ username, /* Username, null for anonymous, blank to prompt */ password, /* Password, null for anonymous, blank to prompt */ encrypt, /* True if content must be encrypted */ compress, /* True of content should be compressed */ handler, /* Server Object Handler, null to omit */ action, /* Action to perform: g, f, s, n, x, r */ limitui /* True if URL data should not be copied to the UI */ )

See EXP_MakeURL() for parameter descriptions. See EXP_DoURL() for return description.

EXP_FormAction()

Given a form DOM object, this function extracts the EXP_MakeURL() parameters to construct and optionally activate an expedat:// URL. It may be used in a form "onsubmit" event attribute or a similar form validation function. The EXP.html example file illustrates the use of this interface.

/* exp_server DNS or IP, and port, of ExpeDat server [REQUIRED] ** exp_path Path prefix. A '/' will be appended ** exp_anonymous Ignore username and password ** exp_username Username text, if present but blank ExpeDat Desktop will prompt ** exp_password Password text, if present but blank ExpeDat Desktop will prompt ** exp_encrypt Encrypt value or a checkbox ** exp_compress Compress value or a checkbox ** exp_handler Server Object Handler text, if present ** exp_action One of g, f, s, n, x, r ** exp_urlonly If present and true, the URL will not be activated ** exp_limitui Non-zero if URL data should not be copied to the UI */ function EXP_FormAction( thisform, /* The form object containing the above parameters */ urlid, /* Optional id to receive the URL as .innerText */ errid /* Optional id to receive error message as .innerText */ )

The parameters for this function consist of DOM objects.

thisform	The HTML form containing inputs for each parameter of EXP_MakeURL(). The name of each input should start with "`exp_`" followed by the name of the corresponding parameter. For example, "`exp_server`". One additional parameter, "`exp_urlonly`" may be provided. If this is present and `true`, then the URL will be constructed but not activated.
urlid	The id of a `.innerText` object which will receive the constructed `expedat://` URL. May be `null`.
errid	The id of a `.innerText` object which will receive an error message, if one is generated. If `null`, errors will be sent to `console.debug`.

The form inputs may be text fields, selection menus, or checkboxes. Other input types which place their value in the ".value" field will work as well.

On success, the generated URL will be copied to urlid.innerText (if urlid is valid), and errid.innerText will be set to the empty string (if errid is valid).

If an error occurs, urlid.innerText will be set to the empty string (if urlid is valid), and an error message will be written to errid.innerText (if errid is valid) or console.debug (if errid is null).

This function always returns false. An "onsubmit" form event attribute must return false to prevent the browser from trying to submit the form via HTTP.

Below is an example of a simple FORM declaration. See EXP.html for a functional example.