webappos.js functions

Each webAppOS app should include the webappos.js script, which ensures the existence of the window.webappos JavaScript object for calling webAppOS-related functions and services.

window.​webappos

The webappos object contains useful webAppOS-specific functions and fields.  The object is shared between all iframes loaded from the same domain; some functions and fields, however, are iframe-specific.

webappos.​interrupt

A one-argument function for managing web calls and special submitter links in web memory.  If specified, the interrupt function is called each time before a web call is being invoked or a submitter link created.  The argument can be one of the following:

{
type: "webcall",
isClient: true|false, // whether the web call is client-side or not
actionName: "[web call action name]",
argument: JSON|string|web memory object reference
}

or

{
type: "submit",
argument: [event or command object reference in web memory]
}

The function must return true, if the invocation has to be interrupted, or false otherwise (the webcall or event/command will be handled as usual by webAppOS).

web calls-related functions (iframe-specific)
webappos.​webcall_and_wait (may become deprecated)
window.webappos.webcall_and_wait = function (
action,
arg
)

Executes the given web call synchronously via the webAppOS webcalls service.

Parameters
action

the name of the action to call (defined at the server side in *.webcalls files)

arg

action argument; usually, a JSON object; sometimes - a string object; for webmemcall conventions: an integer representing the object reference

Returns

a parsed JSON object as JavaScript object; the returned object can contain the "error" attribute (containing an error message) to specify that an error occurred

webappos.​webcall (async)
window.webappos.webcall = async function (
actionName,
arg
)

Executes the given web call asynchronously via the webAppOS webcalls service.  Client-side webcalls are executed right away.

Parameters
actionName

the name of the action to call (defined at the server side in *.webcalls files)

arg

the action argument; for jsoncall conventions: a JavaScript(JSON) object or a string; for webmemcall conventions: an integer reference of a web memory argument or a webmem object itself;

Returns

a Promise, which resolves in a parsed resulting JSON of the web call (with jsoncall calling conventions) as a JavaScript object; the promise is rejected if the returned object contains the "error" attribute, or if some other error occurs

webappos.​get_client_webcall_window (async)
window.webappos.get_client_webcall_window = async function(
actionName,
arg
)

Returns the window, where the given clinet-side webcall should be executed.  This function can be redefined (e.g., by EnvironmentEngine) to support internal iframes.  The function is asynchronous since we may need to wait until the iframe/window is loaded.

Parameters
actionName

the name of the action to call (as defined at the server side in *.webcalls files)

arg

a jsoncall or webmemcall argument (can be a JS object, webmem object, or a string)

Returns

a Promise, which resolves in a DOM window object; the promise rejected if the window was not found

Desktop API
webappos.​desktop
window.webappos.desktop

Provides access to Desktop API. Either passes Desktop API calls to the parent window (if the parent provides Desktop API), or implements by its own.  In the latter case, the default implementation is tailored for single-page webAppOS applications that do not use the desktop. However, webAppOS desktop applications (like the shipped default Desktop app) should redefine functions from Desktop API marked as [DESKTOP-SPECIFIC].

webappos.​desktop
webappos.desktop.get_width

Provides access to Desktop API. Either passes Desktop API calls to the parent window (if the parent provides Desktop API), or implements by its own.  In the latter case, the default implementation is tailored for single-page webAppOS applications that do not use the desktop. However, webAppOS desktop applications (like the shipped default Desktop app) should redefine functions from Desktop API marked as [DESKTOP-SPECIFIC].

webappos.​desktop.​launch_in_desktop [DESKTOP-SPECIFIC]
webappos.desktop.launch_in_desktop = function (
url,
app_url_name
)

Asks the desktop to open the given URL as desktop window associated with the given app.

The default (non-desktop) implementation just opens the given URL in a new tab.

Parameters
url

the URL to open in a desktop window (the URL usually starts with "/apps/<app-url-name>")

app_url_name

the lowest-case name of the webAppOS app used within the URL; the desktop can visualize that this app is active (e.g., by adding the icon to the taskbar/dock); the desktop can store the last coordinates and dimensions of the last open app window for restoring them when the same app is being opened again;

