WebMail Pro documentation

Creating Hello World app

In this tutorial, we'll create a very simple application for Aurora, all it's going to do is displaying "Hello world" message. We'll make sure the link to this application is added to main menu. This sample application is available for download here.

In Aurora, every application consists of at least one module, and each of the modules has its separate subdirectory under modules dir. Applications usually have their logic and presentation separated, hence the modules can be backend and frontend ones. While it's not a strict requirement, the recommended naming policy for frontend modules assumes appending Webclient to module names.

To begin, we need to create a subdirectory under modules dir. Our application will only have one frontend module, and we will call it HelloWorldWebclient.

Then we create three directories under modules/HelloWorldWebclient: js for JavaScript code, templates for HTML templates and i18n for translation files.

The first and primary file of the module is js/manager.js:

'use strict';
module.exports = function (oAppData) {
    var
        TextUtils = require('%PathToCoreWebclientModule%/js/utils/Text.js'),
        App = require('%PathToCoreWebclientModule%/js/App.js'),
        sHash = 'helloworld'
    ;
    if (App.getUserRole() === Enums.UserRole.NormalUser)
    {
        return {
            getScreens: function ()
            {
                var oScreens = {};
                oScreens[sHash] = function () {
                    return require('modules/%ModuleName%/js/views/MainView.js');
                };
                return oScreens;
            },
            getHeaderItem: function ()
            {
                var CHeaderItemView = require('%PathToCoreWebclientModule%/js/views/CHeaderItemView.js');
                return {
                    item: new CHeaderItemView(TextUtils.i18n('%MODULENAME%/ACTION_SHOW_HELLOWORLDAPP')),
                    name: sHash
                };
            }
        };
    }
    return null;
}; 

Let's look at what this code is doing. It starts with including two utilities and denotes hash value used in URL for switching to this application.

The following condition:

    if (App.getUserRole() === Enums.UserRole.NormalUser)
    {
        ...
    }

ensures that only authenticated user, one that doesn't have admin privileges, can access the application.

getScreens function adds a screen for our application and includes js/views/MainView.js file we'll cover below. As for getHeaderItem function, its purpose is adding a link to main menu.

As you can see, the code makes use of language constants. Our module supplies those in i18n/English.ini and i18n/Russian.ini files; if you plan to use Aurora interface in different language, you'll need to provide translation file for that language as well. Take a look at i18n/English.ini file:

HEADING_BROWSER_TAB = "Hello World"
ACTION_SHOW_HELLOWORLDAPP = "HelloWorld"
HEADING_HELLO_WORLD = "Hello World!!!"

The texts constants here are used, respectively:
- in browser's window/tab title;
- as link in top menu;
- as a message in application screen.

And this is how js/views/MainView.js file looks like:

'use strict';
var
    _ = require('underscore'),
    ko = require('knockout'),
    TextUtils = require('%PathToCoreWebclientModule%/js/utils/Text.js'),
    CAbstractScreenView = require('%PathToCoreWebclientModule%/js/views/CAbstractScreenView.js')
;
/**
 * View that is used as screen of the module. Inherits from CAbstractScreenView that has showing and hiding methods.
 * 
 * @constructor
 */
function CMainView()
{
    CAbstractScreenView.call(this, '%ModuleName%');
    /**
     * Text for displaying in browser title.
     */
    this.browserTitle = ko.observable(TextUtils.i18n('%MODULENAME%/HEADING_BROWSER_TAB'));
}
_.extendOwn(CMainView.prototype, CAbstractScreenView.prototype);
CMainView.prototype.ViewTemplate = '%ModuleName%_MainView';
module.exports = new CMainView();

Though the code looks quite complex, its sole purpose is to display a screen using templates/MainView.html template:

<div class="screen" style="display: none;">
    <h1 data-bind="i18n: {'key': '%MODULENAME%/HEADING_HELLO_WORLD'}"></h1>
</div>

Now that we have all the files of our module in place, we need to let Aurora know about this new module. That's done by rebuilding static files as explained here. If you're logged in as Aurora user, you'll need to log out and back in to see the new application entry in top menu.

Once again, this sample app is available for download here.