Namespace RapidContext.App

Provides functions for application bootstrap and server communication.

Source code: RapidContext_App.js

Namespace Summary
 
Method Summary
<static>  
RapidContext.App.apps()
Returns an array with app launchers.
<static>  
RapidContext.App.callApp(app, method, args)
Performs an asynchronous call to a method in an app.
<static>  
RapidContext.App.callProc(name, args)
Performs an asynchronous procedure call.
<static>  
RapidContext.App.downloadFile(url, data)
Downloads a file to the user desktop.
<static>  
RapidContext.App.findApp(app)
Finds the app launcher from an app instance, class name or launcher.
<static>  
RapidContext.App.init(app)
Initializes the platform, API:s and RapidContext UI.
<static>  
RapidContext.App.loadJSON(url, params, options)
Performs an asynchronous HTTP request for a JSON data document and returns a deferred response.
<static>  
RapidContext.App.loadScript(url)
Loads a JavaScript to the the current page asynchronously and returns a deferred response.
<static>  
RapidContext.App.loadStyles(url)
Loads a CSS stylesheet to the the current page asynchronously and returns a deferred response.
<static>  
RapidContext.App.loadText(url, params, options)
Performs an asynchronous HTTP request for a text document and returns a deferred response.
<static>  
RapidContext.App.loadXHR(url, params, options)
Performs an asynchronous HTTP request and returns a deferred response.
<static>  
RapidContext.App.loadXML(url, params, options)
Performs an asynchronous HTTP request for an XML document and returns a deferred response.
<static>  
RapidContext.App.login(login, password, token)
Performs an asynchronous login.
<static>  
RapidContext.App.logout(reload)
Performs an asyncronous logout.
<static>  
RapidContext.App.startApp(app, container)
Creates and starts an app instance.
<static>  
RapidContext.App.status()
Returns an object with status information about the platform and currently loaded environment.
<static>  
RapidContext.App.stopApp(app)
Stops an app instance.
<static>  
RapidContext.App.user()
Returns an object with information about the user.
Namespace Detail
RapidContext.App
Method Detail
<static> {Deferred} RapidContext.App.init(app)
Initializes the platform, API:s and RapidContext UI. If an app identifier is provided, the default platform UI will not be created. Instead the app will be launched with the root document as its UI container.
Parameters:
{String/Object} app Optional
the app id or class name to start
Returns:
{Deferred} a MochiKit.Async.Deferred object that will callback when the initialization has completed

<static> {Object} RapidContext.App.status()
Returns an object with status information about the platform and currently loaded environment. The object returned is a copy of the internal data structure and can be modified without affecting the real data.
Returns:
{Object} the status data object

<static> {Object} RapidContext.App.user()
Returns an object with information about the user. The object returned is a copy of the internal data structure and can be modified without affecting the real data.
Returns:
{Object} the user data object

<static> {Array} RapidContext.App.apps()
Returns an array with app launchers. The array returned is an internal data structure and should not be modified directly.
Returns:
{Array} the loaded app launchers (read-only)

<static> {Object} RapidContext.App.findApp(app)
Finds the app launcher from an app instance, class name or launcher. In the last case, the matching cached launcher will be returned.
Parameters:
{String/Object} app
the app id, instance, class name or launcher
Returns:
{Object} the read-only app launcher, or null if not found

<static> {Deferred} RapidContext.App.startApp(app, container)
Creates and starts an app instance. Normally apps are started in the default app tab container or in a provided widget DOM node. By specifying a newly created window object as the parent container, apps can also be launched into separate windows.

Note that when a new window is used, the returned deferred will callback immediately with a null app instance (normal app communication is not possible cross-window).
// Starts the help app in a new tab
RapidContext.App.startApp('help');

// Starts the help app in a new window
RapidContext.App.startApp('help', window.open());
Parameters:
{String/Object} app
the app id, class name or launcher
{Widget/Window} container Optional
the app container widget or window, defaults to create a new pane in the app tab container
Returns:
{Deferred} a MochiKit.Async.Deferred object that will callback with the app instance (or null if not available)

