AppSuite:GettingStarted 7.4.2: Difference between revisions
Line 19: | Line 19: | ||
# ln -s "$(pwd)/web/ui/bin/build-appsuite" /usr/local/bin | # ln -s "$(pwd)/web/ui/bin/build-appsuite" /usr/local/bin | ||
There's also the option running | There's also the option of running your environment [[AppSuite:Appserver#Use_with_Apache | using a apache server]]. | ||
== Preparing == | == Preparing == |
Revision as of 15:14, 23 October 2013
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 actual installation of the UI build system can be done performing these simple tasks:
$ git clone --depth 1 -b develop https://code.open-xchange.com/git/wd/frontend/web
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
There's also the option of running your environment using a apache server.
Preparing
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' }
While developing always keep in mind, that there is an article about debugging the userinterface which helps you avoiding and fixing typical errors.
Building
This step 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.
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
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
This command will host your app locally. Once you started it, it will always have to run in the background, making all changes within the given build-directories visible. To add the build path of an other workspace, stop appserver and run the upper command again appending the other directory after a white space.
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.
Testing the app
Once made your app available, you can access AppSuite opening your browser 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")
Development cycle
Once successfully tested your first app, you will probably continue developing it. Keep in mind that after writing your code, you will always need to build the app and have your Appserver running.
Further Reading
- You just build your first app for AppSuite, keep in mind that there quite a few options how you can develop for AppSuite.
- It's highly recommended to gain more knowledge about all the benefits the UI build system and the Appserver are providing you for developing AppSuite.
- If you're stuck somewhere, the article about debugging the UI might help you.
- Get a better overview about developing the user inferface.