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

Running

The build system is executed by invoking the command build-appsuite. Similar to most build systems, the build system can perform multiple tasks, which are specified as parameters on the command line. Each task can require any number of parameters. These parameters can be specified either on the command line, using the syntax name=value, or as environment variables.

If present, the file local.conf is sourced by a shell script before the build process starts. This file can export environment variables which are specific to the local system, without checking them into a version control system. Typically, it defines values for builddir and debug.

Since the build system is based on Jake, it also accepts all other Jake options. In addition, the environment variable $nodeopts can be used to pass command line parameters to Node.js. One of the most useful parameters is --debug-brk, which can be used to debug the build system.

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.

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 the app is as easy as calling while you're in the folder containing apps-subdirectory example-workspace

$ build-appsuite app