app_url_name can be null; in this case, the desktop should not visualize any app (the page at the passed URL will be displayed like system window);

Returns

nothing (possible async execution)

webappos.​desktop.​open_path
webappos.desktop.open_path = function (
path,
full_screen
)

Opens the given path by launching the corresponding webAppOS app and passing the path as argument.  For webAppOS project_ids launches the corresponding associated app.  For directories and unidentified apps, launches FileBrowser app.

Parameters
path

the path (project_id or folder path) to open; the path must be in format "login/path/relative/to/user's/home"

full_screen

a boolean flag denoting whether to open in a new tab, not inside the desktop app; default (non-desktop) implementation always assumes full_screen (new tab) mode; if the desktop is present, relies on webappos.desktop.launch_in_desktop

Returns

nothing (possible async execution)

webappos.​desktop.​launch_app
webappos.desktop.launch_app = function (
app_url_name,
full_screen
)

Launches the given webAppOS app.

Parameters
app_url_name

the lower-case URL app name of the app to launch

full_screen

a boolean flag denoting whether to open in a new tab, not inside the desktop app; default (non-desktop) implementation always assumes full_screen (new tab) mode; if the desktop is present, relies on webappos.desktop.launch_in_desktop

Returns

nothing

webappos.​desktop.​set_shared_value
webappos.desktop.set_shared_value = function (
key,
value
)

Sets some desktop-wide property that can be used for inter-app communication.

Parameters
key

a string representing the name of the value

value

the value

Returns

nothing (possible async execution)

webappos.​desktop.​get_shared_value (async)
webappos.desktop.get_shared_value = async function (
key
)

Returns the desired desktop-wide property.

Parameters
key

a string representing the name of the value

Returns

a Promise which resolves in the requested value

webappos.​desktop.​show_dialog [DESKTOP-SPECIFIC]
window.webappos.desktop.show_dialog = function (
title,
content,
fOnClose,
w,
h
)

Asks the desktop to show a dialog window within a desktop.

The default (non-desktop) implementation just opens a simple dojo dialog.

Parameters
title

the window title

content

the innerHTML content of the dialog

fOnClose

a function to call, when the user tries to close the dialog by pressing the "x" button; if not specified, defaults to the function which just closes the dialog

w

desired width (optional)

h

desired height (optional)

Returns

a handle (a number or an object) that can be passed to webappos.desktop.close_dialog; the dialog itself can be displayed later asynchronously

webappos.​desktop.​close_dialog [DESKTOP-SPECIFIC]
window.webappos.desktop.close_dialog = function (
handle
)

Asks the desktop to close the previously open dialog window.

The default (non-desktop) implementation just destroys the dojo dialog.

Parameters
handle

a dialog handle returned by webappos.desktop.show_dialog

Returns

nothing (possible async execution)

webappos.​desktop.​browse_for_file (async)
webappos.desktop.browse_for_file = async function (
dialog_type,
files_filter
)

Shows the browse for file dialog. Relies on webappos.desktop.show_dialog, webappos.desktop.close_dialog, webappos.desktop.set_shared_value, and webappos.desktop.get_shared_value.

Parameters
dialog_type

one of "open", "save", "upload", "dir"

files_filter

a string containing descriptions of file filters to look for; each description is some text followed by file masks in parentheses; filters are delimited by \n, extensions are delimited by ","; Example:  Word document (*.doc,*.rtf), C++ file (*.cpp,*.h,*.hpp)

Returns

a Promise which resolves in a string containing the chosen file name relative to the current login's home folder or null, if no file was chosen;

webappos.​desktop.​show_launcher
webappos.desktop.show_launcher = function (
around_id
)

Shows (or hides, if shown) the launcher menu containing the list of available apps.

Parameters
around_id

the ID of the HTML DOM element, around which the launcher menu has to be shown

Returns

nothing (possible async execution)

webappos.​desktop.​show_user_menu
webappos.desktop.show_user_menu = function (
around_id
)

Shows (or hides, if shown) the user menu containing the "Sign out" button.

Parameters
around_id

the ID of the HTML DOM element, around which the user menu has to be shown

Returns

nothing (possible async execution)

