16. Appendix A: Naming Conventions

16.1. Namespace Structure

The bulk of the code lives in client/zarafa, representing the Zarafa namespace.

  • Zarafa - the root namespace
    • core - the application core framework. Includes global models such as the folder hierarchy, the plugin, contexts, and widgets system, etc.
      • ui - UI components used in the core framework. Navigation panel, main viewport, etc.
      • dialog - core dialogs.
    • common - code that is common to all contexts and plugins.
      • ui - common UI components: value pickers, form panels.
      • dialog - dialogs used by multiple contexts.
    • [context] - context specific code, i.e. freebusy, mail, contact, etc.
      • ui - UI components used exclusively in this context.
    • dialog - context specific dialogs.
    • plugins - Zarafa standard plugins.
    • widgets - Zarafa standard widgets.

16.2. Naming Packages and Classes

Package names are lower case, except the top level Zarafa package. Class, method, and field names follow Java conventions; classes are camel case starting with a capital letter (i.e. CalendarMultiView, MailStore), methods and fields start with a lower case letter (i.e. getParentView(), load(), folderList).

The package/class structure follows the folder/file structure, much like with a Java project. For instance, Zarafa.calendar.ui.CalendarPanel can be found in zarafa/calendar/ui/CalendarPanel.js. Most complex classes will have their own file. Small/trivial classes that are used from only one place may be placed inside another class’s file.

16.3. Naming Insertion Points

Insertion points also follow a hierarchy. Top level:

  • Main application - main
  • Hierarchy panel - hierarchy
  • Contexts - context.[name], i.e. context.task, context.mail
  • Plug-ins - plugin.[name], i.e. plugin.folderstatus, plugin.sugarcrm
  • Widgets - widget.[name], i.e. widget.clock, widget.news

Common node types:

  • Dialog - dialog.[name], i.e. dialog.edit
  • Context menu - contextmenu
  • Tool bar - toolbar
  • Status bar - status

Most common insertion points’ names are of the following structure

{main|hierarchy|context.[context name]|plugin.[plugin name]|widget.[widget name]}.
{dialog.[dialog name]|contextmenu|toolbar|status}*

16.3.1. Coding Style Guidelines

In order to maintain consistency a few guidelines shall be followed in the WA projects.

Placement of brackets.

Function declarations shall always have brackets on a new line.

getModel : function()
{
        return this.model;
},

If-else statements shall use a condensed style.

if (item.isXType('zarafa.recipientfield'))
{
        item.setRecipientStore(record.getRecipients());
} else {
        item.setValue(value);
}

When an if-statement scope only consists of one row then the brackets should also be present.

if (!this.bodyInitialised)
{
        this.initBody();
}

Never use single line if-statements (WRONG).

if (!this.bodyInitialised) this.initBody();

For the ternary operator one line is ok.

iconClass = record.isRead() ? 'icon_mail_read' : 'icon_mail_unread';

It’s also highly recommended to use tabs instead of usual four spaces characters in indentation, as long as each developer can determine whether he wants his editor to show the appropriate number of spaces for each indentation of the code.

After the first character spaces are used.

16.3.2. Documentation

The application is documented using the ext-doc documentation tool provided by the Ext JS people. It allows documenting JavaScript code much like Javadoc or Doxygen. This section describes code is documented. Since Javascript is a very dynamic language it’s pretty much impossible to detect class, method, and field definitions, and the relationships between them. Therefore documentation is quite explicit. One has to declare classes, methods, and fields manually. This section briefly describes the most important aspects of documenting with ext-doc. Please refer to the ext-doc documentation wiki for more information.

16.4. Documenting Classes

A class is declared using the @class statement inside a /** */ multi-line comment. One can use @extends to indicate that the class is a subclass of another class. A description of the class follows these two statements. Optionally the @singleton statement can be used to declare the class a singleton. For classes which inherit directly or indirectly from Ext.Component, should use the @xtype to document which xtype can be used to automatically instantiate the object through the xtype. The constructor will be documented separately and is documented much like a method. Finally use @cfg to declare configuration options for this class. Note that parameters and configuration options are typed.

Plugin example:

/**
 * @class Zarafa.plugins.spreed.SpreedPlugin
 * @extends Zarafa.core.Plugin
 *
 * This class integrates Spreed plugin in existing system.
 * It allows user to setup spreed web meeting settings.
 */
