Merge pull request #678 from wpreul/feature/readme

Updating tutorials and adding a plugins list doc

README.md

@@ -19,6 +19,8 @@ Current version: **0.16.0**
 
 ### [Tutorials](/docs/Tutorials.md)
 
+### [Plugins](/docs/Plugins.md)
+
 ### [Breaking Changes](https://github.com/spumko/hapi/issues?labels=breaking+changes&state=closed)
 
 ## Getting started

docs/Plugins.md

@@ -0,0 +1,18 @@
+# Hapi Plugins
+
+***Create a [pull request](http://help.github.com/send-pull-requests/) to add a plugin to the list.***
+
+## Security
+
+#### [Crumb](https://npmjs.org/package/crumb) - CSRF crumb generation
+
+#### [Travelogue](https://npmjs.org/package/travelogue) - Passport.js integration helper
+
+#### [Yar](https://npmjs.org/package/yar) - Cookie jar
+
+
+## Monitoring
+
+#### [Good](https://npmjs.org/package/good) - Server and process monitoring
+
+#### [Hapi-Helmet](https://npmjs.org/package/hapi-helmet) - Debug console for request monitoring  

docs/Tutorials.md

@@ -5,6 +5,8 @@
 1. Hapi version 0.15.x or greater is installed
 2. A folder with a package.json and main entry point file exist (index.js)
 
+Please read the reference guide for an overview of creating the [plugin structure](docs/Reference.md#creating-a-plugin).
+
 ### Creating an API
 
 A plugin always has the ability to add properties and methods to the _'api'_ object.  This object is useful for exposing any functionality publically.  This tutorial will demonstrate how to add a function and property to this object.
@@ -55,13 +57,7 @@ When a pack allows the _'route'_ permission then any plugin within the pack can
 exports.register = function (pack, options, next)
 ```
 
-Next, make sure that the _'pack'_ allows for the plugin to add routes by checking that _'pack.route'_ is a function.
-
-```javascript
-console.assert(typeof pack.route === 'function', 'Plugin permissions must allow route');
-```
-
-If the _'pack'_ allows the route permission then go ahead and add a new route and then call _'next'_.
+Next call _'route'_ and then call _'next'_.
 
 ```javascript
 pack.route({ method: 'GET', path: '/', handler: function (request) {
@@ -71,16 +67,71 @@ pack.route({ method: 'GET', path: '/', handler: function (request) {
 next();
 ```
 
+In the event that a pack doesn't grant the _'route'_ permission an exception will be thrown.  Therefore, there isn't a need to check first for this function unless the plugin will work without it.
+
 Below is what the final plugin looks like:
 
 ```javascript
 exports.register = function (pack, options, next) {
-
-  console.assert(typeof pack.route === 'function', 'Plugin permissions must allow route');
+
   pack.route({ method: 'GET', path: '/', handler: function (request) {
 
     request.reply('Hello Plugins');
   }});
   next();
 };
 ```
+
+### Plugging into a Subset of Servers
+
+The _'register'_ method for a plugin is passed a _'pack'_ object.  This object has a _'select'_ method that returns a pack of servers that match the provided criteria.  In the following, all of the servers that support TLS will be selected and a route will be added to them.
+
+Begin by exporting the _'register'_ function within the module.
+
+```javascript
+exports.register = function (pack, options, next)
+```
+
+Now call the _'select'_ method on _'pack'_ and look for the pack of servers that have the 'secure' label.
+
+```javascript
+var securePack = pack.select({ label: 'secure' });
+```
+
+The result of calling _'select'_ will be a subset package of any server that match the criteria.  The result will have the same methods that existed on the original _'pack'_ object passed in.
+
+Before calling any of the methods on _'securePack'_ check to make sure that any servers were found that meet the criteria by checking _'length'_.
+
+```javascript
+if (!securePack.length) {
+    return next(new Error('No secure servers found'));   
+}
+```
+
+Finally add a route that is now guranteed to be applied to only servers that support TLS.
+
+```javascript
+securePack.route({ method: 'GET', path: '/', handler: function (request) {
+
+    request.reply('Hello Secure Server');
+}});
+```
+
+The complete plugin _'register'_ function is shown below, including the call of _'next'_.
+
+```javascript
+exports.register = function (pack, options, next) {
+
+    var securePack = pack.select({ label: 'secure' });
+    if (!securePack.length) {
+        return next(new Error('No secure servers found'));   
+    }
+
+    securePack.route({ method: 'GET', path: '/', handler: function (request) {
+
+        request.reply('Hello Secure Server');
+    }});
+
+    next();
+};
+```