networking documentation. Fixes #111

garysoed · Aug 24, 2015 · c98529c · c98529c
1 parent 5fe7c30
commit c98529c
Show file tree

Hide file tree

Showing 20 changed files with 266 additions and 147 deletions.
diff --git a/karma.conf.js b/karma.conf.js
@@ -7,5 +7,6 @@ module.exports = function(config) {
   var configObj = JSON.parse(JSON.stringify(base));
   configObj.basePath = '.';
   configObj.files.push({ pattern: 'out/**/*_test.html', included: true });
+  configObj.files.push({ pattern: 'out/**/*_testsuite.html', included: false });
   config.set(configObj);
 };
diff --git a/min/third_party/di-js/out/bin.js b/min/third_party/di-js/out/bin.js
diff --git a/out/main.html b/out/main.html
@@ -5,7 +5,5 @@
 
 <script>"use strict";
 
-Protoboard.run(function (require) {
-  return require("pb.Bootstrap").run(document);
-});</script>
+Protoboard.run(document);</script>
 </head><body></body></html>
diff --git a/out/protoboard.html b/out/protoboard.html
@@ -103,10 +103,7 @@
               }).then(function (gameData) {
                 TemplateService.addData("pb.playerCount", gameData.playerCount);
                 TemplateService.addData("pb.players", gameData.players);
-
-                for (var stateKey in gameData.state) {
-                  TemplateService.addData("pb." + stateKey, gameData.state[stateKey]);
-                }
+                TemplateService.addData("pb.state", gameData.state);
                 return gameData;
               }).then(function (gameData) {
                 return Promise.all([gameData, Promise.resolve(_this[__setupFn__] ? _this[__setupFn__](require) : null)]);
@@ -175,16 +172,24 @@
           return this;
         }
       },
