From 02bec9a7827029140bda9815e491f0eb61dec124 Mon Sep 17 00:00:00 2001 From: Taranveer Virk Date: Sun, 3 Jun 2018 18:08:02 -0400 Subject: [PATCH] docs(docs): update docs with datasource cli and booter content Signed-off-by: Taranveer Virk --- docs/site/Booting-an-Application.md | 34 +++++++++++++ docs/site/Concepts.md | 3 ++ docs/site/Controller-generator.md | 4 +- docs/site/DataSource-generator.md | 55 +++++++++++++++++++++ docs/site/DataSources.md | 41 +++++++++++++++ docs/site/Glossary.md | 2 +- docs/site/sidebars/lb4_sidebar.yml | 8 +++ docs/site/tables/lb4-artifact-commands.html | 28 +++++++---- docs/site/todo-tutorial-datasource.md | 48 ++++++------------ 9 files changed, 178 insertions(+), 45 deletions(-) create mode 100644 docs/site/DataSource-generator.md create mode 100644 docs/site/DataSources.md diff --git a/docs/site/Booting-an-Application.md b/docs/site/Booting-an-Application.md index 549d5eee8e97..4b9dbb04500b 100644 --- a/docs/site/Booting-an-Application.md +++ b/docs/site/Booting-an-Application.md @@ -226,6 +226,40 @@ The `repositories` object supports the following options: | `nested` | `boolean` | `true` | Look in nested directories in `dirs` for Repository artifacts | | `glob` | `string` | | A `glob` pattern string. This takes precendence over above 3 options (which are used to make a glob pattern). | +### DataSource Booter + +This Booter's purpose is to discover [DataSource](DataSource.md) type Artifacts +and to bind them to the Application's Context. The use of this Booter requires +`RepositoryMixin` from `@loopback/repository` to be mixed into your Application +class. + +You can configure the conventions used in your project for a DataSource by +passing a `datasources` object on `BootOptions` property of your Application. +The `datasources` object support the following options: + +| Options | Type | Default | Description | +| ------------ | -------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------- | +| `dirs` | `string \| string[]` | `['datasources']` | Paths relative to projectRoot to look in for DataSource artifacts | +| `extensions` | `string \| string[]` | `['.datasource.js']` | File extensions to match for DataSource artifacts | +| `nested` | `boolean` | `true` | Look in nested directories in `dirs` for DataSource artifacts | +| `glob` | `string` | | A `glob` pattern string. This takes precendence over above 3 options (which are used to make a glob pattern). | + +### DataSourceConfig Booter + +This Booter's purpose is to discover [DataSource Config]() type Artifacts and +to bind them to the Application's Context. + +You can configure the conventions used in your project for a DataSource Config +by passing a `datasourcesConfig` object on `BootOptions` property of your +Application. The `datasourcesConfig` object support the following options: + +| Options | Type | Default | Description | +| ------------ | -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------- | +| `dirs` | `string \| string[]` | `['datasources']` | Paths relative to projectRoot to look in for DataSource Config artifacts | +| `extensions` | `string \| string[]` | `['.datasource.json']` | File extensions to match for DataSource Config artifacts | +| `nested` | `boolean` | `true` | Look in nested directories in `dirs` for DataSource Config artifacts | +| `glob` | `string` | | A `glob` pattern string. This takes precendence over above 3 options (which are used to make a glob pattern). | + ### Custom Booters A custom Booter can be written as a Class that implements the `Booter` diff --git a/docs/site/Concepts.md b/docs/site/Concepts.md index 02ec5406b021..aca6ae516588 100644 --- a/docs/site/Concepts.md +++ b/docs/site/Concepts.md @@ -49,6 +49,9 @@ LoopBack 4 introduces some new concepts that are important to understand: `@loopback/repository-json-schema` module uses the decorators' metadata to build a matching JSON Schema. +- [**DataSources**](DataSources.md): A named configuration for a Connector + instance that represents data in an external system. + - [**Repository**](Repositories.md): A type of service that represents a collection of data within a DataSource. diff --git a/docs/site/Controller-generator.md b/docs/site/Controller-generator.md index f2294e09de42..702564d886cc 100644 --- a/docs/site/Controller-generator.md +++ b/docs/site/Controller-generator.md @@ -37,10 +37,10 @@ the name. The tool will prompt you for: -- Name of the controller. If the name had been supplied from the command line, +- **Name of the controller.** If the name had been supplied from the command line, the prompt is skipped and the controller is built with the name from the command-line argument. -- Type of the controller. You can select from the following types: +- **Type of the controller.** You can select from the following types: - **Empty Controller** - An empty controller definition - **REST Controller with CRUD Methods** - A controller wired up to a model and repository definition, with pre-defined CRUD methods. diff --git a/docs/site/DataSource-generator.md b/docs/site/DataSource-generator.md new file mode 100644 index 000000000000..563ddabb9846 --- /dev/null +++ b/docs/site/DataSource-generator.md @@ -0,0 +1,55 @@ +--- +lang: en +title: 'DataSource generator' +keywords: LoopBack 4.0, LoopBack 4 +tags: +sidebar: lb4_sidebar +permalink: /doc/en/lb4/DataSource-generator.html +summary: +--- + +{% include content/generator-create-app.html lang=page.lang %} + +### Synopsis + +Adds new [DataSource] class and config files to a LoopBack application. + +```sh +lb4 datasource [options] [] +``` + +### Options + +`--connector` : Name of datasource connector + +This can be a connector supported by LoopBack / Community / Custom. + +{% include_relative includes/CLI-std-options.md %} + +### Arguments + +`` - Required name of the datasource to create as an argiment to the command. If provided, the tool will use that as the default when it prompts for the name. + +### Interactive Prompts + +The tool will prompt you for: + +- **Name of the datasource.** If the name had been supplied from the command line, +the prompt is skipped and the datasource is built with the name from the +command-line argument. +- **Name of connector.** If not supplied via command line, you will be presented +with a list of connector to select from (including an `other` option for +custom connector). +- **Connector configuration.** If the connector is not a custom connector, the +CLI will prompt for the connector configuration information. + +### Output + +Once all the prompts have been answered, the CLI will do the following: +- Install `@loopback/repository` and the connector package (if it's not a custom +connector). +- Create a file with the connector configuration as follows: + `/datasources/${connector.name}.datasource.json` +- Create a DataSource class which recieves the connector config using [Dependency Injection](Dependency-injection.html) as follows: + `/datasources/${connector.name}.datasource.ts` +- Update `index.ts` to export the newly created DataSource class. diff --git a/docs/site/DataSources.md b/docs/site/DataSources.md new file mode 100644 index 000000000000..76706138b5b6 --- /dev/null +++ b/docs/site/DataSources.md @@ -0,0 +1,41 @@ +--- +lang: en +title: 'DataSources' +keywords: LoopBack 4.0, LoopBack 4 +tags: +sidebar: lb4_sidebar +permalink: /doc/en/lb4/DataSources.html +summary: +--- + +## Overview + +A `DataSource` in LoopBack 4 is a named configuration for a Connector instance +that represents data in an external system. The Connector is used by +`legacy-juggler-bridge` to power LoopBack 4 Repositories for Data operations. + +### Creating a DataSource + +It is recommended to use the `lb4 datasource` [command](DataSource-generator.html) +provided by the CLI to generate a DataSource. The CLI will prompt for all necessary connector information and create the following files: + +- `${connector.name}.datasource.json` containing the connector configuration +- `${connector.name}.datasource.ts` containing a class extending `juggler.DataSource`. This class can be used to override the default DataSource +behaviour programaticaly. Note: The connector configuration stored in the `.json` +file is injected into this class using [Dependency Injection](Dependency-inecjtion.html). + +Both the above files are generated in `src/datasources/` directory by the CLI. It +will also update `src/datasources/index.ts` to export the new DataSource class. + +Example DataSource Class: + +```ts +import {inject} from '@loopback/core'; +import {juggler, DataSource} from '@loopback/repository'; + +export class DbDataSource extends juggler.DataSource { + constructor(@inject('datasources.config.db') dsConfig: DataSource) { + super(dsConfig); + } +} +``` diff --git a/docs/site/Glossary.md b/docs/site/Glossary.md index 94ad6439ba2c..6585b6f0f01c 100644 --- a/docs/site/Glossary.md +++ b/docs/site/Glossary.md @@ -23,7 +23,7 @@ values for writing web applications and APIs. For more information, see **Controller**: The implementation of API endpoints. **DataSource**: A named configuration for a Connector instance that represents -data in an external system. +data in an external system. For more information, see [DataSource](DataSource.md). **Element:** The building blocks of a Sequence, such as route, params, and result. For more information, see [Sequence](Sequence.md#elements). diff --git a/docs/site/sidebars/lb4_sidebar.yml b/docs/site/sidebars/lb4_sidebar.yml index d8a9aa9920df..3d5c2ee827b6 100644 --- a/docs/site/sidebars/lb4_sidebar.yml +++ b/docs/site/sidebars/lb4_sidebar.yml @@ -78,6 +78,10 @@ children: url: Controllers.html output: 'web, pdf' + - title: 'DataSources' + url: DataSources.html + output: 'web, pdf' + - title: 'Routes' url: Routes.html output: 'web, pdf' @@ -127,6 +131,10 @@ children: url: Controller-generator.html output: 'web, pdf' + - title: 'DataSource generator' + url: DataSource-generator.html + output: 'web, pdf' + - title: 'Extension generator' url: Extension-generator.html output: 'web, pdf' diff --git a/docs/site/tables/lb4-artifact-commands.html b/docs/site/tables/lb4-artifact-commands.html index c142ba694ee3..580754b3fc1b 100644 --- a/docs/site/tables/lb4-artifact-commands.html +++ b/docs/site/tables/lb4-artifact-commands.html @@ -6,16 +6,24 @@ - - - - - + + + + + + + - - + + + + + + + + + + +
CommandsDescriptionSee
CommandsDescriptionSee
lb4 controller - Add a new controller to a LoopBack 4 application - Controller generator -
lb4 controllerAdd a new controller to a LoopBack 4 applicationController generator
lb4 datasourceAdd a new datasource to a LoopBack 4 applicationDataSource generator
diff --git a/docs/site/todo-tutorial-datasource.md b/docs/site/todo-tutorial-datasource.md index 34bd54bf0d96..1800bc57f250 100644 --- a/docs/site/todo-tutorial-datasource.md +++ b/docs/site/todo-tutorial-datasource.md @@ -23,38 +23,22 @@ create a datasource definition to make this possible. ### Building a Datasource -Create a new folder in the root directory of the project called `config`, and -then inside that folder, create a `datasources.json` file. For the purposes of -this tutorial, we'll be using the memory connector provided with the Juggler. - -#### config/datasources.json - -```json -{ - "name": "db", - "connector": "memory", - "file": "./data/db.json" -} -``` - -Inside the `src/datasources` directory create a new file called `db.datasource.ts`. This file will create -a strongly-typed export of our datasource using the `juggler.DataSource`, -which we can consume in our application via injection. - -#### src/datasources/db.datasource.ts - -```ts - -import * as path from 'path'; -import {juggler} from '@loopback/repository'; - -const dsConfigPath = path.resolve( - __dirname, - '../../../config/datasources.json', -); -const config = require(dsConfigPath); - -export const db = new juggler.DataSource(config); +From inside the project folder, we'll run the `lb4 datasource` command to +create a DataSource. For the purposes of this tutorial, we'll be using the +memory connector provided with the Juggler. + +```sh +lb4 datasource +? Datasource class name: db +? Select the connector for db: In-memory db (supported by StrongLoop) +? window.localStorage key to use for persistence (browser only): +? Full path to file for persistence (server only): ./data/db.json + + create src/datasources/ds.datasource.json + create src/datasources/ds.datasource.ts + update src/datasources/index.ts + +Datasource ds is now created in src/datasources/ ``` Create a `data` folder in the applications root and add a new file called `db.json` contain and example database.