webappos.​close_current_project
webappos.close_current_project = function ()

Closes the current project, but keeps the user signed in.

Returns

nothing; redirects to another page

webappos.​set_project_id (iframe-specific)
window.webappos.set_project_id = function (
new_project_id
)

Updates/changes the current project_id.  This function can be redefined (e.g., by EnvironmentEngine) to changes the displayed project name as well.

Returns

nothing

webAppOS-scopes related functions (iframe-specific)
webappos.​request_scopes (async)
webappos.request_scopes = async function (
driver_name,
scopes
)

Authenticates the user to use one or more particular scopes via the given scopes driver.

For "webappos_scopes" only the "login" and "project_id" ("project_id" is a superset of "login") are currently supported.  If the user is not authenticated, webappos_scopes driver redirects the user to the login page (if a web application is being run as a standalone desktop application, the authentication is automatic and does not require user intervention).  The authentication info is then stored in browser's localStorage keys "login" and "ws_token" as well as in as properties webappos.login and webappos.ws_token.  For the "project_id" scope, the webappos.project_id property is set and web memory is being initialized by connecting to the corresponding server-side web memory slot.

Parameters
driver_name

the name of the scopes driver (e.g., "webappos_scopes" or "google_scopes") that is able to authenticate the requested scopes; the driver must be accessible as scope service (or static .js files for serverless access) at /services/<driver-name>/;

scopes

a space-separated list of desired scopes (specific to scope provider)

Example
webappos.request_scopes("webappos_scopes", "login").then( ()=>
webappos.request_scopes("google_scopes", "https://www.googleapis.com/auth/spreadsheets");
);
Returns

A Promise instance.

webappos.​get_scopes_driver
webappos.get_scopes_driver = function (
driver_name
)

Returns the previously loaded scopes driver.  Can be useful for scopes drivers themselves.

Parameters
driver_name

the driver name (as passed to webappos.request_scopes)

Returns

the previously loaded scopes driver (or undefined).

webappos.​sign_out
window.webappos.sign_out = async function ()

Calls revoke_serverless_access() for all loaded scopes drivers, including "webappos_scopes", if it was loaded (thus, releasing the webAppOS "login" scope and redirecting to the login page).  The sign_out function DOES NOT release server-side scope tokens. This is done intentionally: tokens remain stored at the server side for future access (e.g., for re-mounting cloud drives on the next logon automatically).  An exception is ws_token from the webAppOS "login" scope - it is revoked from the server as well.

Returns

true (if not redirected to the login page)

JavaScript utility functions
webappos.​js_util.​wait (async)
webappos.js_util.wait = async function (
ms
)

Waits the given mount of milliseconds.

Parameters
ms

how many milliseconds to wait

Returns

a Promise that resovles in ms milliseconds

webappos.​js_util.​load_script (async)
webappos.js_util.load_script = async function (
url
)

Loads the given script (asynchronously)

Parameters
url

script url

Returns

A Promise, which either resolves to true, or rejects with an error message.

webappos.​js_util.​exec_script (async)
webappos.js_util.exec_script = async function (
url
)

Loads and executes the given script.

Parameters
url

script url

Returns

A Promise, which either resolves to true, or rejects with an error message.

webappos.​js_util.​show_failure
webappos.js_util.show_failure = function (
message
)

Displays a failure error box.

Parameters
message

an error message to display

Returns

nothing (possible async execution)

webappos.​js_util.​find_element_by_class_name
webappos.js_util.find_element_by_class_name = function (
className,
htmlSubStr
)

Returns the first HTML element having the given class and the given substring within element's innerHTML.

Parameters
className

the CSS class name of the HTML element to find

htmlSubStr

(optional) substring within innerHTML

Returns

the DOM element, or null, if not found

webappos.​js_util.​await_condition (async)
webappos.js_util.await_condition = async function (
fCondition
)

Timeouts until the given condition function returns true.

Parameters
fCondition

a function for checking the condition

Returns

Promise, which resolves when fCondition() returns true

webappos.​js_util.​fire_event
webappos.js_util.fire_event = function (
element,
event_type
)

Emits the given event on the given element.

Parameters
element