<static> {Deferred} RapidContext.App.stopApp(app)
Stops an app instance. If only the class name or launcher is specified, the most recently created instance will be stopped.
Parameters:
{String/Object} app
the app id, instance, class name or launcher
Returns:
{Deferred} a MochiKit.Async.Deferred object that will callback when the app has been stopped

<static> {Deferred} RapidContext.App.callApp(app, method, args)
Performs an asynchronous call to a method in an app. If only the class name or launcher is specified, the most recently created instance will be used. If no instance is running, one will be started. Also, before calling the app method, the app UI will be focused.
Parameters:
{String/Object} app
the app id, instance, class name or launcher
{String} method
the app method name
{Mixed} args Optional
additional parameters sent to method
Returns:
{Deferred} a MochiKit.Async.Deferred object that will callback with the result of the call on success

<static> {Deferred} RapidContext.App.callProc(name, args)
Performs an asynchronous procedure call. This function returns a deferred object that will produce either a callback or an errback depending on the server response.
Parameters:
{String} name
the procedure name
{Array} args Optional
the array of arguments, or null
Returns:
{Deferred} a MochiKit.Async.Deferred object that will callback with the response data on success

<static> {Deferred} RapidContext.App.login(login, password, token)
Performs an asynchronous login. This function returns a deferred object that will produce either a callback or an errback depending on the success of the login attempt. If the current session is already bound to a user, that session will be terminated and a new one will be created. If an authentication token is specified, the login and password fields are not used (can be null).
Parameters:
{String} login
the user login name or email address
{String} password
the password to autheticate the user
{String} token Optional
the authentication token to indentify user/password
Returns:
{Deferred} a MochiKit.Async.Deferred object that will callback with the response data on success

<static> {Deferred} RapidContext.App.logout(reload)
Performs an asyncronous logout. This function terminates the current session and either reloads the browser window or returns a deferred object that will produce either a callback or an errback response.
Parameters:
{Boolean} reload Optional
the reload browser flag, defaults to true
Returns:
{Deferred} a MochiKit.Async.Deferred object that will callback with the response data on success

<static> {Deferred} RapidContext.App.loadJSON(url, params, options)
Performs an asynchronous HTTP request for a JSON data document and returns a deferred response. If no request method has been specified, the POST or GET methods are chosen depending on whether or not the params argument is null. The request parameters are specified as an object that will be encoded by the MochiKit.Base.queryString function. In addition to the default options in MochiKit.Async.doXHR, this function also accepts a timeout option for automatic request cancellation.

Note that this function is unsuitable for loading JavaScript source code, since using eval() will confuse some browser error messages and debuggers regarding the actual source location.
Parameters:
{String} url
the URL to request
{Object} params Optional
the request parameters, or null
{Object} options Optional
the request options, or null
{String} options.method Optional
the HTTP method, GET or POST
{Number} options.timeout Optional
the timeout in seconds, default is no timeout
{Object} options.headers Optional
the specific HTTP headers to use
{String} options.mimeType Optional
the override MIME type, default is none
Returns:
{Deferred} a MochiKit.Async.Deferred object that will callback with the response text on success

<static> {Deferred} RapidContext.App.loadText(url, params, options)
Performs an asynchronous HTTP request for a text document and returns a deferred response. If no request method has been specified, the POST or GET methods are chosen depending on whether or not the params argument is null. The request parameters are specified as an object that will be encoded by the MochiKit.Base.queryString function. In addition to the default options in MochiKit.Async.doXHR, this function also accepts a timeout option for automatic request cancellation.

