diff --git a/docs.json b/docs.json index ccd82701..cbd44add 100644 --- a/docs.json +++ b/docs.json @@ -12,5 +12,8 @@ "docs/js.md", "docs/java.md", "docs/rest.md" - ] + ], + "assets": { + "/": "/docs" + } } diff --git a/docs/concepts.md b/docs/concepts.md index 3d10032a..d6f0c39a 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -7,7 +7,7 @@ answer a couple of questions: > What _is_ LoopBack? - - A component in the [StrongLoop Suite](www.strongloop.com/strongloop-suite). + - A component in the [StrongLoop Suite](http://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 @@ -16,39 +16,49 @@ answer a couple of questions: > 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. + - LoopBack applications are made up of three components: +[Models](#models), [Data Sources/Connectors](#data-sources-and-connectors), 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. + - Any mobile or web app can interact with LoopBack through the Model API that are +backed by various data sources. 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. + +![concepts](loopback-concepts.png "LoopBack Concepts") ### Mobile Clients **PLACEHOLDER FOR SDK INTRO** +In summary, mobile clients work with objects that are connected to LoopBack +to provide data and perform actions.Those objects are captured as models in +LoopBack. + ### Models > What is a Model? -In LoopBack, a Model consists of the following: +A LoopBack Model consists of the following: - Application data - Validation rules + - Data access capabilities - Business logic A mobile client uses the remote API provided by Models to request any -information needed to display a useful interface to the user. +information needed to display a useful interface to the user or trigger actions +on the models to interact with backend systems. -#### A Simple Example +Let's use a simple example to explain what a model can do for you. + +#### Defining a model 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 +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 aggregates this information. @@ -60,17 +70,22 @@ var Product = Model.extend('product'); var Inventory = Model.extend('customer'); ``` -**NOTE:** Models are _schema-less_ by default, but some Connectors, such as +**NOTE:** Models are _schema-less_ by default, but some data sources, 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. +valuable for establishing the common knowledge of business data so that the data +exchange can be agreed and documented while data coming from mobile clients can +be validated and/or sanitized . See [Sanitizing and Validating Models](#sanitizing-and-validating-models) +if your application needs to connect to an RDBMS, for example. -#### Attaching Data Sources +#### Attaching to Data Sources -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: +Instances of a Model carry application data. But they are not very interesting +until applications can create, retrieve, update, or delete (CRUD) model instances. +LoopBack introduces the DataSource concept to provide the data access +capabilities to models. Attaching a Model to a DataSource gives you access to a +powerful API mixed into Models by the Connector behind a DataSource. 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 @@ -87,6 +102,9 @@ Product.create({ name: 'widget', price: 99.99 }, function(err, widget) { }); ``` +Now the models have both data and behaviors. How can the mobile clients benefit +from them? We need a way to make the models available from mobile clients. + #### Exposing to Mobile Clients Models can be exposed to mobile clients using one of the remoting middlewares. @@ -104,11 +122,16 @@ app.use(loopback.rest()); app.model(Product); ``` +After this, you'll have the `Product` model with CRUD functions working remotely +from the mobile clients. Please note the model is schema-less till now and the +data are not checked. + #### 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 +A Model can be described in plain json or JavaScript. The description is called +schema. Once a schema is defined for 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 @@ -137,12 +160,8 @@ required `name` property. ### 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 -the form of models. +Now you see the power of LoopBack models. A model gets rich set of functions out +of the box with the contribution from Data Sources and Connectors. The concept of DataSource is introduced to encapsulate business logic to exchange data between models and various data sources. Data sources are @@ -150,10 +169,16 @@ typically databases that provide create, retrieve, update, and delete (CRUD) functions. LoopBack also generalize other backend services, such as REST APIs, SOAP Web Services, and Storage Services, as data sources. -Data sources are backed by connectors which implement the data exchange logic -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 allows you to connect to many sources of data and services both in the +cloud and on-premise in your data center. 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 the form of models. + +Connectors implement the data exchange logic 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 @@ -168,7 +193,7 @@ For more information, please read the [LoopBack DataSource and Connector Guide]( ### REST -Everything defined in LoopBack (e.g. Models) can be made available as a REST +Functions defined in LoopBack 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/). diff --git a/docs/loopback-concepts.png b/docs/loopback-concepts.png new file mode 100644 index 00000000..4232b35c Binary files /dev/null and b/docs/loopback-concepts.png differ