Merged release/v0.2.0-beta into master

Kocal · Sep 25, 2016 · 9927fef · 9927fef
2 parents 7dec32e + 39736b6
commit 9927fef
Show file tree

Hide file tree

Showing 17 changed files with 2,165 additions and 1,223 deletions.
diff --git a/.idea/django-tornado-websockets-client.iml b/.idea/django-tornado-websockets-client.iml
diff --git a/.jsdoc/static/styles/fixes.css b/.jsdoc/static/styles/fixes.css
@@ -0,0 +1,57 @@
+* {
+    -webkit-box-sizing: border-box;
+    -moz-box-sizing: border-box;
+    box-sizing: border-box;
+}
+
+a { color: royalblue }
+
+h1 { font-size: 36px }
+
+h2 { font-size: 30px }
+
+h3 { font-size: 24px }
+
+h4 { font-size: 18px }
+
+h5 { font-size: 14px }
+
+h6 { font-size: 12px }
+
+body {
+    display: flex;
+    flex-wrap: wrap;
+    margin: 0;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
+    font-size: 14px;
+    line-height: 1.5;
+    color: #333;
+    background-color: #fff;
+}
+
+/* positioning */
+#header,
+#footer {
+    padding: 8px 16px;
+    width: 100%;
+    background-color: rgba(0, 0, 0, .1);
+}
+
+#main { width: 75% }
+
+#aside {
+    padding: 0 8px;
+    width: 25%;
+    border-right: 1px solid #ccc;
+}
+
+#aside nav {
+    /* reset */
+    float: none;
+    padding-left: 0;
+    margin-top: 0;
+    width: auto;
+    border: 0;
+}
+
+#main pre { border: 2px solid rgba(0, 0, 0, .1) }
diff --git a/.jsdoc/tmpl/layout.tmpl b/.jsdoc/tmpl/layout.tmpl
@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>JSDoc: <?js= title ?></title>
+
+    <script src="scripts/prettify/prettify.js"></script>
+    <script src="scripts/prettify/lang-css.js"></script>
+    <!--[if lt IE 9]>
+    <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
+    <![endif]-->
+    <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
+    <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
+    <link type="text/css" rel="stylesheet" href="../../../.jsdoc/static/styles/fixes.css">
+</head>
+
+<body>
+
+<header id="header">
+    <h1 class="page-title"><?js= title ?></h1>
+</header>
+
+<aside id="aside">
+    <nav>
+        <?js= this.nav ?>
+    </nav>
+</aside>
+
+<main id="main">
+    <?js= content ?>
+</main>
+
+<footer id="footer">
+    Documentation generated by <a
+        href="https://github.com/jsdoc3/jsdoc">JSDoc <?js= env.version.number ?></a><?js if(env.conf.templates && env.conf.templates.default && env.conf.templates.default.includeDate !== false) { ?>
+    on <?js= (new Date()) ?><?js } ?>
+</footer>
+
+<script> prettyPrint(); </script>
+<script src="scripts/linenumber.js"></script>
+</body>
+</html>
diff --git a/README.md b/README.md
@@ -4,44 +4,153 @@
 [![Coverage Status](https://coveralls.io/repos/github/Kocal/dtws-client/badge.svg?branch=master)](https://coveralls.io/github/Kocal/dtws-client?branch=master)
 [![npm version](https://badge.fury.io/js/django-tornado-websockets-client.svg)](https://badge.fury.io/js/django-tornado-websockets-client)
 
-JavaScript's WebSocket wrapper for [django-tornado-websockets](https://github.com/Kocal/django-tornado-websockets) project, used as a submodule.
+JavaScript's WebSocket wrapper for [django-tornado-websockets](https://github.com/Kocal/django-tornado-websockets) 
+project, used as a submodule.
 
-## Documentation
-
-- Stable: http://django-tornado-websockets.readthedocs.io/en/stable/usage.html#using-websockets-client-side
-- Latest: http://django-tornado-websockets.readthedocs.io/en/latest/usage.html#using-websockets-client-side
-- Develop: http://django-tornado-websockets.readthedocs.io/en/develop/usage.html#using-websockets-client-side
+---
 
 ## Installation
 
-1. `$ git clone <...>`
-2. `$ npm install`
-3. `# npm -g gulp`
+```bash
+$ git clone https://github.com/Kocal/dtws-client.git
+$ npm i
+# npm -g gulp
+```
 
-## Running unit tests
+## Running examples
+Even if a non-ES6 version is available, examples are made with ES6 version of the project. So please, use a modern 
+browser.
 
-1. Setup your `django-tornado-websockets` WebSocket application and [run Tornado server](http://django-tornado-websockets.readthedocs.io/en/stable/usage.html#run-tornado-server),
-2. `$ npm test`.
+```bash
+python -m httpserver
+```
+Open your browser at <http://localhost:8000/examples> and profit.
 
-## Running examples
+## Running unit tests
+**The unit tests use a django-tornado-websocket application hosted on my own server, so if some tests about events 
+behavior are failing, it's perfectly fine!**
 
-Examples are made with ES2016, so use a modern browser please. :^)
+* Test ES6 version: `$ USE_ES6=true npm test`
+* Test non-ES6 version: `$ npm test`
 
-1. `cd examples`,
-2. `python -m SimpleHTTPServer 8000` or `php -S 0.0.0.0:8000`,
-3. Open your browser at http://localhost:8000 and profit.
+## How to use
 
-## Misc
+### Universal Module Definition
+The JavaScript class `TornadoWebSocket` and its modules are wrapped into the [UMD](https://github.com/umdjs/umd), by 
+using the [returnExports.js](https://github.com/umdjs/umd/blob/master/templates/returnExports.js) template. 
 
-### Gulp
+That's mean that you can use [AMD](https://en.wikipedia.org/wiki/Asynchronous_module_definition), 
+[CommonJS](https://en.wikipedia.org/wiki/CommonJS), or browser globals.
 
-To compile CoffeeScript:
+### Usage with [RequireJS](http://requirejs.org/)
 ```bash
-$ gulp scripts
+public
+├── index.html
+└── js
+    ├── main.js
+    ├── require.js
+    └── tws
+        ├── modules -> ../../../dist/modules
+        ├── tornadowebsocket-es6.js -> ../../../dist/tornadowebsocket-es6.js
+        └── tornadowebsocket.js -> ../../../dist/tornadowebsocket.js
 ```
 
-To watch CoffeeScript file and run « scripts » task:
-```bash
-$ gulp
+*index.html*
+```html
+<script src="js/require.js" data-main="js/main"></script>
+```
+
+*js/main.js*
+```javascript
+function main(TornadoWebSocket) {
+    var tws = new TornadoWebSocket(/* ... */)
+}
+
+// To load ES6 version
+require(['tws/tornadowebsocket-es6'], main)
+// To load non-ES6 version
+require(['tws/tornadowebsocket'], main)
+
+```
+
+### Usage with browser globals
+```
+public
+├── index.html
+└── js
+    ├── main.js
+    └── tws
+        ├── modules -> ../../../dist/modules
+        ├── tornadowebsocket-es6.js -> ../../../dist/tornadowebsocket-es6.js
+        └── tornadowebsocket.js -> ../../../dist/tornadowebsocket.js
+```
+
+*index.html*
+```html
+<script src="js/tws/tornadowebsocket-es6.js"></script>
+<!-- or -->
+<script src="js/tws/tornadowebsocket.js"></script>
+<script src="js/main.js"></script>
+```
+
+*js/main.js*
+```javascript
+var tws = new TornadoWebSocket(/* ... */)
+```
+
+### Using DTWS-client's Modules
+As said just before, this project comes with its own modules. 
+
+#### {@link ModuleProgressBar}
+This module helps to:
+- Communicate with the [Progress Bar server-side module](http://django-tornado-websockets.readthedocs.io/en/stable/modules.html#progress-bar), 
+- Handle the behavior of a progress bar (`init`, `update`, `done` events),
+- Render a progress bar by using HTML5 or Bootstrap rendering.
+
+*index.html*
+```html
+<!-- With RequireJS -->
+<script src="js/require.js" data-main="js/main"></script>
+
+<!-- With browser globals -->
+<script src="js/tws/tornadowebsocket-es6.js"></script>
+<script src="js/tws/modules/progress_bar-es6.js"></script>
+<script src="js/main.js"></script>
+```
+
+*js/main.js*
+```javascript
+function main(TornadoWebSocket, ModuleProgressBar) {
+    var tws = new TornadoWebSocket(/* ... */)
+    var progress = new ModuleProgressBar(/* ... */)
+
+    tws.bind(progress)
+}
+
+// With RequireJS (ES6 version)
+require(['tws/tornadowebsocket-es6', 'tws/modules/progress_bar-es6'], main)
+// With RequireJS (non-ES6 version)
+require(['tws/tornadowebsocket', 'tws/modules/progress_bar'], main)
+
+// With browser globals
+main(window.TornadoWebSocket, window.ModuleProgressBar)
 ```
-
+
+## npm scripts
+
+### doc
+Generate the API documentation with [JSDoc](http://usejsdoc.org).
+
+### test
+Run unit tests by using [Karma](https://karma-runner.github.io) and [Jasmine](http://jasmine.github.io).
+
+## gulp tasks
+
+### default
+Watch ES6 source files and run the `scripts` task.
+
+### scripts
+1. Glob ES6 source files,
+2. Use [ESLint](http://eslint.org/) on them,
+3. Distribute a ES6 version, 
+4. Run [Babel](https://babeljs.io/) on them and generate a non-ES6 version.