|
|
| (31 intermediate revisions by 7 users not shown) |
| Line 1: |
Line 1: |
| <div class="title">Writing a simple application</div>
| | The content on this page has moved to https://documentation.open-xchange.com/latest/ui/customize/app/simple-application.html |
|
| |
|
| Todo: Screenshots!
| | Note: Open-Xchange is in the process of migrating all its technical documentation to a new and improved documentation system (documentation.open-xchange.com). Please note as the migration takes place more information will be available on the new system and less on this system. Thank you for your understanding during this period of transition. |
| | |
| __TOC__
| |
| | |
| ==Getting Started==
| |
| | |
| First create a new folder <tt>helloWorld</tt> in your namespace in the app folder, in this example the namespace <tt>com.example</tt> will be used. (<tt>apps/com.example/helloWorld</tt>)
| |
| | |
| For starters we need two files: a manifest File <tt>manifest.json</tt> and the application file.
| |
| It is convention to name your main application file <tt>main.js</tt>.
| |
| | |
| ==Manifest==
| |
| | |
| First create a manifest.json file, describing the basic properties of your app.
| |
| | |
| <pre class="language-javascript">
| |
| {
| |
| title: "Hello World",
| |
| company: "Open-Xchange",
| |
| icon: "/images/icon.png",
| |
| category: "Dev",
| |
| settings: false,
| |
| requires: "dev",
| |
| index: 100
| |
| }
| |
| </pre>
| |
| | |
| Whilst developing, the manifest has to be added to <tt>src/manifests.json</tt>.
| |
| ''Note: Same as above except for the path, which is mandatory.''
| |
| | |
| <pre class="language-javascript">
| |
| ...
| |
| {
| |
| path: 'com.example/helloWorld/main',
| |
| title: "Hello World",
| |
| company: "Open-Xchange",
| |
| icon: "/images/icon.png",
| |
| category: "Dev",
| |
| settings: false,
| |
| requires: "dev",
| |
| index: 100
| |
| },
| |
| ...
| |
| </pre>
| |
| | |
| ===Setting an app icon===
| |
| | |
| It is convention to place your app image into a subfolder of your app called images.
| |
| The icon defined here will be displayed in the "Your applications" area.
| |
| | |
| [[File:Hello_World_-_Your_applications.png|400px|thumb]]
| |
| | |
| ==Simple application==
| |
| | |
| This is the base skeleton of a new app with a window, that displays "Hello World".
| |
| Please read the annotated source code of an example main.js below, it is quite self-explanatory.
| |
| | |
| <pre class="language-javascript">
| |
| define('com.example/helloWorld/main', ['io.ox/core/commons'], function () {
| |
| | |
| 'use strict';
| |
| | |
| // this is just code. loading this does not imply to launch the application
| |
| | |
| // application object. 'name' is mandatory!
| |
| var app = ox.ui.createApp({ name: 'com.example/helloWorld' });
| |
| | |
| // by using setLauncher this way, we register a callback function
| |
| // that is called when the application is really launched
| |
| app.setLauncher(function () {
| |
| | |
| // application window (some applications don't have a window)
| |
| var win = ox.ui.createWindow({
| |
| name: 'com.example/helloWorld',
| |
| title: 'Hello World'
| |
| });
| |
| | |
| app.setWindow(win);
| |
| | |
| // Add css class with your namespace
| |
| win.addClass('com-example-helloWorld');
| |
| | |
| // add something on 'main' node
| |
| win.nodes.main
| |
| .css({ padding: '13px', textAlign: 'center' })
| |
| .append($('<h1>').text('Hello World!'));
| |
| | |
| // show the window
| |
| win.show();
| |
| });
| |
| | |
| return {
| |
| getApp: app.getInstance
| |
| };
| |
| });
| |
| </pre>
| |
| | |
| Save this file, build and refresh your browser, go to "Your applications", where you should find your app with your app icon.
| |
| Hint: You can also launch the application manually via your browsers console:
| |
| | |
| <pre class="language-javascript">
| |
| ox.launch('com.example/helloWorld/main');
| |
| </pre>
| |
| | |
| [[File:Hello_World_-_Simple_Application.png|300px|thumb]]
| |
| | |
| ===Styles===
| |
| | |
| In order to prevent conflicts with other apps or base-styles you should add a css class with your namespace to the main node of your application.
| |
| | |
| <pre class="language-javascript">
| |
| win.addClass('com-example-helloWorld');
| |
| </pre>
| |
| | |
| It is convention to create a file called style.less in the root folder of your application.
| |
| This file has to be defined for [http://requirejs.org/docs/api.html require.js] which is done like this.
| |
| | |
| <pre class="language-javascript">
| |
| ...
| |
| define('com.example/helloWorld/main',
| |
| ['less!com.example/helloWorld/style.less'
| |
| ], function () {
| |
| ...
| |
| </pre>
| |
| | |
| A simple less file would look like this:
| |
| | |
| <pre class="language-less">
| |
| .com-example-helloWorld {
| |
| h1 {
| |
| color: red;
| |
| }
| |
| ...
| |
| }
| |
| </pre>
| |
| | |
| | |
| ===Internationalization (i18n)===
| |
| | |
| In order to get <tt>gettext</tt> support for your app you have to require it:
| |
| | |
| <pre class="language-javascript">
| |
| ...
| |
| define('com.example/helloWorld/main',
| |
| [...
| |
| 'gettext!com.example/helloWorld'
| |
| ...
| |
| ], function (gt) {
| |
| ...
| |
| </pre>
| |
| | |
| Every string in your app should be processed by <tt>gettext</tt> in order to have them properly translated.
| |
| In our example it would look like this:
| |
| | |
| <pre class="language-javascript">
| |
| ...
| |
| .append($('<h1>').text(gt('Hello World!')));
| |
| ...
| |
| </pre>
| |
| | |
| Hint: If you want to check your app for untranslated strings, append <tt>&debug-i18n=true</tt> to the URL in your browser and refresh. If a string is not processed by <tt>gettext</tt> it will be highlighted.
| |
| | |
| You can find more detailed information on this topic here: [[Appsuite:i18n]]
| |
| | |
| ===Making an application window chromeless===
| |
| | |
| If you don't have the need for a toolbar and want a chromeless window, you can it in the ox.ui.createWindow function call.
| |
| | |
| <pre class="language-javascript">
| |
| ...
| |
| var win = ox.ui.createWindow({
| |
| ...
| |
| chromeless: true
| |
| ...
| |
| });
| |
| ...
| |
| </pre>
| |
| | |
| ===Creating a Dialog===
| |
| | |
| In order to open a dialog <tt>io.ox/core/tk/dialogs</tt> has to be required and use one of the supplied methods.
| |
| | |
| <pre class="language-javascript">
| |
| ...
| |
| win.nodes.main
| |
| .append($('<a class="btn">').text('Open Modal Dialog')
| |
| .on('click', function (e) {
| |
| e.preventDefault();
| |
| require(['io.ox/core/tk/dialogs'],
| |
| function (dialogs) {
| |
| new dialogs.ModalDialog({
| |
| width: 600,
| |
| easyOut: true
| |
| })
| |
| .append($('<p>').text('Hello world'))
| |
| .addButton('close', 'Close')
| |
| .show();
| |
| }
| |
| );
| |
| })
| |
| );
| |
| ...
| |
| </pre>
| |
| | |
| ==Displaying a notification==
| |
| | |
| If you want to display notifications you can require <tt>io.ox/core/notifications</tt> and use the yell method, like in the examples below.
| |
| | |
| <pre class="language-javascript">
| |
| ...
| |
| require(['io.ox/core/notifications'],
| |
| function (notifications) {
| |
| win.nodes.main
| |
| .append(
| |
| $('<a class="btn">').text('Display success notfication')
| |
| .on('click', function () {
| |
| notifications.yell('success', 'Ah success!');
| |
| }),
| |
| $('<a class="btn">').text('Display error notfication')
| |
| .on('click', function () {
| |
| notifications.yell('error', 'Oh failed!');
| |
| })
| |
| );
| |
| });
| |
| ...
| |
| </pre>
| |
| | |
| ==Displaying a Halo View==
| |
| | |
| ===For internal users===
| |
| | |
| <pre class="language-javascript">
| |
| ...
| |
| win.nodes.main.append(
| |
| $('<a href="#" class="btn halo-link">')
| |
| .data({ internal_userid: ox.user_id })
| |
| .text('Open Halo')
| |
| );
| |
| ...
| |
| </pre>
| |
| | |
| ===For external users===
| |
| | |
| <pre class="language-javascript">
| |
| ...
| |
| win.nodes.main.append(
| |
| $('<a class="btn halo-link">')
| |
| .data({ email1: "test@example.com" })
| |
| .text('Open Halo from Email')
| |
| );
| |
| ...
| |
| </pre>
| |
| | |
| ==Download full example==
| |
| | |
| You can download the example application here with all above shown examples above included.
| |
| [Include link here]
| |
| | |
| [[Category:AppSuite]]
| |
| [[Category:UI]]
| |