Skip to content

Commit

Permalink
docs(docs): update docs with datasource cli and booter content
Browse files Browse the repository at this point in the history
Signed-off-by: Taranveer Virk <[email protected]>
  • Loading branch information
virkt25 committed Jun 3, 2018
1 parent b0a5b3a commit 02bec9a
Show file tree
Hide file tree
Showing 9 changed files with 178 additions and 45 deletions.
34 changes: 34 additions & 0 deletions docs/site/Booting-an-Application.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
3 changes: 3 additions & 0 deletions docs/site/Concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
4 changes: 2 additions & 2 deletions docs/site/Controller-generator.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
55 changes: 55 additions & 0 deletions docs/site/DataSource-generator.md
Original file line number Diff line number Diff line change
@@ -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] [<name>]
```

### Options

`--connector` : Name of datasource connector

This can be a connector supported by LoopBack / Community / Custom.

{% include_relative includes/CLI-std-options.md %}

### Arguments

`<name>` - 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.
41 changes: 41 additions & 0 deletions docs/site/DataSources.md
Original file line number Diff line number Diff line change
@@ -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);
}
}
```
2 changes: 1 addition & 1 deletion docs/site/Glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
8 changes: 8 additions & 0 deletions docs/site/sidebars/lb4_sidebar.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -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'
Expand Down
28 changes: 18 additions & 10 deletions docs/site/tables/lb4-artifact-commands.html
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,24 @@
</head>

<table width="750">
<thead><tr>
<th width="200">Commands</th>
<th>Description</th>
<th width="200">See</th>
</tr></thead>
<thead>
<tr>
<th width="200">Commands</th>
<th>Description</th>
<th width="200">See</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>lb4 controller</code>
</td><td> Add a new controller to a LoopBack 4 application
</td><td> <a href="Controller-generator.html">Controller generator</a>
</td></tr>
<tr>
<td><code>lb4 controller</code></td>
<td>Add a new controller to a LoopBack 4 application</td>
<td><a href="Controller-generator.html">Controller generator</a></td>
</tr>

<tr>
<td><code>lb4 datasource</code></td>
<td>Add a new datasource to a LoopBack 4 application</td>
<td><a href="DataSource-generator.html">DataSource generator</a></td>
</tr>

</tbody></table>
48 changes: 16 additions & 32 deletions docs/site/todo-tutorial-datasource.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit 02bec9a

Please sign in to comment.