1. Documentation
2. App Development

6. App Development

6.1. Technology Reference

RapidContext app development is mostly based on JavaScript, HTML and CSS. The apps execute in the web browsers, so care must therefore be taken to follow appropriate web standards to remain compatible with all browsers. The most important of these are listed below:

• HTML 5 — User interface structure and presentation. Normally accessed from JavaScript through the HTML DOM.
• CSS 2 & CSS 3 — User interface style and layout. Normally accessed from JavaScript through the HTML and CSS DOM.
• JavaScript — Programming language reference for the core JavaScript library.
• DOM Core, DOM HTML & DOM Window — Provides access to HTML, CSS and the browser environment from JavaScript.

RapidContext also provides a number of JavaScript libraries that greatly simplify the development:

• RapidContext JavaScript API — Provides server-side communication, app launching and utilities. Also contains a user interface widget library.
• MochiKit — A swiss-army knife with utilities and functions missing from the core JavaScript language.
• jQuery — Provides simple and efficient access to HTML and CSS (via DOM).
• Crypto-JS (MD5) — Provides MD5 hash functions.

6.2. App Configuration

The app source code and resources are stored on the server, but will be transferred to the web browser upon launch. Each app has an app configuration (i.e. a manifest) that lists resources required for launch along with some meta-data. These can be inspected in the Admin app, as shown in the screenshot below.

The app configuration is placed in the plugin/local/app/ directory (or the app/ directory in your plug-in). The file name should follow normal storage rules (e.g. [app identifier].properties). In the file, app meta-data is specified with a list of URL resources required to launch the app. If an app is not properly declared in the configuration file, it will not be visible to the web browser. Below follows a simple example:

# General properties
name = Example App
description = A simple example app to play and experiment with.
className = ExampleApp

# Resources array
resources.0.type = code
resources.0.url = app/example/app.js
resources.1.type = ui
resources.1.url = app/example/ui.xml
resources.2.type = icon
resources.2.url = app/example/icon.png
  

In the example above, the three files app.js, ui.xml and icon.png are referenced and must be located at the specified URL. Any app resource of type code is dynamically loaded as a JavaScript file on the first app launch. Subsequent launches will reuse the previously loaded file, so web page must be reloaded to force an app to be updated.

The available app configuration parameters are as follows:

• name — The app name as presented to the user. This name is shown in various places in the default user interface.
• description — The optional app description that is presented to the user.
• className — The app JavaScript class name. This name refers to a constructor function for the app instance (see next section). The class name must be unique to avoid collisions with other apps loaded at the same time (in the web page). The source code for the class should be placed in one of the code resources listed.
• launch — The optional app launch setting. This may have one of the following values:
  • manual (default) — The app is manually started and stopped by the user (when clicking on icons or similar).
  • auto — The app is started automatically when a new user session starts, but can also be started and stopped manually by the user.
  • once — The app is started automatically when a new user session starts and can thereafter neither be started nor stopped by the user.
  • window — The app is always launched in a separate window (similar to holding Alt or Ctrl for other apps). This limits the possibility for other apps to interchange calls or data.
  • limited — The app is hidden from the user to avoid manual starting and stopping in the default user interface. The app can still be started programmatically by other apps through the RapidContext client API:s.
• resources.#.type — The resource type. This may have one of the following values:
  • <none> — The resource type will be guessed based on the url if omitted.
  • code — A JavaScript source code file that will be loaded before app launch.
  • style — A CSS stylesheet file that will be loaded before app launch.
  • ui — A user interface XML definition file (see below). The interface specified in this file is built each time the app is launched.
  • icon — An icon displayed with the launcher for the app. Can be either a an image URL (48x48 pixels), an HTML snipplet or a CSS class name.
  • json — A JSON data file that is loaded and provided as an app resource.
  • * — Other resource types may be used, but have no special handling.
• resources.#.id — The optional resource identifier. All resources with an identifier can easily be accessed from the app JavaScript code, using this.resource.[id].
• resources.#.url — The optional resource URL. If local, it should be relative to the root files/ storage directory. The files should thus be placed either in plugin/local/files/ or in files/ inside your plug-in. Local resource URLs support glob matching (e.g. myapp/*.js or dir/myapp/**).
• resources.#.html — The optional resource HTML. Used as an alternative to image app icons.
• resources.#.class — The optional resource CSS class. Used as an alternative to image app icons.
• resources.#.topic — The optional resource help topic name. The corresponding resource URL should point to an HTML help document for the app. The topic name may contain / characters to indicate directories.

