diff --git a/docs/concepts.md b/docs/concepts.md index f1386ea5..3d10032a 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -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** -###Model +### Models -LoopBack is centered around models. A model is an object that encapsulates -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, +> What is a Model? - model: Person +In LoopBack, a Model consists of the following: - properties: - - a Person model has properties such as First Name, Last Name and Birthday. - - First Name and Last Name are strings while Birthday is date. + - Application data + - Validation rules + - Business logic -A model can also do things as actions and behaviors. Some actions are common to -all instances of the same model while others are specific to a given instance. -For example, +A mobile client uses the remote API provided by Models to request any +information needed to display a useful interface to the user. - model: Person +#### A Simple Example - actions: - - a Person model can say his/her Full Name (relying on a given instance) - - a Person model can find people by Last Name (independent of instances) +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. -Models are the vehicle for data exchange and data representation across -different layers in LoopBack. For example, the Person model is available as -database tables, Node.js classes, REST resources, and mobile SDK objects. +```js +// Step 1: Create Models +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 -MVC framework. Models in LoopBack have backend connectivity built in already, -so that you can save data back to your backend and call actions or functions run -on the backend seamlessly from your mobile application. +**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. -###LoopBack Definition Language (LDL) +#### Attaching Data Sources -All models in LoopBack can be described as JSON objects. LoopBack has utilized -and extended JSON to define a model's properties and structure. The JSON that is -utilized to help define a model's properties and structure or schema is called -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, +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: - model: Person +```js +// Step 2: Attach Data Sources +var db = loopback.createDataSource({ + connector: require('loopback-connector-mongodb') +}); - definition in LDL: - { - "firstName" : "string", - "lastName" : "string", - "birthday": "date" - } +// Enables the Model to use the MongoDB API +Product.attachTo(db); -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 -and on premise in your data center. These sources of data and services are +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 +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 in LoopBack. Plugins are highly customizable and extensible. Unlike other 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 | 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) | | 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 +LoopBack also supports other protocols for your API as well. Socket.io is another protocol that is currently being developed. For more information, please read [Model REST APIs](#model-rest-api). diff --git a/docs/intro.md b/docs/intro.md index fe194c95..42a1dee6 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -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.