AppSuite:GettingStarted 7.6.0

Getting Started

Hello and welcome to the world of OX App Suite development. This document is designed to get you started with developing your first app for OX App Suite as quickly and simply as possible. However, along the way we will also tempt you to learn more by linking to some more in-depth documentation about the various topics we cover.

Installing the Development Tools

First, you need to install some tools which are necessary for UI development.

$ npm install -g grunt-cli bower yo Open-Xchange-Frontend/generator-ox-ui-module

Create a Workspace

All your app development can take place inside one working directory. The examples will assume you have created a directory named myapp inside your home directory:

$ mkdir ~/myapp
$ cd ~/myapp

It doesn't need to be in your home directory, and the actual name should reflect the name of your app. The main point is that all commands will be executed in this directory and all paths will be relative to this directory from now on.

Now, you can generate a grunt configuration using:

$ yo ox-ui-module

The source code of your app will reside in the subfolder named apps. To avoid name collisions please pick a unique subfolder inside that. The easiest and recommended way is to use a domain name that you own. Typically, the domain elements are reversed, like in Java. example.com becomes com.example:

$ mkdir -p apps/com.example

Writing an App

As an example, let's create the smallest possible app and test it. It requires only two files: apps/com.example/register.js for the source code of the app:

define('com.example/register', function () {
    'use strict';
    alert('Hello, World!');
});

and apps/com.example/manifest.json for the manifest which tells the UI that your app exists and what to do with it:

{ "namespace": "core" }

Building an App

The source code of your app can't be used by OX App Suite as it. It first has to be processed by the build system. This step will check the source code for syntax errors, compress it, and depending on the structure of your code, many other things. The processed code is then written to a directory named build by default. Start the build with this command:

$ grunt

If your editor supports it, you can configure it to call the build system after every file save. Take care to call it from the top directory of your app's workspace, not from the directory of the saved file.

Testing an App

The freshly built code can now be tested. Instead of uploading your code to an OX App Suite server, you can use the appserver proxy to inject your code into the UI code of any existing OX App Suite installation. For example, to start appserver using ox.io as the server, you will need a local configuration pointing to that server. You can generate it with this command:

$ grunt show-config:local --output grunt/local.conf.json

Open up the file grunt/local.conf.json in your editor and add "http://ox.io/ ox.io" to the server setting of the appserver section. Then start the development server:

$ grunt dev

This command will serve your app from the local directory build, and get everything else from the URL specified in the server setting.

Once appserver is running, you can access OX App Suite by opening your browser using this address:

http://localhost:8337/appsuite

After logging in, the app should be loaded and display the alert message.

Development cycle

Once you are sure that your setup works, you can extend the example and write the actual code for your app. The dev task will detect any changes and rebuild your app and even reload all browsers connected to http://localhost:8337/appsuite.

While developing always keep in mind, that there is an article about debugging the user interface which helps you avoid and fix typical errors.

Packaging

Building packages is currently not supported in 7.6.0. We are working on it.

Further Reading

• Congratulations you have just built your first app for OX App Suite, but please keep in mind that there are quite a few options for developing for OX App Suite.
• More information on the build system can be found on github:
  • See all available grunt tasks
  • Documentation of all generator tasks
• If you're stuck somewhere, the article about debugging the UI might help you.
• You can read this to get a better overview of developing the user inferface.