6.3. App Implementation

All apps are implemented as JavaScript objects with constructor function (i.e. as JavaScript "classes"). Normally a single code resource contains the source code for the app. By declaring multiple code resources, several files can be loaded (in the specified order). Upon launch, the app constructor function is called and a new app instance object should be created.

The JavaScript constructor function for an app must be named exactly as specified by the className property in the app configuration. The app instance objects must also contain two methods — start() and stop() — that handle the app lifecycle. Below is an example JavaScript file that implements a minimal example app:

/**
 * Creates a new ExampleApp instance. This function is called
 * once all app resources have been loaded. It is called as a
 * constructor function, so it will create a new object with
 * the prototype inherited from this function.
 */
function ExampleApp() {
    // Constructor code. No UI or external calls here.
}

/**
 * Starts the app execution. This function is called when the
 * user interface has been successfully created.
 */
ExampleApp.prototype.start = function() {
    // this.ui -- a map of identifiers from the UI XML
    // this.ui.root -- the user interface parent widget
    // this.ui.overlay -- the overlay widget for the app
    // this.resource -- a map of resource URL:s
}

/**
 * Stops the app execution. This function is called when the
 * app should terminate, but before the user interface has
 * been destroyed. The app should kill running requests and
 * similar when this method is called.
 */
ExampleApp.prototype.stop = function() {
    // stop async requests and other pending actions
}
  

The RapidContext.App.startApp() function is responsible for app loading, instance creation and calling the start() method once the user interface has been created. Each app instance will also inherit all properties from app config, with the following adjustments:

• this.ui — Contains an Object with properties for any user interface widget with an id attribute. The property value is set to the UI widget or DOM node.
• this.ui.root — Contains the parent container widget for the app user interface, normally an instance of RapidContext.Widget.Pane.
• this.ui.overlay — Contains a RapidContext.Widget.Overlay widget for the whole app user interface. This overlay was used while loading the app resources, and is thereafter available to the app.
• this.resource — Contains an Object with properties for any app resource with an id property in app configuration. The value is a string with the resource URL. Note that all resources are also available in the this.resources array.

6.4. User Interface XML

The user interface for an app is normally contained inside an RapidContext.Widget.TabContainer widget. The app itself is assigned a RapidContext.Widget.Pane widget inside which it is responsible for creating and managing its own user interface.

The RapidContext platform simplifies the user interface creation by optionally building it from a serialized XML format. The user interface XML is normally stored in a ui.xml file in the same location as the app JavaScript source code and other resources. To use the automatic user interface creation, an app resource is specified as follows:

resources.#.type = ui
resources.#.url = example/ui.xml
  

The ui.xml file contains a mix of HTML (in XML form) and references to user interface widgets defined in the RapidContext.Widget namespace. The XML is processed by the RapidContext.UI.buildUI function. Here is a simple example:

<?xml version="1.0" encoding="UTF-8"?>

<ui>
  <Button id="test" icon="COMMENT">Press Me</Button>
</ui>
  

The root XML tag in a ui.xml file should always be <ui>. Inside this tag, all well-formed XML tags will be interpreted as follows:

• Tag Names — The XML tag names will be looked up in the RapidContext.Widget.CLASSES map, using the exact case-sensitive tag name. If found, the corresponding widget constructor function is used to create the HTML DOM node. Otherwise the tag name is sent to MochiKit.DOM.createDOM() to create the corresponding HTML DOM node.
• The id Attribute — The id attribute is used to map the DOM node to the app this.ui object. It is NOT set on the HTML DOM node created. The benefit of this solution is that any identified DOM nodes are immediately available, without going through the DOM API document.getElementById. Also, this solution avoids collisions when the same app is launched twice or when multiple apps use the same identifiers.
• The class Attribute — The class attribute is set on the HTML DOM node created (similar to HTML). Note that widgets have additional CSS classes, potentially causing conflicts with specific style settings (see below).
• The w & h Attributes— The attributes w and h are used in a call to RapidContext.Util.registerSizeConstraints(). This sets up either a CSS calc(...) style or a JavaScript function for the node that will calculate the appropriate size whenever RapidContext.Util.resizeElements() is called (handled automatically on window resize).
• Other Attributes — Other XML attributes are either set as string values to the HTML DOM nodes created, or sent to the corresponding RapidContext.Widget.setAttrs() function. This makes it possible to configure each widget with the specific attributes supported.

6.5. User Interface Style

