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_FormParse()

Extract exp_ values from the given form DOM object and return them in a mutable object suitable for input to EXP_MakeURLObj().

function EXP_FormParse( thisform /* The form object containing the exp_ parameters */ )

The following form elements are supported.  See EXP_MakeURLObj() detailed semantics.

exp_server	The DNS name or IP address of the ExpeDat server.
exp_path	The remote path to target on the ExpeDat server.
exp_anonymous	If present and non-zero, exp_username and exp_password will be ignored.
exp_username	Username for authentication.
exp_password	Password for authentication
exp_encrypt	Encryption enabled value or checkbox.
exp_compress	Compression enabled value or checkbox.
exp_handler	Server object handler
exp_action	The type of transaction to perform.
exp_limitui	True if ExpeDat Desktop should not copy URL data to its UI.
exp_targets	Multitarget parameters
exp_filter	File selection filter
exp_options	ExpeDat transaction options.

Additional exp_ elements may be supported in the future.

EXP_MakeURLObj()

Converts a JSON object structure into an expedat:// URL.

function EXP_MakeURLObj( args /* Values for the URL */ )

The output of EXP_FormParse is suitable as an input.  The following fields are supported.  Unsupported fields are quietly ignored.  Support for new fields may be added in the future.

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.
prompt	If non-null and non-empty, a "b=" key will be included with this value.  Non-zero forces ExpeDat Desktop to prompt for a download location before a Get operation.
mkdirs	If non-null and non-empty, an "m=" key will be included with this value.  Non-zero instructs the server to create missing parent directories during a Send operation.
targets	If non-null and non-empty, an "t=" key will be included with this value.  This allows you to specify multiple targets for a Get or Send operation.
returnurl	If non-null and non-empty, an "r=" key will be included with this URL.  ExpeDat Desktop will invoke this Return URL upon completion of the operation.
statusurl	If non-null and non-empty, an "s=" key will be included with this URL.  Upon completion of the operation, ExpeDat Desktop will invoke this Return URL, with target status information appended.

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

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_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.

<FORM onsubmit="return EXP_Get_Form(this,'exp_url','exp_error');" action="">