Zarafa.plugins.spreed.SpreedPlugin = Ext.extend(Zarafa.core.Plugin, {
        //class code
}

16.5. Documenting Fields

Within a class configuration fields (which are configured using the config parameter in the constructor) must be added and documented. These fields must be documented using the @cfg within a /** */ multi-line comment.

Zarafa.plugins.spreed.SpreedPlugin = Ext.extend(Zarafa.core.Plugin, {

        /**
         * Contains link to the spreedStore class
         * initialized once when plugin is created.
         *
         * @property
         * @type Object
         * @private
         */
        spreedStore : null,

        /**
         * Unique id which works instead entryid
         * for SpreedRecord.
         *
         * @property
         * @type Integer
         * @private
         */
        sequenceId : 0,

        //code

});

16.6. Documenting Constructors

Constructors must be documented inside a /** */ multi-line comment. Use @constructor to mark the function as a constructor. Other than that the function is simly documented as a regular function. It is recommended, but not mandatory, to use // single-line comments (which will not be parsed for online documentation) to document configuration value overrides for the superclass.

/**
 * @constructor
 * @param {Object} config Configuration object
 *
 */
constructor : function (config)
{
        config = config || {};
        Ext.applyIf(config, {
                name : "spreed"
        });

        Zarafa.plugins.spreed.SpreedPlugin.superclass.constructor.call(this, config);
        this.init();
},

16.7. Documenting Methods

The following listing shows how to document methods. Parameters can be specified using @param with a type, name, and description. The method name will be extracted automatically, but if for any reason this fails, adding @method [name] will solve that. If an argument is an optional - one can make this explicitly by using (optional) as exemplified by the errorCallBack parameter. For method which are private, only visible for the own class, then @private annotation shall be added. Do not use the “old” way of describing private (private) in the method description and/or with one less * in the comment opening. If this old documenting format is found in the code base it shall be updated to use @private.

/**
 * Similar to {@link Ext.data.JsonWriter#toHash}
 *
 * Convert recipients into a hash. Recipients exists as
 * {@link Zarafa.core.data.IPMRecipientRecord IPMRecipientRecord} within
 * a {@link Zarafa.core.data.IPMRecord IPMRecord} and thus must be serialized
 * seperately into the hash object.
 *
 * @param {Ext.data.Record} record The record to hash
 * @return {Object} The hashed object
 * @override
 * @private
 */
toPropHash : function(record)
{
        //code
        return hash;
}

16.8. Documenting Insertion Points

Insertion points should be documented just after the class declaration. The name of the insertion point can be specified using @insert with a name of the insertion point. Parameters can be specified using @param with a type, name, and description.

For example, populating insertion point for new menu item:

Zarafa.core.ui.MainToolbar = Ext.extend(Zarafa.core.ui.Toolbar, {
        // Insertion points for this class
        /**
        * @insert main.maintoolbar.new.item
        * Insertion point for populating the "New item" menu. It will be placed in the item part of the
        * list. Each item inserted to this list is accessible from all contexts.
        * @param {Zarafa.core.ui.MainToolbar} toolbar This toolbar
        */

        ...

        //population of insertion point itself
        var itemMenu = container.populateInsertionPoint('main.maintoolbar.new.item', this) || [];

        ...
}

16.9. Documenting Enumerations

An example of documenting enumeration is Spreed Dialog types enumeration. An enumeration is declared using the @class statement inside a /** */ multi-line comment. One can use @extends to indicate that the enum extends Zarafa.core.Enum. A description of the class follows these two statements. Optionally the @singleton statement can be used to declare the class a singleton. Each property of the enum should be documented, telling what it means and what type it is.

/**
 * @class Zarafa.plugins.spreed.data.DialogTypes
 * @extends Zarafa.core.Enum
 *
 * Enum containing the different types of dialogs needed to display spreed meeting.
 * @singleton
 */
Zarafa.plugins.spreed.data.DialogTypes = Zarafa.core.Enum.create({

        /**
         * The dialog with empty fields.(Brandly new)
         *
         * @property
         * @type Number
         */
        EMPTY  : 1,

        /**
         * The dialog with filled subject and participants.
         *
         * @property
         * @type Number
         */
        FILLED : 2,


        /**
         * The dialog with only participants field prefilled.
         *
         * @property
         * @type Number
         */
        PARTICIPANTS_FILLED : 3

});