Contribution Acceptance Criteria

JavaScript files

Copyright header

All JavaScript source files should have the Alfresco copyright header with the year of the last edit, e.g:

/**
 * Copyright (C) 2005-2015 Alfresco Software Limited.
 *
 * This file is part of Alfresco
 *
 * Alfresco is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * Alfresco is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with Alfresco. If not, see <http://www.gnu.org/licenses/>.
 */

JSDoc

All JavaScript source files should include the correct JSDoc

Module should include:

• the path of the module as the @module tag
• description with example usage in @example tag
• appropriate @extends and @mixes tags
• appropriate @author tags
• a @since tag if the module is new for the new scheduled release

/**
 * <p>This should be used to stack widgets in a column. Each widget will be allocated 100% of the available width and
 * will consume as much vertical height as required. It is possible to space widgets by setting the 
 * [widgetMarginTop]{@link module:alfresco/layout/VerticalWidgets#widgetMarginTop} and
 * [widgetMarginBottom]{@link module:alfresco/layout/VerticalWidgets#widgetMarginBottom} attributes (but you should bear
 * in mind that if using both attributes then the gap between 2 widgets will be the <b>combination</b> of both values).</p>
 * @example <caption>Example configuration:</caption>
 * {
 *    "name": "alfresco/layout/VerticalWidgets",
 *    "config": {
 *       "widgetMarginTop": 10,
 *       "widgetMarginBottom": 10
 *       "widgets": [
 *          {
 *             "name": "alfresco/logo/Logo"
 *          },
 *          {
 *             "name": "alfresco/logo/Logo"
 *          }
 *       ]
 *    }
 * }
 * @module alfresco/layout/VerticalWidgets
 * @extends module:alfresco/core/ProcessWidgets
 * @author Dave Draper
 * @since 1.0.41
 */

Functions and attributes

• Every function and attribute should include the @instance tag
• Each attribute should include @type and @default tags (note that @default does not require a value for strings, booleans or null)
• Each function should include appropriate @param and @returns tags
• If the attribute or function is new it should have a @since tag for the next scheduled release

Attribute example:

/**
 * This is the size of margin (in pixels) that will appear to the right of every widget added. 
 *
 * @instance
 * @type {number}
 * @default
 * @since 1.0.41
 */

Function example:

/**
 * This function is based on the version that can be found in alfresco.js. It searches through all of
 * the available scopes for the widget and for all of the widgets inherited from.
 *
 * @instance
 * @param {string} p_messageId The id of the message to be displayed.
 * @returns {string} A localized form of the supplied message
 * @since 1.0.41
 */

Links

Where JSDoc refers to another module, it should be explicitly linked, e.g:

[VerticalWidgets]{@link module:alfresco/layout/VerticalWidgets}

Specific functions in modules should also be linked, e.g:

[widgetMarginBottom]{@link module:alfresco/layout/VerticalWidgets#widgetMarginBottom}

Publication and Subscription Topics

• New topics should be defined with an @event tag
• Functions that listen to topics (with alfSubscribe) should include an @listens tag
• Functions that publish a topic (with alfPublish) should include an @fires tag
• Topic String constants should be added to the alfresco/core/topics module with @event and relevant @property tags

New topic example:

/**
 * This topic is used to request that the browser displays a new page.
 *
 * @instance
 * @event navigateToPageTopic
 * @type {string}
 * @default "ALF_NAVIGATE_TO_PAGE"
 */
navigateToPageTopic: "ALF_NAVIGATE_TO_PAGE",

Topic subscription and publishing example:

* @listens module:alfresco/core/topics#DOCUMENTLIST_TAG_CHANGED
* @fires module:alfresco/core/topics#DISPLAY_NOTIFICATION

Attributes

• Attributes should be added alphabetically at the top of the module before the functions. Currently not all of the modules adhere to this rule, but we are in the process of updating them all. It is not necessary to re-order existing attributes - just don't give us any extra work to do! :-)

Functions

• Functions should be kept small.
• Functions should have a specific name including the module path and attribute to facilitate filtering via the LoggingService. A single underscore should delimit tokens in the path, a double underscore should delimit the attribute name mapped to the function, e.g:

allWidgetsProcessed: function alfresco_layout_VerticalWidgets__allWidgetsProcessed(widgets) {

Tabbing

Do not use the tab key, use spaces for tabs. The Alfresco convention is to use 3 spaces to represent a single tab width.

Closures

Try to avoid the use of closures where there may be an argument that the code inside the closure may want to be overridden by another module. Always consider that someone else may want to extend or customize your closure - use a lang.hitch instead.

Logging

Do not use console.log directly. Instead call this.alfLog (available when you mix-in the alfresco/core/Core module). You can pass a standard log level as the first argument, e.g:

this.alfLog("warn", "A widget was clicked but did not provide any information on how to handle the event", this);

CSS and i18n dependencies

Ensure that any CSS and i18n dependencies are referenced using the "cssRequirements" and "i18nRequirements" attributes (remember to only include CSS selectors and messages directly related to the widget or service in the referenced files), e.g:

/**
 * An array of the CSS files to use with this widget.
 *
 * @instance
 * @type {object[]}
 * @default [{cssFile:"./css/AlfButton.css"}]
 */
cssRequirements: [{cssFile:"./css/AlfButton.css"}],

/**
 * An array of the i18n files to use with this widget.
 *
 * @instance
 * @type {object[]}
 * @default [{i18nFile: "./i18n/AlfButton.properties"}]
 */
i18nRequirements: [{i18nFile: "./i18n/AlfButton.properties"}],

CSS files

Only include CSS selectors relevant to the associated widget or service. The root DOM element in the widget template should include a class that maps directly to the widget and all CSS selectors should be scoped to this class, e.g.

Template

<div class="alfresco-layout-ClassicWindow">
   <div class="titlebar" data-dojo-attach-point="titleBarNode">${title}</div>
   <div class="content" data-dojo-attach-point="contentNode"></div>
</div>

CSS file

.alfresco-layout-ClassicWindow > div.content {
   margin: 10px 0;
   padding: 10px;
}

LESS

Always use the common LESS variable in CSS for common styling (e.g. fonts, sizes, borders, colours, etc), e.g:

.alfresco-documentlibrary-AlfBreadcrumbTrail {
   margin-bottom: @standard-line-height;
   margin-top: @standard-line-height;
   margin-left: @standard-column-width;
   font-family: @bold-font;
   color: @general-font-color;
   font-size: @normal-font-size;
}

i18n files

Try to ensure that properties files are scoped by starting each property key with a value that maps directly to the widget or service.

Unit Tests

• All unit tests should pass against contributed code
• All contributed code should be submitted with an associated test. New modules will require a new test suite and changes to existing modules will require an update to the existing tests.
• New tests should provide at least 80% statement coverage (use the "vm-coverage-report" Grunt task to get a coverage score)
• Unit tests should follow approved best practices.