the DOM element, for which to fire an event

event_type

a string denoting the event type (e.g., "click")

Returns

true, if all was OK, or false if the event was cancelled (by calling preventDefault)

webappos.​js_util.​print_stack_trace
webappos.js_util.print_stack_trace = function ()

Prints the current stack trace via console.log

Returns

nothing

webappos.​js_util.​clone_object
webappos.js_util.clone_object = function (
obj
)

Calls the object constructor to create a clone of the given object and copies own properties (non-recursively).

Parameters
obj

object to clone

Returns

a cloned object of the same type

webappos.​js_util.​clone_object_properties
webappos.js_util.clone_object_properties = function (
obj
)

Creates a new object {} and copies own properties of the given object (non-recursively).

Parameters
obj

object, from which to get the properties

Returns

an object with the same properties and values

webappos.​js_util.​slice
webappos.js_util.slice = function (
arr,
i,
j
)

Returns a sub-array of the given array. Correctly works with Float64Arrays.

Parameters
arr

array, from which to extract a sub-array

i

(optional) the first index; default=0; if negative, assume index arr.length+i

j

(optional) the next-to-last index; default=arr.length; if negative, assume index arr.length+j

Returns

an object with the same properties and values

webappos.​js_util.​inerit

Implementing the inheritance relation via JavaScript prototypes.

Parameters
proto

the super-class object (prototype)

Returns

a new object, which acts a a subclass of the given proto

webappos.​js_util.​is_true_object
webappos.js_util.is_true_object = function (
item
)

Checks whether the given JS variable is of type "object" AND not null AND not array.

Parameters
item

the JS variable to check

Returns

whether item is of type "object" AND not null AND not array

webappos.​js_util.​is_object
webappos.js_util.is_object = function (
item
)

Checks whether the given JS variable is an object or an array.

Parameters
item

the JS variable to check

Returns

whether item is of type "object" or "object smth."

webappos.​js_util.​is_array
webappos.js_util.is_array = function (
obj
)

Checks whether the given JS variable is an array.

Parameters
obj

the JS variable to check

Returns

whether obj is an array

webappos.​js_util.​is_function
webappos.js_util.is_function = function (
functionToCheck
)

Checks whether the given JS variable is a JS function.

Parameters
functionToCheck

the JS variable to check

Returns

whether functionToCheck is a JS function

webappos.​js_util.​capitalize_first_letter
webappos.js_util.capitalize_first_letter = function (
string
)

Given a string, returns the same string with the first letter capitalized.

Parameters
string

the string to process

Returns

the same string with the first letter capitalized.

webappos.​js_util.​starts_with
webappos.js_util.starts_with = function (
s,
prefix
)

Checks whether the given string s starts with the given prefix.

Parameters
s

the string

prefix

the prefix to check

Returns

whether the given string s starts with the given prefix

webappos.​js_util.​find_element_by_tag_name
webappos.js_util.find_element_by_tag_name = function (
tagName,
htmlSubStr
)

Returns the first HTML element with the given tag name and the given substring within element's innerHTML.

Parameters
tagName

HTML tag name

htmlSubStr

(optional) substring within innerHTML

Returns

the DOM element, or null, if not found

webappos.​js_util.​initialize_file_input
webappos.js_util.initialize_file_input = function(
inputElement,
previouslyChosenFiles
)

Initializes the given <input type="file"> element for uploading files.  Use webappos.js_util.upload_file_input to upload the files.

Parameters
inputElement

the DOM <input> element (as JS object)

previouslyChosenFiles

(optional) file names encoded as string (using ";" as a delimiter) that have been uploaded earlier using the same input element (to inform the user that they have already used this input and now they are going to replace those previously uploaded files)

Returns

the names of previously chosen files encoded as string (using ";" as a delimiter); TODO: the return value may differ from the value of the previouslyChosenFiles argument, if such files do not exist any more

webappos.​js_util.​upload_file_input
webappos.js_util.upload_file_input = function(
inputElement,
pathPrefix
)

Uploads the files selected by the user in the <input type="file"> element.  Can be called even when the input has not been initialized using webappos.js_util.initialize_file_input.

Parameters
inputElement

