verdnatura-mirror
/
loopback-boot
mirror of https://github.com/strongloop/loopback-boot.git
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #18 from strongloop/doc-changes 

Doc changes
This commit is contained in:
Miroslav Bajtoš 2014-07-09 07:39:02 +02:00
parent 5e142c5188 25704cf69a
commit 3522f117c0
6 changed files with 55 additions and 375 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

394
README.md
View File

@ -1,10 +1,32 @@
# LoopBack Boot # 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 ## Installation
@ -23,369 +45,9 @@ app.use(loopback.rest());
app.listen(); 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. complete API reference.
## Versions ## License
The version range `1.x` is backwards compatible with `app.boot` provided This module is provided under dual MIT/StrongLoop license. See [LICENSE](LICENSE) for details.
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
<script src="app.bundle.js"></script>
<script>
var app = require('loopback-app');
var User = app.models.User;
User.login(
{ email: 'test@example.com', password: '12345' },
function(err, res) {
if (err) {
console.error('Login failed: ', err);
} else {
console.log('Logged in.');
}
}
);
</script>
```

2
browser.js
View File

@ -11,7 +11,7 @@ var execute = require('./lib/executor');
* *
* @param {Object} app The loopback app to boot, as returned by `loopback()`. * @param {Object} app The loopback app to boot, as returned by `loopback()`.
* *
* @header bootBrowserApp(app) * @header boot(app)
*/ */
exports = module.exports = function bootBrowserApp(app) { exports = module.exports = function bootBrowserApp(app) {

10
docs.json
View File

@ -1,12 +1,8 @@
{ {
"content": [ "content": [
"README.md", "docs/header-node.md",
{
"title": "API",
"depth": 2
},
"index.js", "index.js",
"browser.js", "docs/header-browser.md",
"docs/migrating-from-1x-to-2x.md" "browser.js"
] ]
} }

11
docs/header-browser.md Normal file
View File

@ -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);
```

11
docs/header-node.md Normal file
View File

@ -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);
```

2
index.js
View File

@ -68,7 +68,7 @@ var addInstructionsToBrowserify = require('./lib/bundler');
* for files containing model definitions. * for files containing model definitions.
* @end * @end
* *
* @header bootLoopBackApp(app, [options]) * @header boot(app, [options])
*/ */
exports = module.exports = function bootLoopBackApp(app, options) { exports = module.exports = function bootLoopBackApp(app, options) {