AppSuite:GettingStarted 7.4.2

Getting Started

Hello and welcome to OX AppSuite development. This document will get you started to develop your first own app for OX AppSuite with a minimal setup. We will look at the steps necessary but will also tempt you to learn more by linking you to some more in-depth documentation about these topics. Depending on how you wound up reading this page, you will probably have already completed some of the steps below.

Installing

The build system comes in two variants: as part of the OX App Suite source, and as a Software Development Kit (SDK). The SDK contains only the build system and can be installed as a package. Its only external dependency is Node.js, which should be installed automatically by your package manager. While the core of OX App Suite is supposed to be built using the included version of the build system, either the source or the SDK can be used to build external (i.e. independently installable) apps.

The actual installation depends on the chosen variant:

SDK

First, if not already done, add the Open-Xchange repository to the list of Apt sources.

  # echo deb http://software.open-xchange.com/products/appsuite/\
  stable/appsuiteui/DebianSqueeze/ / >> /etc/apt/sources.list.d/ox.list
  # aptitude update

Then, the actual installation is a single command.

  # aptitude install open-xchange-appsuite-dev

Finally, the main executable of the build system should be put in the executable path for easier calling. This is typically done by either extending the $PATH environment variable

  $ export PATH=$PATH:/opt/open-xchange-appsuite-dev/bin

or symlinking the binary to a directory already in the path.

  # ln -s /opt/open-xchange-appsuite-dev/bin/build-appsuite /usr/local/bin

Source

Using the source variant can avoid the requirement for root permissions.

  $ git clone https://git.open-xchange.com/git/wd/frontend/web

Just like with the SDK variant, the executable should be put in the executable path either by extending the $PATH variable

  $ export PATH="$PATH:$(pwd)/web/ui/bin"

or by symlinking the executable.

  # ln -s "$(pwd)/web/ui/bin/build-appsuite" /usr/local/bin

Create Workspace

In order to have a proper space for your app/plugin create a workspace prospectivly containing all your code. This folder should contain the subfolder apps. The following article is written assuming, you're working in your workspace directory. In this example we will create our own workspace called example-workspace and add the suiteable subdirectory apps for our code:

  $ mkdir example-workspace
  $ cd example-workspace
  $ mkdir apps

Packaging

To keep written plugins/apps easy-to-distribute OX uses the UI Build System packaging new components. Before writing your first lines of code initialize the package to gather information about the app/plugin you're writing:

  $ build-appsuite init-packaging package=example-app

  Build path: build
  Build version: 0.0.1-1.20130424.123835
  
  Version [0.0.1]: 
  
  Maintainer (Name <e-mail>): Maintainer <maintainer@example.com>
  
  Copyright line [2013 Open-Xchange, Inc]: 
  
  License name [CC-BY-NC-SA-3.0]: 
  
  Short description: Hello World app

The task presents a number of interactive prompts to get the necessary information about the generated packages. The entered values should follow the Debian Maintainer's Guide. Some or even all prompts can be skipped by explicitly specifying the information as a build variable. The list of variable names is available in the reference of init-packaging.

After the task is finished, the generated files can be customized manually to account for any additional packaging requirements.

Writing

As an example, let's create a small app and build it. It requires only two files: example-workspace/apps/com.example/main.js for the source code of the app

 
define('com.example/main', function () {
    'use strict';
    var app = ox.ui.createApp({ name: 'com.example' });
    app.setLauncher(function () {
        var win = ox.ui.createWindow({
            name: 'com.example',
            title: 'Hello World App'
        });
        app.setWindow(win);
        win.nodes.main.append($('<h1>').text('Hello, World!'));
        win.show();
    });
    return { getApp: app.getInstance };
});

and example-workspace/apps/com.example/manifest.json for the manifest:

{ title: 'Hello World App' }

Building

While you're in the folder containing apps-subdirectory example-workspace, using the the UI Build System makes building the app is as easy as calling:

$ build-appsuite app

This command will process your app, checking the source code for syntax errors and compressing it, to make it run error-free and fast. Calling this command will also write the processed source to the a subdirectory called build in your workspace, containing also the apps-directory with the original source code.

Running

Hosting the app

For quickest round-trip times, the directory with the generated files in build-folder should be made available via the appserver tool, which is also part of the installed SDK. Your OX App Suite installation will use appserver use as upstream server, Assuming you are calling appserver from your workspace, and using ox.io as server:

$ appserver --server=https://www.ox.io/appsuite/ build

WARNING: Take care that build variables like builddir or manifestDir are not set during development. Otherwise, you will have to specify their directories manually for appserver. Also, the clean task will delete these directories and all their contents! In general, don't point builddir or any other *Dir variables at existing directories.

Executing the app

Once made your app available, you can access your browser opening AppSuite with this address:

http://localhost:8337/appsuite

Then simply run this command in your browser's javascript console to open the hello world application:

ox.launch("com.example/main")