the DOM <input> element (as JS object)

pathPrefix

the path prefix for each file to be uploaded; relative to the global webAppOS home directory, without unnecessary slashes; default is webappos.login; if you wish to upload files into the current project, pass webappos.project_id

Returns

file names encoded as string (using ";" as a delimiter); file names could be changed, if such files already existed

webappos.​js_util.​show_please_wait
webappos.js_util.show_please_wait = function (
msg
)

Shows a modal "Please, wait" window with the given message.

Parameters
msg

the message to display

Returns

nothing; the window wrap becomes visible

webappos.​js_util.​hide_please_wait
webappos.js_util.hide_please_wait = function ()

Hides the "Please, wait" window shown earlier

Returns

nothing; the window wrap becomes invisible

Useful fields
webappos.​app_url_name
webappos.app_url_name

Stores the current application URL name

webappos.​project_id
webappos.project_id

Stores the current project_id (or null).  Initialized during requrest_scopes("webappos_scopes", "project_id").

Functions for accessing URL query string (iframe-specific)
webappos.​js_util.​get_query_value
webappos.js_util.get_query_value = function (
key
)

Returns the argument value from the query string

Parameters
key

the key name, for which to get the value

Returns

the value for the given key, or null, if the value was not found

webappos.​js_util.​update_query_value
webappos.js_util.update_query_value = function (
key,
value
)

Updates (sets) the given value for the given key in the current query string.

Parameters
key

the key name, for which to update/set the value

value

the value to set

Returns

nothing

webappos.​js_util.​get_and_remove_query_value
webappos.js_util.get_and_remove_query_value = function (
key
)

Given the key, removes the key=value fragment from the query string and returns the deleted value.

Parameters
key

the key name, for which to remove the corresponding query fragment

Returns

the previous value for the given key, or null, if the value was not found

webappos.​js_util.​get_top_level_query_value
webappos.js_util.get_top_level_query_value = function (
key
)

Returns the argument value from the query string of the top-level frame.

Parameters
key

the key name, for which to get the value

Returns

the value for the given key, or null, if the value was not found

"Web memory"-related stuff
webappos.​init_web_memory (iframe-specific)
webappos.init_web_memory = async function ()

Performs the initial synchronization of web memory and keeps on synchronizing.

The function is called from the webappose_scopes web service. It uses login, ws_token, and project_id, and calls webmem.init() internally.

If the server closes the web socket connection (or if the connection is lost for some other reason), the corresponding error message will be displayed with the option to refresh the page.

Normally, the connection is active until the user closes the current browser tab (or desktop iframe), or webappos.close_current_project is called (which replaces the current page with some other).

Returns

nothing (possible async execution)

webmem
window.webmem

Provides access to "web memory". This object becomes available only when web memory has been initialized by calling webappos.init_web_memory. The object will be the same for the iframe that initialized web memory and all descendant iframes that will include webappos.js.

Contains repository objects and classes, which are synchronized automatically with the server.  Given a reference, the corresponding element (object, class, attribute, association) can be accessed as webmem[reference].

Classes can also be accessed as webmem.<ClassName>. Class instances (objects) can be created via the "new" operator. New objects will be automatically accessible as webmem[reference]. They will also be automatically synchronized with the server.

See "JavaScript Model Format" doc for more detail: http://​webappos​.org​/dev​/doc​/index​.html​#File4:webappos​.js_internals​.txt:JavaScript_Model_Format

webmem.​submit

Attaches the given command or event object to the submitter object to execute the given command or handle the given event.

Parameters
obj

an instance of the Event or Command class in web memory

Returns

nothing (possible async execution)

webmem.​webcall (async)

Executes the given web call asynchronously via the current webAppOS web socket.  Client-side webcalls are executed right away.

Parameters
action

the name of the action to call (defined at the server side in *.webcalls files)

arg

the action argument; for jsoncall conventions: a JavaScript(JSON) object or a string; for webmemcall conventions: an integer reference of a web memory argument or a webmem object itself;

Returns

a Promise which resolves in a parsed resulting JSON of the web call as a JavaScript object; the promise is rejected if the returned object contains the "error" attribute, or if some other error occurs