The platform user interface is default styled by two CSS files — css/style.css and css/widget.css. When the default styles are not sufficient, a number of options are available:

1. Element style Attributes — The easiest way to modify the style of a widget or an HTML DOM node is by setting the style attribute. This can be done either in the ui.xml file or through the MochiKit.Style.setStyle() function.
2. Inline <style> Tags — The ui.xml file may contain an additional <style> tag with CSS rules to add to the page. Care should be taken use proper class attributes to avoid restyling other apps.
3. CSS Resource Files — CSS rules can also be loaded from an app resource URL, as explained previously. Again, care should be taken use proper class attributes to avoid restyling other apps.
4. Edit Default CSS Files — The default CSS files are located in the system plug-in and can be replaced by any other loaded plug-in. Replacing the default styles or images is useful for creating new user interface themes for the whole platform, but is strongly discouraged for other purposes. The styles and images provided in the default CSS files may change without notice in future versions.

6.6. Web Listeners & Services

RapidContext provides a default web listener for HTTP requests. This is the web listener that launches the start app and handles the platform web requests. It is configured in the webservice/root.yaml file:

id: root
type: webservice/app
description: >-
    The root (default) web service. This launches the start app and provides
    access to the storage files.
path: /files/
app: start
header:
  ...
match:
  - path: /
  

Although the default web listener responds to all requests, it is easy to add a custom listener to handle requests for a specific host, path, etc. The example below shows a simple file web server:

id: www.test.com
type: webservice/file
description: A simple static web site service.
path: files/www.test.com/
match:
  - host: www.test.com
  - host: www.test.net
  - host: www.test.org
  

Web listeners configurations are placed in the plugin/local/webservice/ directory (or the webservice/ directory in your plug-in). The file name should follow normal storage rules (e.g. [identifier].properties). A number of web service types are available and custom ones can also be implemented in Java.

The available web service configuration parameters are as follows:

• id — The unique web service identifier. May only contain ASCII alphanumeric characters without spaces or separators.
• type — The web service type. This may have one of the following values:
  • webservice/file — Provides storage file access, similar to a normal web server.
  • webservice/app — Extends the webservice/file service by providing a default app launcher and APIs.
  • webservice/procedure — Provides a procedure API web service for executing procedures.
  • webservice/storage — Provides a storage API web service for reading and writing data.
• description — The optional description text for this resource.
• match.#.method — The optional HTTP request method to match. Defaults to blank, meaning that any request method will match. A non-blank value contributes 400 points to the reqest match score.
• match.#.protocol — The optional request protocol to match (i.e. http or https). Defaults to blank, meaning that any protocol will match. A non-blank value contributes 300 points to the request match score.
• match.#.host — The optional web server host name to match. Defaults to null, meaning that any host name will match. A non-blank value contributes 200 points to the request match score.
• match.#.port — The optional web server port number to match. Defaults to zero (0), meaning that any port number will match. A non-blank value contributes 100 points to the request match score.
• match.#.path — The optional base request path to match. Defaults to an empty string, meaning that any path will match. A non-blank value contributes its length to the request match score.
• match.#.auth — The optional user authentication required flag. Defaults to false, meaning that anonymous access is allowed.
• match.#.prio — The optional matcher priority. Defaults to zero (0). Contributes its own value to the request match score. The web listener with the highest match score serves the request.

The webservice/file listener automatically maps directories to index.html files. If a requested file is missing, the parent directories are searched for the nearest 404.html or index.html file. This allows single-page apps to match any URL.

The webservice/file and webservice/app listeners support the following additional parameters:

• path — The base storage path for file lookups. Defaults to /files/.

The webservice/app listeners support the following additional parameters:

• app — The app identifier for the default launcher Defaults to start.
• login — The app identifier for the alternative launcher to use for non-authorized users. Defaults to login.
• title — The web page title. Defaults to RapidContext.
• lang — The web page ISO language code. Defaults to en.
• viewport — The web page meta viewport tag. Defaults to width=device-width, initial-scale=1.
• header.# — The optional HTML headers to add to the page. Normally used for favicons and similar.

The webservice/procedure listeners support the following additional parameters:

• prefix — The optional procedure name prefix, used for locating the procedure to execute. Any additional request path will be appended to this prefix to form the full procedure identifier.
• inputType — The input arguments data format. Available options are json (for serialized JSON data, the default), or text (for plain text).
• outputType — The output response data format. Available options are json+metadata (for a serialized JSON object with data or error properties, the default), json (for just the serialized JSON response), or text (for plain text output).