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.
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.
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).
window.webappos.webcall_and_wait = function ( |
| ) |
Executes the given web call synchronously via the webAppOS webcalls service.
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 |
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
window.webappos.webcall = async function ( |
| ) |
Executes the given web call asynchronously via the webAppOS webcalls service. Client-side webcalls are executed right away.
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; |
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
window.webappos.get_client_webcall_window = async function( |
| ) |
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.
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) |
a Promise, which resolves in a DOM window object; the promise rejected if the window was not found
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].
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 = function ( |
| ) |
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.
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); |
nothing (possible async execution)
webappos.desktop.open_path = function ( |
| ) |
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.
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 |
nothing (possible async execution)
webappos.desktop.launch_app = function ( |
| ) |
Launches the given webAppOS app.
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 |
nothing
webappos.desktop.set_shared_value = function ( |
| ) |
Sets some desktop-wide property that can be used for inter-app communication.
key | a string representing the name of the value |
value | the value |
nothing (possible async execution)
webappos.desktop.get_shared_value = async function ( |
| ) |
Returns the desired desktop-wide property.
key | a string representing the name of the value |
a Promise which resolves in the requested value
window.webappos.desktop.show_dialog = function ( |
| ) |
Asks the desktop to show a dialog window within a desktop.
The default (non-desktop) implementation just opens a simple dojo dialog.
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) |
a handle (a number or an object) that can be passed to webappos.desktop.close_dialog; the dialog itself can be displayed later asynchronously
window.webappos.desktop.close_dialog = function ( |
| ) |
Asks the desktop to close the previously open dialog window.
The default (non-desktop) implementation just destroys the dojo dialog.
handle | a dialog handle returned by webappos.desktop.show_dialog |
nothing (possible async execution)
webappos.desktop.browse_for_file = async function ( |
| ) |
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.
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) |
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 = function ( |
| ) |
Shows (or hides, if shown) the launcher menu containing the list of available apps.
around_id | the ID of the HTML DOM element, around which the launcher menu has to be shown |
nothing (possible async execution)
webappos.desktop.show_user_menu = function ( |
| ) |
Shows (or hides, if shown) the user menu containing the "Sign out" button.
around_id | the ID of the HTML DOM element, around which the user menu has to be shown |
nothing (possible async execution)
Closes the current project, but keeps the user signed in.
nothing; redirects to another page
window.webappos.set_project_id = function ( |
| ) |
Updates/changes the current project_id. This function can be redefined (e.g., by EnvironmentEngine) to changes the displayed project name as well.
nothing
webappos.request_scopes = async function ( |
| ) |
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.
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) |
webappos.request_scopes("webappos_scopes", "login").then( ()=>
webappos.request_scopes("google_scopes", "https://www.googleapis.com/auth/spreadsheets");
);
A Promise instance.
webappos.get_scopes_driver = function ( |
| ) |
Returns the previously loaded scopes driver. Can be useful for scopes drivers themselves.
driver_name | the driver name (as passed to webappos.request_scopes) |
the previously loaded scopes driver (or undefined).
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.
true (if not redirected to the login page)
webappos.js_util.wait = async function ( |
| ) |
Waits the given mount of milliseconds.
ms | how many milliseconds to wait |
a Promise that resovles in ms milliseconds
webappos.js_util.load_script = async function ( |
| ) |
Loads the given script (asynchronously)
url | script url |
A Promise, which either resolves to true, or rejects with an error message.
webappos.js_util.exec_script = async function ( |
| ) |
Loads and executes the given script.
url | script url |
A Promise, which either resolves to true, or rejects with an error message.
webappos.js_util.show_failure = function ( |
| ) |
Displays a failure error box.
message | an error message to display |
nothing (possible async execution)
webappos.js_util.find_element_by_class_name = function ( |
| ) |
Returns the first HTML element having the given class and the given substring within element's innerHTML.
className | the CSS class name of the HTML element to find |
htmlSubStr | (optional) substring within innerHTML |
the DOM element, or null, if not found
webappos.js_util.await_condition = async function ( |
| ) |
Timeouts until the given condition function returns true.
fCondition | a function for checking the condition |
Promise, which resolves when fCondition() returns true
webappos.js_util.fire_event = function ( |
| ) |
Emits the given event on the given element.
element | the DOM element, for which to fire an event |
event_type | a string denoting the event type (e.g., "click") |
true, if all was OK, or false if the event was cancelled (by calling preventDefault)
Prints the current stack trace via console.log
nothing
webappos.js_util.clone_object = function ( |
| ) |
Calls the object constructor to create a clone of the given object and copies own properties (non-recursively).
obj | object to clone |
a cloned object of the same type
webappos.js_util.clone_object_properties = function ( |
| ) |
Creates a new object {} and copies own properties of the given object (non-recursively).
obj | object, from which to get the properties |
an object with the same properties and values
webappos.js_util.slice = function ( |
| ) |
Returns a sub-array of the given array. Correctly works with Float64Arrays.
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 |
an object with the same properties and values
Implementing the inheritance relation via JavaScript prototypes.
proto | the super-class object (prototype) |
a new object, which acts a a subclass of the given proto
webappos.js_util.is_true_object = function ( |
| ) |
Checks whether the given JS variable is of type "object" AND not null AND not array.
item | the JS variable to check |
whether item is of type "object" AND not null AND not array
webappos.js_util.is_object = function ( |
| ) |
Checks whether the given JS variable is an object or an array.
item | the JS variable to check |
whether item is of type "object" or "object smth."
webappos.js_util.is_array = function ( |
| ) |
Checks whether the given JS variable is an array.
obj | the JS variable to check |
whether obj is an array
webappos.js_util.is_function = function ( |
| ) |
Checks whether the given JS variable is a JS function.
functionToCheck | the JS variable to check |
whether functionToCheck is a JS function
webappos.js_util.capitalize_first_letter = function ( |
| ) |
Given a string, returns the same string with the first letter capitalized.
string | the string to process |
the same string with the first letter capitalized.
webappos.js_util.starts_with = function ( |
| ) |
Checks whether the given string s starts with the given prefix.
s | the string |
prefix | the prefix to check |
whether the given string s starts with the given prefix
webappos.js_util.find_element_by_tag_name = function ( |
| ) |
Returns the first HTML element with the given tag name and the given substring within element's innerHTML.
tagName | HTML tag name |
htmlSubStr | (optional) substring within innerHTML |
the DOM element, or null, if not found
webappos.js_util.initialize_file_input = function( |
| ) |
Initializes the given <input type="file"> element for uploading files. Use webappos.js_util.upload_file_input to upload the files.
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) |
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 = function( |
| ) |
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.
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 |
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 = function ( |
| ) |
Shows a modal "Please, wait" window with the given message.
msg | the message to display |
nothing; the window wrap becomes visible
Hides the "Please, wait" window shown earlier
nothing; the window wrap becomes invisible
Stores the current application URL name
Stores the current project_id (or null). Initialized during requrest_scopes("webappos_scopes", "project_id").
webappos.js_util.get_query_value = function ( |
| ) |
Returns the argument value from the query string
key | the key name, for which to get the value |
the value for the given key, or null, if the value was not found
webappos.js_util.update_query_value = function ( |
| ) |
Updates (sets) the given value for the given key in the current query string.
key | the key name, for which to update/set the value |
value | the value to set |
nothing
webappos.js_util.get_and_remove_query_value = function ( |
| ) |
Given the key, removes the key=value fragment from the query string and returns the deleted value.
key | the key name, for which to remove the corresponding query fragment |
the previous value for the given key, or null, if the value was not found
webappos.js_util.get_top_level_query_value = function ( |
| ) |
Returns the argument value from the query string of the top-level frame.
key | the key name, for which to get the value |
the value for the given key, or null, if the value was not found
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).
nothing (possible async execution)
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
Attaches the given command or event object to the submitter object to execute the given command or handle the given event.
obj | an instance of the Event or Command class in web memory |
nothing (possible async execution)
Executes the given web call asynchronously via the current webAppOS web socket. Client-side webcalls are executed right away.
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; |
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