diff --git a/README.md b/README.md index 2b3c406..90a2b3c 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,32 @@ # LoopBack Boot -LoopBack Boot is a convention-based bootstrapper for LoopBack applications. +A convention-based bootstrapper for LoopBack applications. -**For full documentation, see the official StrongLoop documentation:** +For full documentation, see the official StrongLoop documentation: [Application initialization](http://docs.strongloop.com/display/LB/Application+initialization) and [Creating a LoopBack application](http://docs.strongloop.com/display/LB/Creating+a+LoopBack+application). - * [Creating a LoopBack application](http://docs.strongloop.com/display/LB/Creating+a+LoopBack+application) +## Overview + +The loopback-boot module initializes (bootstraps) a LoopBack application. Specifically, it: + - Configures data-sources. + - Defines custom models + - Configures models and attaches models to data-sources. + - Configures application settings + - Runs additional boot scripts, so you can put custom setup code in multiple small files instead of in the main application file. + +For more information, see [Application initialization](http://docs.strongloop.com/display/LB/Application+initialization). + +### Version notes + +The version range `1.x` is backwards compatible with `app.boot` provided +by LoopBack 1.x versions and the project layout scaffolded by `slc lb project` +up to slc version 2.5. + +The version range `2.x` supports the new project layout as scaffolded by +`yo loopback`. + +This document describes the configuration conventions of the `2.x` versions. +See the [official documentation](http://docs.strongloop.com/display/LB/Application+initialization) +for instructions on upgrading existing projects. ## Installation @@ -23,369 +45,9 @@ app.use(loopback.rest()); app.listen(); ``` -See [API docs](http://apidocs.strongloop.com/loopback-boot/#api) for +See [API docs](http://apidocs.strongloop.com/loopback-boot/) for complete API reference. -## Versions +## License -The version range `1.x` is backwards compatible with `app.boot` provided -by LoopBack 1.x versions and the project layout scaffolded by `slc lb project` -up to slc version 2.5. - -The version range `2.x` supports the new project layout as scaffolded by -`yo loopback`. - -This document describes the configuration conventions of the `2.x` versions. -See [Migrating from 1.x to 2.x](http://apidocs.strongloop.com/loopback-boot/#migrating-from-1x-to-2x) -for step-by-step instructions on how to upgrade existing projects. - -## Configurations and conventions - -The bootstrapping process takes care of the following tasks: - - - Configuration of data-sources. - - Definition of custom Models - - Configuration of models, attaching models to data-sources. - - Configuration of app settings like `host`, `port` or `restApiRoot`. - - Running additional boot scripts, so that the custom setup code can be kept - in multiple small files as opposed to keeping everything in the main app file. - -Below is the typical project layout. See the following sections for description -of the project files. - -``` -project/ - app.js - config.json - datasources.json - models.json - models/ - boot/ -``` - -### App settings - -The settings are loaded from the file `config.json` in the project root directory -and can be accessed via `app.get('option-name')` from the code. - -Additionally, the following files can provide values to override `config.json`: - - - `config.local.js` or `config.local.json` - - `config.{env}.js` or `config.{env}.json`, where `{env}` is the value of `NODE_ENV` - (typically `development` or `production`) - -**NOTE:** The additional files can override the top-level keys with -value-types (strings, numbers) only. Nested objects and arrays are -not supported at the moment. - -#### Example settings - -*config.json* - -```json -{ - "host": "localhost", - "port": 3000, - "restApiRoot": "/api" -} -``` - -*config.production.js* - -```js -module.exports = { - host: process.env.CUSTOM_HOST, - port: process.env.CUSTOM_PORT -}; -``` - -### Data sources - -The configuration of data sources is loaded from the file `datasources.json` -in the project root directory, the data sources can be accessed via -`app.datasources['datasource-name']` from the code. - -Additionally, the following files can provide values to override -`datasources.json`: - - - `datasources.local.js` or `datasources.local.json` - - `datasources.{env}.js` or `datasources.{env}.json`, - where `{env}` is the value of `NODE_ENV` - (typically `development` or `production`) - -**NOTE:** The additional files can override the top-level data-source options -with value-types (strings, numbers) only. Nested objects and arrays are -not supported at the moment. - -#### Example data sources - -*datasources.json* - -```js -{ - // the key is the datasource name - // the value is the config object to pass to - // app.dataSource(name, config). - db: { - connector: 'memory' - } -} -``` - -*datasources.production.json* - -```js -{ - db: { - connector: 'mongodb', - database: 'myapp', - user: 'myapp', - password: 'secret' - } -} -``` - -### Models: definition - -Custom models are defined using JSON files in `models/` directory, -one JSON file per model. - -#### Example models - -The following are example JSON files for two `Model` definitions: -`Dealership` and `Location`. - -*models/dealership.json* - -```js -{ - // the model name - "name": "Dealership", - // the options passed to Model.extend(name, properties, options) - "options": { - "relations": { - "cars": { - "type": "hasMany", - "model": "Car", - "foreignKey": "dealerId" - } - } - }, - // the properties passed to Model.extend(name, properties, options) - "properties": { - "id": {"id": true}, - "name": "String", - "zip": "Number", - "address": "String" - } -} -``` - -*models/car.json* -```js -{ - "name": "Car", - // options can be specified at the top level too - "relations": { - "dealer": { - "type": "belongsTo", - "model": "Dealership", - "foreignKey": "dealerId" - }, - } - "properties": { - "id": { - "type": "String", - "required": true, - "id": true - }, - "make": { - "type": "String", - "required": true - }, - "model": { - "type": "String", - "required": true - } - } -} -``` - -#### Adding custom methods to models - -The models created from JSON files come with the set of built-in methods -like `find` and `create`. To implement your custom methods, you should -create a javascript file in `models/` directory with the same base-name -as the JSON file containing model definition (e.g. `models/car.js` for -`models/car.json`) and define the methods there. - -Example: - -*models/car.js* - -```js -// Car is the model constructor -// Base is the parent model (e.g. loopback.PersistedModel) -module.exports = function(Car, Base) { - // Define a static method - Car.customMethod = function(cb) { - // do some work - cb(); - }; - - // Define an instance (prototype) method - Car.prototype.honk = function(duration, cb) { - // make some noise for `duration` seconds - cb(); - }; - - // Provide a custom setup method - Car.setup = function() { - Base.setup.call(this); - - // configure validations, - // configure remoting for methods, etc. - }; -}; -``` - -### Models: configuration - -Before the models can be used in a loopback application, they have to be -configured - attached to a data-source, exposed via the REST API, and so on. - -The configuration is described in the file `models.json`: - -```js -{ - // the key is the model name - "Dealership": { - // a reference, by name, to a dataSource definition - "dataSource": "my-db" - }, - "Car": { - "dataSource": "my-db", - // do not expose Car over the REST API - "public": false - } -} -``` - -The bootstrapper will automatically load definition of every custom model -configured in `models.json`. By default, the definition files are loaded from -`models/` subdirectory. However, it is possible to specify a different location -(or even multiple locations) via `_meta.sources`: - -```js -{ - "_meta": { - "sources": [ - // all paths are relative to models.json - "./models" - "./node_modules/foobar/models" - ] - }, - // use the `FooBar` model from the `foobar` module - "FooBar": { - "dataSource": "db" - } -} -``` - -### Boot scripts - -When the data sources and models are configured, the bootstrapper invokes -all scripts in the `boot/` folder. The scripts are sorted lexicographically -ingoring case. - -#### Example boot script - -*boot/authentication.js* - -```js -module.exports = function(app) { - app.enableAuth(); -}; -``` - -## Running in a browser - -The bootstrap process is implemented in two steps that can be called -independently. - -### Build - -The first step loads all configuration files, merges values from additional -config files like `app.local.js` and produces a set of instructions -that can be used to boot the application. - -These instructions must be included in the browser bundle together -with all configuration scripts from `models/` and `boot/`. - -Don't worry, you don't have to understand these details. -Just call `boot.compileToBrowserify`, it will take care of everything for you. - -*build file (Gruntfile.js, gulpfile.js)* - -```js -var browserify = require('browserify'); -var boot = require('loopback-boot'); - -var b = browserify({ - basedir: appDir, -}); - -// add the main application file -b.require('./browser-app.js', { expose: 'loopback-app' }); - -// add boot instructions -boot.compileToBrowserify(appDir, b); - -// create the bundle -var out = fs.createWriteStream('browser-bundle.js'); -b.bundle().pipe(out); -// handle out.on('error') and out.on('close') -``` - -### Run - -In the browser, the main application file should call loopback-boot -to setup the loopback application by executing the instructions -contained in the browser bundle: - -*browser-app.js* - -```js -var loopback = require('loopback'); -var boot = require('loopback-boot'); - -var app = module.exports = loopback(); -boot(app); -``` - -The app object created above can be accessed via `require('loopback-app')`, -where `loopback-app` is the identifier used for the main app file in -the browserify build shown above. - -Here is a simple example demonstrating the concept: - -*index.html* - -```xml - - -``` +This module is provided under dual MIT/StrongLoop license. See [LICENSE](LICENSE) for details. diff --git a/browser.js b/browser.js index ac49bc2..7346c4a 100644 --- a/browser.js +++ b/browser.js @@ -11,7 +11,7 @@ var execute = require('./lib/executor'); * * @param {Object} app The loopback app to boot, as returned by `loopback()`. * - * @header bootBrowserApp(app) + * @header boot(app) */ exports = module.exports = function bootBrowserApp(app) { diff --git a/docs.json b/docs.json index 5607f8f..1fab05d 100644 --- a/docs.json +++ b/docs.json @@ -1,12 +1,8 @@ { "content": [ - "README.md", - { - "title": "API", - "depth": 2 - }, + "docs/header-node.md", "index.js", - "browser.js", - "docs/migrating-from-1x-to-2x.md" + "docs/header-browser.md", + "browser.js" ] } diff --git a/docs/header-browser.md b/docs/header-browser.md new file mode 100644 index 0000000..a2c0f3b --- /dev/null +++ b/docs/header-browser.md @@ -0,0 +1,11 @@ +## Browser API + +Use this API in the `app.js` file that you process by browserify and run in the browser. + +```js +var loopback = require('loopback'); +var boot = require('loopback-boot'); + +var app = module.exports = loopback(); +boot(app); +``` diff --git a/docs/header-node.md b/docs/header-node.md new file mode 100644 index 0000000..c7b19fb --- /dev/null +++ b/docs/header-node.md @@ -0,0 +1,11 @@ +## Node API + +Use this API in the `app.js` file of your server-side Node.js application. + +```js +var loopback= require('loopback'); +var boot = require('loopback-boot'); + +var app = module.exports = loopback(); +boot(app, __dirname); +``` diff --git a/index.js b/index.js index 84db3d9..1c1b426 100644 --- a/index.js +++ b/index.js @@ -68,7 +68,7 @@ var addInstructionsToBrowserify = require('./lib/bundler'); * for files containing model definitions. * @end * - * @header bootLoopBackApp(app, [options]) + * @header boot(app, [options]) */ exports = module.exports = function bootLoopBackApp(app, options) {