diff --git a/js/README.md b/js/README.md index b10756475..24bab33b1 100644 --- a/js/README.md +++ b/js/README.md @@ -17,3 +17,63 @@ inside the project's root directory. This combines and compresses all used JavaS files into one file: ``js/mail.min.js``. If [debug mode](https://doc.owncloud.org/server/8.2/developer_manual/general/devenv.html#enabling-debug-mode) is disabled, this compressed file is then used. +## Coding guidelines + +Generally, any code contributed to this repository should comply with the general [ownCloud coding style guidelines](https://doc.owncloud.org/server/9.0/developer_manual/general/codingguidelines.html). + +Currently we use several frameworks and their extensions. Namely, this app is build with jQuery, Underscore.js, Backbone.js and Backbone Marionette. Additionally, Require.js is used for loading module dependencies (code and template). + +The client-side software is structured as [Model-View-Controller application](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller). + +### Modules +Since Require.js is used for loading module dependencies, all code (Model, View, Controller, Service, Templates) are structured as modules. A typical module looks like this: +```js +define(function(require) { + 'use strict'; + + // get any other dependencies + var Backbone = require('backbone'); + + // create module here + var MessageFlag = Backbone.Model.extend{ + defaults: { + name: '', + value: false + }, + doSomethingUseful: function(param1) { + // Something useful + } + }; + + // return the module + return MessageFlag; +}); +``` + +Since this is a model, it would be stored to ``js/model/messageflag.js``. Any other module that depends on that module can require it with ``require('model/messageflag')``. + +For controllers, services and any other module that is used as singleton, the 'revealing module pattern' is used. There are many tutorials on the internet that explain how it works and what it's advantages are. + +### Models +All models should be Backbone models. Usually this means you create models by extending ``Backbone.Model``: +```js +define(function(require) { + 'use strict'; + + return Backbone.Model.extend({ + foo: 13, + bar: function(input) { + return input * 2; + } + }); +}); +``` + +### Views +TODO + +### Controller +TODO + +### Templates +TODO