Merge pull request #4 from studentIvan/dev

1.2.0 release

.gitignore

@@ -1,2 +1,3 @@
 .idea
 node_modules
+npm_debug.log

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014 Maslov Ivan
+Copyright (c) 2015 Maslov Ivan
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,8 +1,19 @@
-DuelJS v1.1.0
+DuelJS v1.2.0
 ======
+[![Documentation Status](https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat-square)](http://dueljs.readthedocs.org/) [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://raw.githubusercontent.com/studentIvan/dueljs/master/LICENSE) [![Bower](https://img.shields.io/bower/v/duel.svg?style=flat-square)](http://bower.io/search/?q=duel) [![](https://img.shields.io/github/issues-raw/studentIvan/dueljs.svg?style=flat-square)](https://github.com/studentIvan/dueljs/issues/) [![GitHub stars](https://img.shields.io/github/stars/studentIvan/dueljs.svg?style=flat-square)](https://github.com/studentIvan/dueljs/stargazers)
+
 JavaScript HTML5 Master/Slave Browser Tabs Helper.
 
-See a brief documentation on the [the homepage](http://dueljs.studentivan.ru)
+See a brief look on [the homepage](http://dueljs.studentivan.ru)
+
+Documentation available on http://dueljs.readthedocs.org/
+
+######New in 1.2.0:
+* New method: channel.off - stop watching event
+* New method: channel.once - executing callback only one time and stop watching event
+* New method: channel.emit - the alias of channel.broadcast
+* Function window.isMaster() now returns true even if no one channel has initialized [#3](https://github.com/studentIvan/dueljs/issues/3)
+* Dev test coverage (Mocha + PhantomJS)
 
 ######New in 1.1.0:
 * "storage" event improves performance in modern browsers.

bower.json

@@ -1,6 +1,6 @@
 {
   "name": "duel",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "homepage": "http://dueljs.studentivan.ru",
   "authors": [
     "Maslov Ivan <[email protected]>"
@@ -21,6 +21,8 @@
   "license": "MIT",
   "ignore": [
     "node_modules",
-    "bower_components"
+    "bower_components",
+    "docs",
+    "test"
   ]
 }

docs/api.rst

@@ -0,0 +1,126 @@
+API:duel
+========
+
+duel
+----
+Main global object.
+
+* global
+* type: object
+
+duel.activeChannels
+-------------------
+Collect inside all active channels.
+
+* public
+* type: array
+* default: []
+
+duel.useStorageEvent
+--------------------
+Optional configuration. Storage event improves performance in modern browsers.
+
+* public
+* type: boolean
+* default: true (IE - false)
+
+duel.isLocalStorageAvailable()
+------------------------------
+Common function for localStorage detection.
+
+* public
+* type: function
+* returns: boolean
+
+duel.channel(name:string)
+-------------------------
+Creates a new channel or join to existed.
+Hint: a = duel.channel('x') and b = duel.channel('x') will be linking on ONE object.
+
+* public
+* type: function
+* returns: object (duel.DuelAbstractChannel inheritor)
+
+duel.makeCurrentWindowMaster()
+------------------------------
+Take the all channels in current window and set current window as master for all of them.
+
+* public
+* type: function
+
+duel.clone(obj:object)
+----------------------
+Common function for copy objects.
+
+* public
+* type: function
+* returns: object
+* throws error on unsupported type
+
+duel._generateWindowID()
+------------------------
+Generates, sets up and returns new window/tab ID.
+
+* private
+* type: function
+* returns: number
+
+duel.getWindowID()
+------------------
+Get unique window/tab ID.
+
+* public
+* type: function
+* returns: number
+
+duel.addEvent(el:object, type:string, fn:function)
+--------------------------------------------------
+Cross-browser addEvent method.
+
+* public
+* type: function
+
+duel.storageEvent(event:object)
+-------------------------------
+Finds the specific channel and execute event on it. **event** object contains **key:string** and **newValue:string**.
+**newValue** is a JSON string, which contains **channelName:string** and **triggerDetails:object**.
+**triggerDetails** contains **name:string** and **args:array**.
+
+* public
+* type: function
+
+duel.DuelAbstractChannel
+------------------------
+Abstract class for possible duel channels. DuelJS probably will support another channels besides **duel.DuelLocalStorageChannel** in future.
+
+* abstract
+* type: function
+* returns: object
+
+duel.DuelLocalStorageChannel
+----------------------------
+Channel class for work with localStorage.
+
+* abstract
+* type: function
+* returns: object
+
+duel.DuelFakeChannel
+--------------------
+Channel class for work without localStorage.
+
+* abstract
+* type: function
+* returns: object
+
+window.isMaster()
+-----------------
+Take first channel in current window and check is it master or not
+
+Standard window object spreading method.
+Looks like syntax sugar for channelObject.currentWindowIsMaster()
+
+* public
+* type: function
+* returns: boolean
+

docs/channel_api.rst

@@ -0,0 +1,74 @@
+API:channel object interface
+============================
+
+channel.getName()
+-----------------
+Returns the name of this channel.
+
+* public
+* type: function
+* returns: string
+
+channel.setCurrentWindowAsMaster()
+----------------------------------
+Makes current window/tab as master in this channel.
+
+* public
+* type: function
+* returns: boolean
+
+channel.currentWindowIsMaster()
+-------------------------------
+Checks the master state of this channel.
+
+* public
+* type: function
+* returns: boolean
+
+channel.broadcast(trigger:string[, arguments:arguments])
+--------------------------------------------------------
+Emits broadcasting. Hint: only master can sends broadcast.
+
+* public
+* type: function
+
+channel.emit(trigger:string[, arguments:arguments])
+---------------------------------------------------
+Alias of **channel.broadcast**
+
+channel.executeTrigger(triggerDetails:object[, force:boolean])
+--------------------------------------------------------------
+Executes pointed trigger. **triggerDetails** contains **name:string** and **args:array**
+
+* public
+* type: function
+* throws error if triggerDetails is not an instance of Object
+
+channel.on(trigger:string, callback:function)
+---------------------------------------------
+Attaches callback to trigger event.
+
+* public
+* type: function
+
+channel.once(trigger:string, callback:function)
+-----------------------------------------------
+Attaches callback to trigger event only for one time.
+
+* public
+* type: function
+
+channel.off(trigger:string)
+---------------------------
+Detaches callback from trigger event (destroys trigger).
+
+* public
+* type: function
+
+channel._triggers
+-----------------
+Contains triggers of this channel.
+
+* private
+* type: object
+

docs/getting_started.rst

@@ -0,0 +1,71 @@
+Getting Started
+===============
+
+Getting started with DuelJS.
+
+Requirements
+------------
+
+With DuelJS you no need to any requirements - only vanilla js and modern web browser.
+Don't try to use it with node.js without browser emulators.
+
+Installing DuelJS
+-----------------
+
+You can install it using bower or simple copy duel.js main file into your site or even clone git repository.
+
+Different ways:
+
+* Bower package: ``bower install duel --save``
+* Git repo: ``git clone https://github.com/studentIvan/dueljs.git``
+* Main file: `duel.min.js <https://github.com/studentIvan/dueljs/blob/master/public/lib/duel.min.js>`_
+
+
+Put it into your webpage:
+``<script type="text/javascript" src="path/to/duel.min.js"></script>``
+
+So we've got all the set up out of the way. Let's write some simple code.
+::
+    <script type="text/javascript">
+    var channel = duel.channel('my_first_channel');
+    // now you have opened some channel, this tab is connected to it
+
+    setInterval(function () {
+        if (channel.currentWindowIsMaster()) {
+            // here you checking is this tab active (in focus) or not
+            // you can use alternative syntax: if (window.isMaster()) { ...
+
+            document.title = 'Master ' + duel.getWindowID();
+            // duel.getWindowID returns a unique browser tab id
+
+        } else {
+            document.title = 'Slave ' + duel.getWindowID();
+        }
+    }, 100);
+    </script>
+
+Broadcasting
+------------
+
+When your tab had some channel (e.g. **my_first_channel** from previous section) you can do cross-tab broadcasting.
+
+Use simple commands:
+
+* **channel.broadcast('event_name', a,r,g,u,m,e,n,t,s...);**
+    - send event command to all another tabs in channel. Alias: **channel.emit**.
+* **channel.on('event_name', function (a,r,g,u,m,e,n,t,s...) { do here what you want });**
+    - define watcher for event_name.
+* **channel.off('event_name');**
+    - remove event_name watcher.
+* **channel.once('event_name', function (a,r,g,u,m,e,n,t,s...) { do here what you want });**
+    - define watcher for event_name, do it only one time and remove.
+
+Articles and examples
+---------------------
+
+* `Задача коммуникации между вкладками и выявления активной вкладки <http://habrahabr.ru/post/247739/>`_ (russian)
+* `Youtube-player integration demonstration <http://dueljs.studentivan.ru/youtube_player_example/>`_ (russian)
+
+If you still need more docs go to `API`_ section
+
+.. _API: api.html

docs/index.rst

@@ -0,0 +1,18 @@
+DuelJS Documentation
+====================
+
+.. note:: Documentation still in progress.
+Welcome to the DuelJS JavaScript library documentation.
+
+.. _site-docs:
+
+User Documentation
+------------------
+
+.. toctree::
+    :maxdepth: 2
+
+    getting_started
+    api
+    channel_api
+

package.json

@@ -1,14 +1,17 @@
 {
   "name": "duel",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "DuelJS - JavaScript HTML5 Master/Slave Browser Tabs Helper",
   "main": "public/lib/duel.js",
   "devDependencies": {
-    "http-server": "^0.6.1"
+    "chai": "^1.10.0",
+    "mocha": "^2.1.0",
+    "mocha-phantomjs": "^3.5.3",
+    "phantomjs": "^1.9.13"
   },
   "scripts": {
-    "pretest": "npm install",
-    "test": "http-server -a 0.0.0.0 -p 8624 -c-1"
+    "pretest": "npm install && mocha-phantomjs test/mocha.test.html",
+    "test": "phantomjs test/phantom.script.js"
   },
   "repository": {
     "type": "git",

public/index.html

@@ -5,7 +5,7 @@
     <title>Duel page</title>
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <link rel="stylesheet" href="//yastatic.net/bootstrap/3.3.1/css/bootstrap.min.css">
-    <script type="text/javascript" src="lib/duel.min.js"></script>
+    <script type="text/javascript" src="lib/duel.js"></script>
 </head>
 <body>
 <div class="container-fluid">