WebMail Pro documentation

Simple chat app example

This example demonstrates creating Aurora application to implement a simple chat, following the guidelines provided at Creating your apps page. The application includes one main module and two optional ones.

NB: This is an advanced example of building an application and using Aurora API, so before going through this article, be sure to check simple examples:

• Creating Hello World app
• Creating sample frontend module
• Creating sample backend module

SimpleChat module is available for download at:
https://github.com/afterlogic/aurora-module-simple-chat
Instructions on installing modules are found here.

For simplicity reasons, main module of the application includes both backend and frontend code - while in real-world applications, you might wish to separate the two.

Backend part of the module provides a set of Web API methods. Primary file of backend part is module.php. Functions it contains are listed below.

  • Public function init is optional, it is used for the following purposes:

    1. Initializing oApiChatManager manager which is declared in managers/manager.php file and used for working with the database via oEavManager. oEavManager is a manager for dealing with EAV data storage in the database, it is declared in our platform and can be used by any module.
    2. extending CUser object by adding EnableModule property. CUser object is declared in Core module and can be used by other modules when necessary.
      This particular function cannot be invoked via Web API.
  • If public function GetSettings is defined, result of its execution will be placed into window.auroraAppData object of web client created for the platform. This function can also be used via Web API. SimpleChat module holds EnableModule setting which is of per-user nature and can be altered by user, if their role is NormalUser at least.
    Roles currently supported, in ascending order of privileges, are as follows: Anonymous (user is not logged in, and cannot access any data or methods which require authentication), Customer, NormalUser, TenantAdmin, SuperAdmin.

  • UpdateSettings method is called via Web API to update EnableModule setting value. The function is available for NormalUser and higher roles.

  • GetPostsCount method is available over Web API for Customer and higher roles. Returns number of messages in the chat.

  • GetPosts method is available over Web API for Customer and higher roles. Returns chat messages, depending on offset and limit values supplied.

  • CreatePost method is available over Web API for NormalUser and higher roles. It means that users with Customer role participate chat in read-only mode.

Webclient part of the module deals with backend methods over Web API to create posts, obtain message list and edit module settings.

Primary webclient file of the module is js/manager.js, it contains the function which is executed once client is initialized, and returns list of methods available for use in other modules. Sets of methods may vary depending on user's role. In this case, we return sets of methods for users with NormalUser and Customer roles, while it doesn't return any methods for other users. It means that, if noone is logged in (user's role equals Anonymous), or if that's an administrator logged in, web client won't have any views available.

Files can be directly included only if they're found in their own module or in CoreWebclient module, for example:

var App = require('%PathToCoreWebclientModule%/js/App.js');
var Settings = require('modules/%ModuleName%/js/Settings.js');

Placeholders %PathToCoreWebclientModule% and %ModuleName% are replaced with corresponding value when JavaScript file is built with gulp tasks.

The module frontend provides the following methods for external use:

  • start method is executed in every module once application is initialized. While the method doesn't have to be present in a module, it's declared in js/views/SettingsPaneView.js file. Its purpose is registering settings screen.

  • getScreens module is called by Core module. For any module, it returns a list of screens the module provides. Those screens are opened upon clicking toolbar link or from the code. While the method is optional, it's present and returns infomation on a single screen described in `js/views/MainView.js`` file.

  • getHeaderItem is also called by Core module, that's done for all the modules that provide this method. It returns information on view model used to display a toolbar link. If the method is unavailable, screens listed via getScreens method will be opened in some different way from the code.

SimpleChatLoggerPlugin backend module
https://github.com/afterlogic/aurora-module-simple-chat-logger-plugin

This is a backend module created as an example of subscribing to another module's events and triggering specific actions depending on an event. module.php file of SimpleChatLoggerPlugin contains the functions listed below.

  • Within init function, we subscribe to SimpleChat::CreatePost::after event triggered upon using CreatePost method of SimpleChat module. For all the methods available via Web API, before and after events are automatically generated, developers can subscribe to those events and perform custom actions depending on an event.
    This particular function cannot be invoked via Web API.

  • afterCreatePost method is executed upon creating a post in SimpleChat module and appends data for this new post to a log file.
    The method cannot be used via Web API, just like all the other methods used as callback functions in terms of subscribeEvent method.

SimpleChatEmojiWebclientPlugin web client module
https://github.com/afterlogic/aurora-module-webclient-simple-chat-emoji-plugin

This is a web client module created as an example of subscribing to events of another module and triggering specific actions depending on an event. File Manager.js of this module provides just one function start subscribed to SimpleChat::DisplayPost::before event. The event is generated by SimpleChat module prior to calling DisplayPost method.

start function of SimpleChatEmojiWebclientPlugin module amends message text before it is displayed, replacing :) character sequences with emoticon.