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

Merge pull request #22 from strongloop/model-docs 

Model Documentation + How it Works
This commit is contained in:
Ritchie Martori 2013-09-05 10:57:43 -07:00
parent 61c30e58b9 b17a3c4ea7
commit 2e6a1c9dd9
2 changed files with 135 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
docs/concepts.md
View File

@ -1,65 +1,144 @@
##Concepts ## Concepts
###SDKs ### Overview
Before we go into all the wonderful concepts that make up LoopBack, let's first
answer a couple of questions:
> What _is_ LoopBack?
- 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.
> 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** **PLACEHOLDER FOR SDK INTRO**
###Model ### Models
LoopBack is centered around models. A model is an object that encapsulates > What is a Model?
data. A model is usually named after its real life counterpart. Like its real
life counterpart, a model has some properties. Each property has a name, a type,
and other attributes. For example,
model: Person In LoopBack, a Model consists of the following:
properties: - Application data
- a Person model has properties such as First Name, Last Name and Birthday. - Validation rules
- First Name and Last Name are strings while Birthday is date. - Business logic
A model can also do things as actions and behaviors. Some actions are common to A mobile client uses the remote API provided by Models to request any
all instances of the same model while others are specific to a given instance. information needed to display a useful interface to the user.
For example,
model: Person #### A Simple Example
actions: For example, an e-commerce app might have `Product` and `Inventory` Models.
- a Person model can say his/her Full Name (relying on a given instance) A mobile client could use the `Product` Model API to search through all of the
- a Person model can find people by Last Name (independent of instances) 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.
Models are the vehicle for data exchange and data representation across ```js
different layers in LoopBack. For example, the Person model is available as // Step 1: Create Models
database tables, Node.js classes, REST resources, and mobile SDK objects. var Model = require('loopback').Model;
var Product = Model.extend('product');
var Inventory = Model.extend('customer');
```
When developing your mobile applications, think of models being the "M" in your **NOTE:** Models are _schema-less_ by default, but some Connectors, such as
MVC framework. Models in LoopBack have backend connectivity built in already, relational databases, _require_ schemas. Additionally, schemas are immensely
so that you can save data back to your backend and call actions or functions run valuable for validating sanitizing data coming from mobile clients. See
on the backend seamlessly from your mobile application. [Sanitizing and Validating Models](#sanitizing-and-validating-models) if your
application needs to connect to an RDBMS, for example.
###LoopBack Definition Language (LDL) #### Attaching Data Sources
All models in LoopBack can be described as JSON objects. LoopBack has utilized Attaching a Model to a Data Source gives you access to a powerful API mixed into
and extended JSON to define a model's properties and structure. The JSON that is Models by their Sources. The [MongoDB Connector](#), for example, mixes in a
utilized to help define a model's properties and structure or schema is called `create` method that allows us to store a new Product in the database:
LoopBack Definition Language (LDL). LDL is simple DSL to define data models in
JavaScript or plain JSON. The model definitions establish common knowledge of
data in LoopBack. For example,
model: Person ```js
// Step 2: Attach Data Sources
var db = loopback.createDataSource({
connector: require('loopback-connector-mongodb')
});
definition in LDL: // Enables the Model to use the MongoDB API
{ Product.attachTo(db);
"firstName" : "string",
"lastName" : "string",
"birthday": "date"
}
For more information, please read [LoopBack Definition Language Guide](/loopback-datasource-juggler/#loopback-definition-language-guide). // 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
});
```
###Datasources and Connectors #### Exposing to Mobile Clients
LoopBack allows you to connect to many sources of data and services in the cloud Models can be exposed to mobile clients using one of the remoting middlewares.
and on premise in your data center. These sources of data and services are This example uses the `app.rest` middleware to expose the `Product` Model's API
over REST.
```js
// Step 3: Create a LoopBack Application
var app = loopback();
// Use the REST remoting middleware
app.use(loopback.rest());
// Expose the `Product` model
app.model(Product);
```
#### 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.
```js
// Step 4: Add a Schema
var productSchema = {
"name": { "type": "string", "required": true },
"price": "number"
};
var Product = Model.extend('product', productSchema);
```
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.
#### More About Models
- 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).
- Expose custom behavior to clients using [remote methods](#remote-methods).
- See how to [define relationships](#relationships) between Models.
### Data Sources and Connectors
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 called DataSources. DataSources are accessed through a plugin called a Connector
in LoopBack. Plugins are highly customizable and extensible. Unlike other in LoopBack. Plugins are highly customizable and extensible. Unlike other
mobile backend, LoopBack can leverage your existing data and organize them in mobile backend, LoopBack can leverage your existing data and organize them in
@ -79,22 +158,21 @@ the underlying connector and exposes functions via DataSource or model classes.
#### LoopBack Connector Modules #### LoopBack Connector Modules
| Type | Package Name | | Type | Package Name |
| --------- |:--------------------------------------------------------------------------------------:| | --------- | -------------------------------------------------------------------------------------- |
| Memory | [Built-in](https://github.com/strongloop/loopback-datasource-juggler) | | Memory | [Built-in](https://github.com/strongloop/loopback-datasource-juggler) |
| MongoDB | [loopback-connector-mongodb](https://github.com/strongloop/loopback-connector-mongodb) | | MongoDB | [loopback-connector-mongodb](https://github.com/strongloop/loopback-connector-mongodb) |
| Oracle | [loopback-connector-oracle](https://github.com/strongloop/loopback-connector-oracle) | | Oracle | [loopback-connector-oracle](https://github.com/strongloop/loopback-connector-oracle) |
| REST | [loopback-connector-rest](https://github.com/strongloop/loopback-connector-rest) | | 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 ### REST
Everything defined in LoopBack is available to you as a REST endpoint. For Everything defined in LoopBack (e.g. Models) can be made available as a REST
every model that is created in LoopBack, a REST endpoint is automatically endpoint. You can see and experiment with _your_ REST api using the
created for you. You can see and experiment with your REST api using the
[LoopBack API Explorer](http://localhost:3000/explorer/). [LoopBack API Explorer](http://localhost:3000/explorer/).
LoopBack also supports other protocols for your API as well. Socket.io is LoopBack also supports other protocols for your API as well. Socket.io is
another protocol that is currently being developed. another protocol that is currently being developed.
For more information, please read [Model REST APIs](#model-rest-api). For more information, please read [Model REST APIs](#model-rest-api).

13
docs/intro.md
View File

@ -1,14 +1,15 @@
#LoopBack # LoopBack
**v1.0.0** **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 LoopBack is a mobile backend framework that puts you in control. As
a mobile developer you decide where to run your mobile backend - in a mobile developer you decide where to run your mobile backend - in
the cloud or on permise. the cloud or on-premise.
LoopBack is built on [StrongNode](/strongnode) and open source Node. LoopBack is built on [StrongNode](/strongnode) and open source Node.js
js modules. It leverages the power of Node, the community that modules. It leverages the power of Node, the community that
stands behind Node, and the support that [StrongLoop](www.strongloop.com) offers. stands behind Node, and the support that [StrongLoop](www.strongloop.com)
offers.
LoopBack is here to help you develop mobile applications with rich LoopBack is here to help you develop mobile applications with rich
functionality and data that is in your datacenter and the cloud. functionality and data that is in your datacenter and the cloud.