+      forExistingGame: {
+        value: function forExistingGame(gameId) {
+          return Runner.forExistingGame(this[__io__], gameId);
+        }
+      },
       forNewGame: {
-        value: function forNewGame(playerCount) {
+        value: function forNewGame() {
+          var playerCount = arguments[0] === undefined ? 0 : arguments[0];
           var initialGameState = arguments[1] === undefined ? {} : arguments[1];
 
           return Runner.forNewGame(this[__io__], playerCount, initialGameState);
         }
       },
-      forExistingGame: {
-        value: function forExistingGame(gameId) {
-          return Runner.forExistingGame(this[__io__], gameId);
+      run: {
+        value: function run() {
+          var doc = arguments[0] === undefined ? document : arguments[0];
+
+          return this.forNewGame().run(doc);
         }
       }
     });

diff --git a/src/main.html b/src/main.html
@@ -4,5 +4,5 @@
 <link rel="import" href="third_party/di.html">
 
 <script>
-  Protoboard.run(require => require('pb.Bootstrap').run(document));
+  Protoboard.run(document);
 </script>
diff --git a/src/net/localstorageio.html b/src/net/localstorageio.html
@@ -25,7 +25,7 @@
      * Implementation of net.AbstractIO that stores data in local store.
      *
      * @constructor
-     * @class net.InMemoryIO
+     * @class net.LocalStorageIO
      * @param {Storage} [localStorage] The LocalStorage object. Defaults to window.localStorage.
      * @extends net.AbstractIO
      */

diff --git a/src/protoboard.html b/src/protoboard.html
@@ -14,6 +14,11 @@
   const __players__ = Symbol();
   const __setupFn__ = Symbol();
 
+  /**
+   * Runs the Protoboard game.
+   *
+   * @class Protoboard.Runner
+   */
   class Runner {
 
     /**
@@ -58,7 +63,16 @@
     }
 
     /**
-     * Runs the game on the given document object.
+     * Runs the game on the given document object. Also makes available the following variables to
+     * the templating system:
+     *
+     * -   `pb.playerCount`: Contains number of players in the game.
+     * -   `pb.players`: Array of player objects. Each player object is an object with:
+     *
+     *     -   id: ID of the player
+     *     -   state: The player's state
+     *
+     * -   `pb.state`: Contains the game state object.
      *
      * @method run
      * @param {Document} [doc] Document to run the game on. Defaults to the root document.
@@ -98,10 +112,7 @@
                     // Initialize the templates.
                     TemplateService.addData('pb.playerCount', gameData.playerCount);
                     TemplateService.addData('pb.players', gameData.players);
-
-                    for (let stateKey in gameData.state) {
-                      TemplateService.addData(`pb.${stateKey}`, gameData.state[stateKey]);
-                    }
+                    TemplateService.addData('pb.state', gameData.state);
                     return gameData;
                   })
                   .then(gameData => {
@@ -193,27 +204,40 @@
       return this;
     }
 
+    /**
+     * Creates a game based on an existing game.
+     *
+     * @method forExistingGame
+     * @param {string} gameId ID of game to use.
+     * @return {Protoboard.Runner} The runner object.
+     */
+    forExistingGame(gameId) {
+      return Runner.forExistingGame(this[__io__], gameId);
+    }
+
     /**
      * Creates a new game.
      *
      * @method forNewGame
-     * @param {number} playerCount Number of players that the game should have before starting.
+     * @param {number} [playerCount] Number of players that the game should have before starting.
+     *    Defaults to 0.
      * @param {Object} [initialGameState] The initial state of the game. Defaults to empty string.
      * @return {Protoboard.Runner} The runner object.
      */
-    forNewGame(playerCount, initialGameState = {}) {
+    forNewGame(playerCount = 0, initialGameState = {}) {
       return Runner.forNewGame(this[__io__], playerCount, initialGameState);
     }
 
     /**
-     * Creates a game based on an existing game.
+     * Runs Protoboard game with default settings.
      *
-     * @method forExistingGame
-     * @param {string} gameId ID of game to use.
-     * @return {Protoboard.Runner} The runner object.
+     * @method run
+     * @param {Document} doc = document The Document to run the game in.
+     * @return {Promise} Promise that will be resolved with a function when the game has started.
+     *    Use this function to retrieve Protoboard classes.
      */
-    forExistingGame(gameId) {
-      return Runner.forExistingGame(this[__io__], gameId);
+    run(doc = document) {
+      return this.forNewGame().run(doc);
     }
   }
 

diff --git a/test/net/karma.conf.js b/test/net/karma.conf.js
@@ -7,6 +7,6 @@ module.exports = function(config) {
   var configObj = JSON.parse(JSON.stringify(base));
   configObj.basePath = '../..';
   configObj.files.push({ pattern: 'out/net/*_test.html', included: true });
-  configObj.files.push({ pattern: 'out/net/*_testsuite.html', included: true });
+  configObj.files.push({ pattern: 'out/net/*_testsuite.html', included: false });
   config.set(configObj);
 };
diff --git a/test/net/session_test.html b/test/net/session_test.html
@@ -88,7 +88,7 @@
             })
             .then(playersData => {
               expect(playersData[0]).to.eql({
-                name: 'Player Name',
+                id: 'Player Name',
                 state: {
                   role: 'Medic'
                 }

diff --git a/test/protoboard_test.html b/test/protoboard_test.html
@@ -62,12 +62,12 @@
               Rpc.get('/(root)'),
               TemplateService.get('pb.playerCount'),
               TemplateService.get('pb.players'),
-              TemplateService.get('pb.randomSeed')
+              TemplateService.get('pb.state')
             ]);
           })
           .then(values => {
             let [require, root, ...templateData] = values;
-            let [templatePlayerCount, templatePlayers, templateRandomSeed] = templateData;
+            let [templatePlayerCount, templatePlayers, templateState] = templateData;
             const StateService = require('pb.service.State');
             const TemplateService = require('pb.service.Template');
 
@@ -102,7 +102,7 @@
 
             expect(templatePlayerCount).to.eql(['pb.playerCount', 2]);
             expect(templatePlayers).to.eql(['pb.players', expectedPlayers]);
-            expect(templateRandomSeed).to.eql(['pb.randomSeed', 1234]);
+            expect(templateState).to.eql(['pb.state', { randomSeed: 1234 }]);
           });
     });
     it('should correctly setup for existing game', () => {
@@ -133,12 +133,12 @@
                 Rpc.get('/(root)'),
                 TemplateService.get('pb.playerCount'),
                 TemplateService.get('pb.players'),
-                TemplateService.get('pb.randomSeed')
+                TemplateService.get('pb.state')
               ]);
             })
             .then(values => {
               let [require, root, ...templateData] = values;
-              let [templatePlayerCount, templatePlayers, templateRandomSeed] = templateData;
+              let [templatePlayerCount, templatePlayers, templateState] = templateData;
               const StateService = require('pb.service.State');
               const TemplateService = require('pb.service.Template');
 
@@ -173,7 +173,7 @@
 
               expect(templatePlayerCount).to.eql(['pb.playerCount', 2]);
               expect(templatePlayers).to.eql(['pb.players', expectedPlayers]);
-              expect(templateRandomSeed).to.eql(['pb.randomSeed', 1234]);
+              expect(templateState).to.eql(['pb.state', { randomSeed: 1234 }]);
             });
       });
     });

diff --git a/tutorial/01_overview.js b/tutorial/01_overview.js
@@ -4,11 +4,15 @@
  * components. Aesthetics, performance, and correctness are outside the scope of this project,
  * though we do provide some basic support for theming.
  *
