## Server Extensions

### [Express.js](http://expressjs.com/)

#### Entry Point

Bootstrapping is happening in `./server/index.coffee`. You usually don't need to
touch this file. If you want to extend the functionality of the Server you
should use the `./server/initialize` directory (see below).

#### Configuration

All configuration goes in `./server/config.coffee` and is passed along to
initilization and routes (see examples below).

The default port of the Server is `7799`. The default static directory is
`./public` - generated by `gulp build` (you want to run `gulp watch` to pick up
file changes while developing).

#### Initilization

The Entry Point will load and initialize all files that are in
`./server/initialize`. For example `./server/initialize/app.coffee` will
initialize the JSON Body Parser and the static directory:

    module.exports = (config, helpers, io, models) ->
      @use express.static(config.server.publicDir)
      @use bodyParser.json()

The context (`@`/`this`) is the `express()` app that is initialized in the
Entry Point.

#### Routes

Pretty much the same as the Initilization files, the Entry Point will load all
files in `./server/routes`. Split the files depending on your resources and
define all related routes in them. For example `./server/routes/app.coffee`:

    module.exports = (config, helpers, io, models) ->
      @get '/hello/:name', (req, res) ->
        res.json { str: helpers.app.sayHello(req.params.name) }

      @post '/whatever, (req, res) ->

#### Helpers

Helpers are commonly used functions that can be shared between initilization,
routes and models. They are passed to the exported function as seen in the
examples above.

All helpers will be loaded from the directory `./server/helpers`.

The name of the file is important, as it's used to populate the `helpers`
object. For example `./server/helpers/app.coffee`:

    module.exports =
      sayHello: (toName) ->
        "Hello #{toName}!"

Will be available as `helpers.app.sayHello()`. A file
`./server/helpers/string.coffee` would be available as `helpers.string.*`.

Helpers should only work with raw data and should not interact with the Express
app or models in any way.

#### Start Server for Development

When in development environment, use `npm start`. This will start a
[Forever](https://github.com/foreverjs/forever) process that still logs to
`STDOUT`. It will watch the `./server` directory for any file changes and
restarts the server.

You'd still need to reload the browser manually. Unfortunately I haven't found
a reliable solution for this yet.

### [Lodash](https://lodash.com/docs)

[Lodash](https://lodash.com/docs) is already installed for convinience. Just do
`_ = require('lodash')` anywhere and hack away.

### [Socket.io](http://socket.io/docs/)

A [Socket.io](http://socket.io/docs/) Server is automatically initialized on
the Entry Point and is served at the same port as the HTTP Server. The `io`
object is passed to the initilization and the routes, see the examples above.

### [MongoDB](https://www.mongodb.org/) with [Mongoose](http://mongoosejs.com/docs/guide.html) (Optional)

You can define [Mongoose](http://mongoosejs.com/docs/guide.html) models in
`./server/models`. For example `./server/models/count.coffee`:

    module.exports = (helpers) ->
      @model 'Count',
        visits: Number

The context (`@`/`this`) is the `mongoose` object defined in the Entry Point.
Just make sure that the `mongoose.model` definition is returned.

Models are initialized in the `models` object and passed to initilization as
well as routes. Just as the `helpers` it is important how you name the files, as
it is the key the model is initialized with. The example above would be located
at `models.count`. A usage example would be:

    module.exports = (config, helpers, models) ->
      @get '/count', (req, res) ->
        models.count.findOne {}, (err, count) ->
          unless count
            count = new models.count({ visits: 0 })

          count.visits += 1
          count.save()

          res.json count.toJSON()

The Server Entry Point only tries to connect to the database defined in the
config file if there are any model files. So you might use the Server without
any database connection by leaving the `./server/models` directory empty or
remove it altogether.

### `yo grail:create` - Generate a Server Component

With the `yo grail:create` you can quickly create a Server Component consisting
of Initialize, Helper, Route and/or Model. All are optional.