Note that this function is unsuitable for loading JavaScript source code, since using eval() will confuse some browser error messages and debuggers regarding the actual source location.
Parameters:
{String} url
the URL to request
{Object} params Optional
the request parameters, or null
{Object} options Optional
the request options, or null
{String} options.method Optional
the HTTP method, GET or POST
{Number} options.timeout Optional
the timeout in seconds, default is no timeout
{Object} options.headers Optional
the specific HTTP headers to use
{String} options.mimeType Optional
the override MIME type, default is none
Returns:
{Deferred} a MochiKit.Async.Deferred object that will callback with the response text on success

<static> {Deferred} RapidContext.App.loadXML(url, params, options)
Performs an asynchronous HTTP request for an XML document and returns a deferred response. If no request method has been specified, the POST or GET methods are chosen depending on whether or not the params argument is null. The request parameters are specified as an object that will be encoded by the MochiKit.Base.queryString function. In addition to the default options in MochiKit.Async.doXHR, this function also accepts a timeout option for automatic request cancellation.
Parameters:
{String} url
the URL to request
{Object} params Optional
the request parameters, or null
{Object} options Optional
the request options, or null
{String} options.method Optional
the HTTP method, GET or POST
{Number} options.timeout Optional
the timeout in seconds, default is no timeout
{Object} options.headers Optional
the specific HTTP headers to use
{String} options.mimeType Optional
the override MIME type, default is none
Returns:
{Deferred} a MochiKit.Async.Deferred object that will callback with the parsed response XML document on success

<static> {Deferred} RapidContext.App.loadXHR(url, params, options)
Performs an asynchronous HTTP request and returns a deferred response. If no request method has been specified, the POST or GET methods are chosen depending on whether or not the params argument is null. The request parameters are specified as an object that will be encoded by the MochiKit.Base.queryString function. In addition to the default options in MochiKit.Async.doXHR, this function also accepts a timeout option for automatic request cancellation.

Note that this function is unsuitable for loading JavaScript source code, since using eval() will confuse some browser error messages and debuggers regarding the actual source location.
Parameters:
{String} url
the URL to request
{Object} params Optional
the request parameters, or null
{Object} options Optional
the request options, or null
{String} options.method Optional
the HTTP method, GET or POST
{Number} options.timeout Optional
the timeout in seconds, default is no timeout
{Object} options.headers Optional
the specific HTTP headers to use
{String} options.mimeType Optional
the override MIME type, default is none
Returns:
{Deferred} a MochiKit.Async.Deferred object that will callback with the XMLHttpRequest instance on success

<static> {Deferred} RapidContext.App.loadScript(url)
Loads a JavaScript to the the current page asynchronously and returns a deferred response. This function is only suitable for loading JavaScript source code, and not JSON data, since it loads the script by inserting a <script> tag in the document <head> tag. All function definitions and values must therefore be stored to global variables by the script to be accessible after loading. The deferred callback function will therefore not provide any data even on successful callback.

This method of script loading has the advantage that JavaScript debuggers (such as Firebug) will be able to handle the code properly (error messages, breakpoints, etc). If the script fails to load due to errors however, the returned deferred object may fail to errback in some cases.
Parameters:
{String} url
the URL to the script
Returns:
{Deferred} a MochiKit.Async.Deferred object that will callback when the script has been loaded

<static> {Deferred} RapidContext.App.loadStyles(url)
Loads a CSS stylesheet to the the current page asynchronously and returns a deferred response. The stylesheet is loaded by inserting a <link> tag in the document head tag, which means that the deferred callback function will not be provided with any data.
Parameters:
{String} url
the URL to the stylesheet
Returns:
{Deferred} a MochiKit.Async.Deferred object that will callback when the stylesheet has been loaded

<static> RapidContext.App.downloadFile(url, data)
Downloads a file to the user desktop. This works by creating a new window or an inner frame which downloads the file from the server. Due to Content-Disposition headers being set on the server, the web browser will popup a dialog for the user to save the file. This function can also be used for saving a file that doesn't exist by first posting the file (text) content to the server.
Parameters:
{String} url
the URL or filename to download
{String} data Optional
the optional file data (if not available on the server-side)