- * This aims to be customizable in different levels:
- * 1. JavaScript: Provides JavaScript API to make boardgame components easier (coming soon)
- * 2. HTML: Developers can use preexisting HTML elements to write their own game.
- * 3. {{#crossLink "5 Theming"}}Theme{{/crossLink}}: This library comes with some existing themes. You
- * can customize the color themes, and if you use CSS, you can customize in greater details.
+ * This tutorial will go through some concepts and how-tos for using Protoboard. It is recommended
+ * that you read the tutorials in the order that they are presented.
+ *
+ * Protoboard aims to be customizable in different levels:
+ *
+ * 1.  JavaScript: Provides JavaScript API to make boardgame components easier (coming soon)
+ * 1.  HTML: Developers can use preexisting HTML elements to write their own game.
+ * 1.  {{#crossLink "05 Theming"}}Theme{{/crossLink}}: This library comes with some existing themes.
+ *     You can customize the color themes, and if you use CSS, you can customize in greater details.
  *
  * Some glossary of terminologies for the API:
  * {{#html 'dl'}}
@@ -38,13 +42,16 @@
  * {{/html}}
  *
  * Every element introduced in Protoboard has 3 parts of its name:
- * 1. `pb-` is the prefix of every Protoboard element.
- * 2. The second prefix indicates the type of element:
- *    - `pb-c-` indicates a component
- *    - `pb-r-` indicates a region
- *    - `pb-u-` indicates a UI element.
- * 3. The last part is the name of the element.
- *
- * @class 1 Overview
+ *
+ * 1.  `pb-` is the prefix of every Protoboard element.
+ * 1.  The second prefix indicates the type of element:
+ *     -   `pb-c-` indicates a component
+ *     -   `pb-r-` indicates a region
+ *     -   `pb-u-` indicates a UI element.
+ * 1.  The last part is the name of the element.
+ *
+ * You can use the above to figure out the corresponding API.
+ *
+ * @class 01 Overview
  * @module tutorial
  */
diff --git a/tutorial/02_prerequisites.js b/tutorial/02_prerequisites.js
@@ -1,17 +1,19 @@
 /**
  * 1. Install [NPM](https://www.npmjs.com/).
- * 2. Unpack the binary in the directory, or install using [bower](http://bower.io/):
+ * 1. Unpack the binary in the directory, or install using [bower](http://bower.io/):
+ *
  *    ```
  *    bower install --save protoboard
  *    ```
- * 3. Protoboard relies on
+ *
+ * 1. Protoboard relies on
  *    [HTML Import](http://www.html5rocks.com/en/tutorials/webcomponents/imports/). So you will need
  *    an HTTP server serving static files. A simple one you can use is
  *    [http-server](https://www.npmjs.com/package/http-server):
  *    `npm install http-server`.
- * 4. Run `http-server` from the root directory of the project, and navigate to the file you want to
+ * 1. Run `http-server` from the root directory of the project, and navigate to the file you want to
  *    open. A good one to start is `ex/all/index.html`.
  *
- * @class 2 Prerequisites
+ * @class 02 Prerequisites
  * @module tutorial
- */
+ */
diff --git a/tutorial/03_basic.js b/tutorial/03_basic.js
@@ -1,31 +1,36 @@
 /**
  * To use this library, you will need to write an HTML file. You will need to do the following:
- * 1. Add the following code to the `<head>` block of the document:
- *    ```html
- *    <link rel="import" href="path/to/protoboard/out/main.html">
- *    ```
- * 2. Add custom elements in the body. Be sure to import the appropriate files in the `<head>`
- *    block. For example, to add a token:
- *    ```html
- *    <head>
- *      <!-- Required -->
- *      <link rel="import" href="path/to/out/di.html">
- *      <link rel="import" href="path/to/out/bootstrap.html">
- *
- *      <!-- Import token -->
- *      <link rel="import" href="path/to/out/component/token.html">
- *
- *      <!-- This should always come last -->
- *      <link rel="import" href="path/to/protoboard/out/main.html">
- *    </head>
- *
- *    <body>
- *      <pb-c-token>
- *        <div>Token Content</div>
- *      </pb-c-token>
- *    </body>
- *    ```
- *    Make sure that all dependencies are ABOVE the `main.html` import.
+ *
+ * 1.  Add the following code to the `<head>` block of the document:
+ *
+ *     ```html
+ *     <link rel="import" href="path/to/protoboard/out/main.html">
+ *     ```
+ *
+ * 1.  Add custom elements in the body. Be sure to import the appropriate files in the `<head>`
+ *     block. For example, to add a token:
+ *
+ *     ```html
+ *     <head>
+ *       <!-- Required -->
+ *       <link rel="import" href="path/to/out/di.html">
+ *       <link rel="import" href="path/to/out/bootstrap.html">
+ *
+ *       <!-- Import token -->
+ *       <link rel="import" href="path/to/out/component/token.html">
+ *
+ *       <!-- This should always come last -->
+ *       <link rel="import" href="path/to/protoboard/out/main.html">
+ *     </head>
+ *
+ *     <body>
+ *       <pb-c-token>
+ *         <div>Token Content</div>
+ *       </pb-c-token>
+ *     </body>
+ *     ```
+ *
+ *     Make sure that all dependencies are ABOVE the `main.html` import.
  *
  * To help with debugging for missing imports, you can open the developer tools (Alt + &#8984; for
  * Chrome on Mac) and check the Console tab. It should tell you elements which are missing imports.
@@ -36,8 +41,9 @@
  * examples on how to use every element. You can also play around with every element on that page.
  *
  * Some example projects:
- * - [Chess](https://github.com/garysoed/protoboard-chess)
  *
- * @class 3 Basic Usage
+ * -   [Chess](https://github.com/garysoed/protoboard-chess)
+ *
+ * @class 03 Basic Usage
  * @module tutorial
- */
+ */