Update model docs further.
This commit is contained in:
Michael Schoonmaker
parent
e0ff75bc84
commit
b17a3c4ea7
154
docs/concepts.md
154
docs/concepts.md
|
|
@ -1,135 +1,144 @@
|
|||
##Concepts
|
||||
## Concepts
|
||||
|
||||
###What is LoopBack?
|
||||
### Overview
|
||||
|
||||
- a component in the StrongLoop Suite
|
||||
- a library of Node.js modules for connecting mobile apps to various data
|
||||
sources
|
||||
- a command line tool `slc lb` for generating applications and models
|
||||
- a set of SDKs for native and web mobile clients
|
||||
Before we go into all the wonderful concepts that make up LoopBack, let's first
|
||||
answer a couple of questions:
|
||||
|
||||
###How it Works
|
||||
> What _is_ LoopBack?
|
||||
|
||||
LoopBack apps are made up of three components: mobile clients, data sources, and
|
||||
models. Clients, such as mobile or web apps, use LoopBack mobile SDKs to
|
||||
interact with data sources, such as a database or REST API. Access to these
|
||||
data sources is provided by models, which control how a data source is exposed
|
||||
to a mobile client.
|
||||
- A component in the [StrongLoop Suite](www.strongloop.com/strongloop-suite).
|
||||
- A library of Node.js modules for connecting mobile apps to a variety of data
|
||||
sources.
|
||||
- A command line tool, `slc lb`, for generating models and entire applications
|
||||
with the LoopBack library.
|
||||
- A set of SDKs for native and web-based mobile clients.
|
||||
|
||||
Any mobile or web app can interact with a LoopBack data source through
|
||||
the model API. The model API is available in Node.js, over REST, and as
|
||||
native mobile SDKs for iOS, Android, and HTML5. Using the API, clients can query
|
||||
databases, store data, upload files, send emails, create push notifications,
|
||||
register users, and any other behavior provided by data sources.
|
||||
> How does LoopBack work?
|
||||
|
||||
LoopBack Applications are made up of three components:
|
||||
[Data Sources](#data-sources-and-connectors) (also referred to as "Connectors"),
|
||||
[Models](#models), and the [Mobile Clients](#mobile-clients) that consume them.
|
||||
|
||||
Any mobile or web app can interact with a LoopBack Data Source through the Model
|
||||
API. The Model API is available [locally within Node.js](#model), [remotely over
|
||||
REST](#rest-api), and as native mobile SDKs for [iOS, Android, and
|
||||
HTML5](#mobile-clients). Using the API, clients can query databases, store data,
|
||||
upload files, send emails, create push notifications, register users, and any
|
||||
other behavior provided by data sources.
|
||||
|
||||
### Mobile Clients
|
||||
|
||||
**PLACEHOLDER FOR SDK INTRO**
|
||||
|
||||
###Models
|
||||
### Models
|
||||
|
||||
**What is a Model?**
|
||||
> What is a Model?
|
||||
|
||||
In LoopBack, a **Model** consists of the following.
|
||||
In LoopBack, a Model consists of the following:
|
||||
|
||||
- application data
|
||||
- business rules
|
||||
- logic
|
||||
- functions
|
||||
- Application data
|
||||
- Validation rules
|
||||
- Business logic
|
||||
|
||||
A mobile client uses APIs provided by **Models** to request any information
|
||||
needed to display a useful interface to the user.
|
||||
A mobile client uses the remote API provided by Models to request any
|
||||
information needed to display a useful interface to the user.
|
||||
|
||||
**A Simple Example**
|
||||
#### A Simple Example
|
||||
|
||||
For example, an e-commerce app might have `Product` and `Inventory` models.
|
||||
A mobile client could use the `Product` model API to search all the products in
|
||||
a database. A client could join the `Product` and `Inventory` data to determine
|
||||
what products are in-stock, or the `Product` model could provide a server-side
|
||||
function (or [remote method](#remote-methods)) that returns this information.
|
||||
For example, an e-commerce app might have `Product` and `Inventory` Models.
|
||||
A mobile client could use the `Product` Model API to search through all of the
|
||||
Procuts in a database. A client could join the `Product` and `Inventory` data to
|
||||
determine what products are in stock, or the `Product` Model could provide a
|
||||
server-side function (or [remote method](#remote-methods)) that aggregates this
|
||||
information.
|
||||
|
||||
```js
|
||||
var loopback = require('loopback');
|
||||
var Model = loopback.Model;
|
||||
// Step 1: Create Models
|
||||
var Model = require('loopback').Model;
|
||||
var Product = Model.extend('product');
|
||||
var Inventory = Model.extend('customer');
|
||||
```
|
||||
|
||||
> - Models are **schema-less** by default.
|
||||
> - Some data sources, such as relational databases, require schemas.
|
||||
> - Adding a schema allows you to sanitize data coming from mobile clients.
|
||||
**NOTE:** Models are _schema-less_ by default, but some Connectors, such as
|
||||
relational databases, _require_ schemas. Additionally, schemas are immensely
|
||||
valuable for validating sanitizing data coming from mobile clients. See
|
||||
[Sanitizing and Validating Models](#sanitizing-and-validating-models) if your
|
||||
application needs to connect to an RDBMS, for example.
|
||||
|
||||
**Attaching Data Sources**
|
||||
#### Attaching Data Sources
|
||||
|
||||
Attaching a model to a data source gives you access to the data source's API.
|
||||
Using the MongoDB connector, this data source provides a `create` method. This
|
||||
example uses the `create` method to store a new product.
|
||||
Attaching a Model to a Data Source gives you access to a powerful API mixed into
|
||||
Models by their Sources. The [MongoDB Connector](#), for example, mixes in a
|
||||
`create` method that allows us to store a new Product in the database:
|
||||
|
||||
```js
|
||||
// Step 2: Attach Data Sources
|
||||
var db = loopback.createDataSource({
|
||||
connector: require('loopback-connector-mongodb')
|
||||
});
|
||||
|
||||
// enables the model to use
|
||||
// the mongodb api
|
||||
// Enables the Model to use the MongoDB API
|
||||
Product.attachTo(db);
|
||||
|
||||
// create a new product in the database
|
||||
Product.create({name: 'widget', price: 99.99}, function(err, widget) {
|
||||
console.log(widget.id); // the product's id
|
||||
// Create a new product in the database
|
||||
Product.create({ name: 'widget', price: 99.99 }, function(err, widget) {
|
||||
console.log(widget.id); // The product's id, added by MongoDB
|
||||
});
|
||||
```
|
||||
|
||||
**Exposing to Mobile Clients**
|
||||
#### Exposing to Mobile Clients
|
||||
|
||||
Models can be exposed to mobile clients using one of the remoting middlewares.
|
||||
This example uses the `app.rest` middleware to expose the `Product` model's API
|
||||
This example uses the `app.rest` middleware to expose the `Product` Model's API
|
||||
over REST.
|
||||
|
||||
```js
|
||||
// create a loopback app
|
||||
// Step 3: Create a LoopBack Application
|
||||
var app = loopback();
|
||||
|
||||
// use the REST remoting middleware
|
||||
// Use the REST remoting middleware
|
||||
app.use(loopback.rest());
|
||||
|
||||
// expose the `Product` model
|
||||
// Expose the `Product` model
|
||||
app.model(Product);
|
||||
```
|
||||
|
||||
**Sanitizing and Validating Models**
|
||||
#### Sanitizing and Validating Models
|
||||
|
||||
Once a schema is added to a model, it will validate and sanitize data before
|
||||
giving it to a data source. For example, the `Product` model has a schema that
|
||||
will not change. The example below updates the `Product` model with a schema
|
||||
written in **LoopBack Definition Language**, a well documented flavor of JSON.
|
||||
Once a schema is added to a Model, it will validate and sanitize data before
|
||||
giving it to a Data Source. For example, the `Product` Model has a schema that
|
||||
will not change. The example below updates the `Product` Model with a schema
|
||||
written in **LoopBack Definition Language**, a well-documented flavor of JSON.
|
||||
|
||||
```js
|
||||
// Step 4: Add a Schema
|
||||
var productSchema = {
|
||||
"name": {"type": "string", "required": true},
|
||||
"name": { "type": "string", "required": true },
|
||||
"price": "number"
|
||||
};
|
||||
var Product = Model.extend('product', productSchema);
|
||||
```
|
||||
|
||||
If a remote client tries to save a product with extra properties, they will be
|
||||
removed. The model will only be saved if the product contains the required
|
||||
`name` property.
|
||||
On one hand, If a remote client tries to save a product with extra properties
|
||||
(e.g. `description`), those properties will be removed before saving the Model.
|
||||
On the other hand, the Model will _only_ be saved if the product contains the
|
||||
required `name` property.
|
||||
|
||||
**Learn more about models**
|
||||
#### More About Models
|
||||
|
||||
- Check out the model [REST API](#rest-api)
|
||||
- Check out the Model [REST API](#rest-api).
|
||||
- Read the
|
||||
[LoopBack Definition Language Guide](http://docs.strongloop.com/loopback-datasource-juggler#loopback-definition-language-guide).
|
||||
- Browse the [Node.js Model API](#model).
|
||||
- Before you build your own, check out the [bundled models](#bundled-models).
|
||||
- Before you build your own, check out the [bundled Models](#bundled-models).
|
||||
- Expose custom behavior to clients using [remote methods](#remote-methods).
|
||||
- See how to [define relationships](#relationships) between models.
|
||||
- See how to [define relationships](#relationships) between Models.
|
||||
|
||||
###Datasources and Connectors
|
||||
### Data Sources and Connectors
|
||||
|
||||
LoopBack allows you to connect to many sources of data and services in the cloud
|
||||
and on premise in your data center. These sources of data and services are
|
||||
LoopBack allows you to connect to many sources of data and services both in the
|
||||
cloud and on-premise in your data center. These sources of data and services are
|
||||
called DataSources. DataSources are accessed through a plugin called a Connector
|
||||
in LoopBack. Plugins are highly customizable and extensible. Unlike other
|
||||
mobile backend, LoopBack can leverage your existing data and organize them in
|
||||
|
|
@ -146,7 +155,7 @@ using database drivers or other client APIs. In general, connectors are not used
|
|||
directly by application code. The DataSource class provides APIs to configure
|
||||
the underlying connector and exposes functions via DataSource or model classes.
|
||||
|
||||
**LoopBack Connector Modules**
|
||||
#### LoopBack Connector Modules
|
||||
|
||||
| Type | Package Name |
|
||||
| --------- | -------------------------------------------------------------------------------------- |
|
||||
|
|
@ -155,13 +164,12 @@ the underlying connector and exposes functions via DataSource or model classes.
|
|||
| Oracle | [loopback-connector-oracle](https://github.com/strongloop/loopback-connector-oracle) |
|
||||
| REST | [loopback-connector-rest](https://github.com/strongloop/loopback-connector-rest) |
|
||||
|
||||
For more information, please read [LoopBack DataSource and Connector Guide](/loopback-datasource-juggler/#loopback-datasource-and-connector-guide).
|
||||
For more information, please read the [LoopBack DataSource and Connector Guide](/loopback-datasource-juggler/#loopback-datasource-and-connector-guide).
|
||||
|
||||
### REST
|
||||
|
||||
Everything defined in LoopBack is available to you as a REST endpoint. For
|
||||
every model that is created in LoopBack, a REST endpoint is automatically
|
||||
created for you. You can see and experiment with your REST api using the
|
||||
Everything defined in LoopBack (e.g. Models) can be made available as a REST
|
||||
endpoint. You can see and experiment with _your_ REST api using the
|
||||
[LoopBack API Explorer](http://localhost:3000/explorer/).
|
||||
|
||||
LoopBack also supports other protocols for your API as well. Socket.io is
|
||||
|
|
|
|||
|
|
@ -1,14 +1,15 @@
|
|||
#LoopBack
|
||||
# LoopBack
|
||||
**v1.0.0**
|
||||
|
||||
LoopBack is part of the [StrongLoop Suite](www.strongloop.com/strongloop-suite)
|
||||
LoopBack is part of the [StrongLoop Suite](www.strongloop.com/strongloop-suite).
|
||||
|
||||
LoopBack is a mobile backend framework that puts you in control. As
|
||||
a mobile developer you decide where to run your mobile backend - in
|
||||
the cloud or on permise.
|
||||
LoopBack is built on [StrongNode](/strongnode) and open source Node.
|
||||
js modules. It leverages the power of Node, the community that
|
||||
stands behind Node, and the support that [StrongLoop](www.strongloop.com) offers.
|
||||
the cloud or on-premise.
|
||||
LoopBack is built on [StrongNode](/strongnode) and open source Node.js
|
||||
modules. It leverages the power of Node, the community that
|
||||
stands behind Node, and the support that [StrongLoop](www.strongloop.com)
|
||||
offers.
|
||||
|
||||
LoopBack is here to help you develop mobile applications with rich
|
||||
functionality and data that is in your datacenter and the cloud.
|
||||
|
|
|
|||
Loading…
Reference in New Issue