From e45f386478cc632a92b83e8dcee519b2eef367f3 Mon Sep 17 00:00:00 2001 From: Yaapa Hage Date: Wed, 26 Aug 2020 21:51:05 +0530 Subject: [PATCH] chore: docs Doc updates Signed-off-by: Yaapa Hage --- docs/site/Component.md | 31 ++++++++++++++ docs/site/Creating-components.md | 40 ++++++++++++------- docs/site/Extending-LoopBack-4.md | 18 ++++++++- packages/cli/generators/extension/index.js | 13 +++--- .../extension/templates/src/component.ts.ejs | 14 ++++++- .../extension/templates/src/index.ts.ejs | 2 + packages/core/src/component.ts | 2 +- 7 files changed, 96 insertions(+), 24 deletions(-) diff --git a/docs/site/Component.md b/docs/site/Component.md index ac41ca894b5a..0f631a48ce80 100644 --- a/docs/site/Component.md +++ b/docs/site/Component.md @@ -83,6 +83,37 @@ const app = new RestApplication(); app.component(AuthenticationComponent); ``` +## Official components + +Here is a list of components officially created and maintained by the LoopBack +team. + +- [@loopback/apiconnect](https://github.com/strongloop/loopback-next/tree/master/extensions/apiconnect) - An extension for IBM API Connect +- [@loopback/authentication](https://github.com/strongloop/loopback-next/tree/master/packages/authentication) - A LoopBack component for authentication support +- [@loopback/authentication-jwt](https://github.com/strongloop/loopback-next/tree/master/extensions/authentication-jwt) - Extension for the prototype of JWT + authentication +- [@loopback/authentication-passport](https://github.com/strongloop/loopback-next/tree/master/extensions/authentication-passport) - A package creating adapters between the + passport module and @loopback/authentication +- [@loopback/authorization](https://github.com/strongloop/loopback-next/tree/master/packages/authorization) - A LoopBack component for authorization support +- [@loopback/boot](https://github.com/strongloop/loopback-next/tree/master/packages/boot) - A collection of Booters for LoopBack 4 Applications +- [@loopback/booter-lb3app](https://github.com/strongloop/loopback-next/tree/master/packages/booter-lb3app) - A booter component for LoopBack 3 applications to + expose their REST API via LoopBack 4 +- [@loopback/context-explorer](https://github.com/strongloop/loopback-next/tree/master/extensions/context-explorer) - Visualize context hierarchy, bindings, + configurations, and dependencies +- [@loopback/cron](https://github.com/strongloop/loopback-next/tree/master/extensions/cron) - Schedule tasks using cron-like syntax +- [@loopback/extension-health](https://github.com/strongloop/loopback-next/tree/master/extensions/health) - An extension exposes health check related + endpoints with LoopBack 4 +- [@loopback/extension-logging](https://github.com/strongloop/loopback-next/tree/master/extensions/logging) - An extension exposes logging for Winston and + Fluentd with LoopBack 4 +- [@loopback/extension-metrics](https://github.com/strongloop/loopback-next/tree/master/extensions/metrics) - An extension exposes metrics for Prometheus with + LoopBack 4 +- [@loopback/pooling](https://github.com/strongloop/loopback-next/tree/master/extensions/pooling) - Resource pooling service for LoopBack 4 +- [@loopback/rest](https://github.com/strongloop/loopback-next/tree/master/packages/rest) - Expose controllers as REST endpoints and route REST API + requests to controller methods +- [@loopback/rest-crud](https://github.com/strongloop/loopback-next/tree/master/packages/rest-crud) - REST API controller implementing default CRUD semantics +- [@loopback/rest-explorer](https://github.com/strongloop/loopback-next/tree/master/packages/rest-explorer) - LoopBack's API Explorer +- [@loopback/typeorm](https://github.com/strongloop/loopback-next/tree/master/extensions/typeorm) - Adds support for TypeORM in LoopBack + ## Creating components Please refer to [Creating components](Creating-components.md) for more diff --git a/docs/site/Creating-components.md b/docs/site/Creating-components.md index 4d2f5798eca0..83fff992e382 100644 --- a/docs/site/Creating-components.md +++ b/docs/site/Creating-components.md @@ -441,23 +441,35 @@ app.find('repositories.*'); ## Configuring components -More often than not, the component may want to offer different value providers -depending on the configuration. For example, a component providing an email API -may offer different transports (stub, SMTP, and so on). +Components can be configured by an app by calling `this.configure()` in its +constructor, and the configuration object can be injected into the component +constructor using the `@config()` decorator. -Components should use constructor-level -[Dependency Injection](Context.md#dependency-injection) to receive the -configuration from the application. +{% include code-caption.html content="mycomponent.ts" %} ```ts -class EmailComponent { - constructor(@inject('config#components.email') config) { - this.providers = { - sendEmail: - this.config.transport == 'stub' - ? StubTransportProvider - : SmtpTransportProvider, - }; +export class MyComponent implements Component { + constructor( + @config() + options: MyComponentOptions = {enableLogging: false}, + ) { + if (options.enableLogging) { + // do logging + } else { + // no logging + } } } ``` + +{% include code-caption.html content="application.ts" %} + +```ts +... +// MyComponent.COMPONENT is the binding key of MyComponent +this.configure(MyComponent.COMPONENT).to({ + enableLogging: true, +}); +this.component(MyComponent); +... +``` diff --git a/docs/site/Extending-LoopBack-4.md b/docs/site/Extending-LoopBack-4.md index e63b906c23ac..20fa50112ac0 100644 --- a/docs/site/Extending-LoopBack-4.md +++ b/docs/site/Extending-LoopBack-4.md @@ -89,7 +89,7 @@ ctx.bind('utilities.PasswordHash').to(PasswordHasher) // Bind the UserController class as the user management implementation ctx.bind('controllers.UserController').toClass(UserController); -// Locate the an instance of UserController from the context +// Locate the instance of UserController from the context const userController: UserController = await ctx.get('controller.UserController'); // Run the login() const ok = await userController.login('John', 'MyPassWord'); @@ -190,7 +190,23 @@ An application-level component usually contributes: ### Learn from existing ones - [loopback4-example-log-extension](https://github.com/strongloop/loopback-next/tree/master/examples/log-extension) +- [@loopback/apiconnect](https://github.com/strongloop/loopback-next/tree/master/extensions/apiconnect) - [@loopback/authentication](https://github.com/strongloop/loopback-next/tree/master/packages/authentication) +- [@loopback/authentication-jwt](https://github.com/strongloop/loopback-next/tree/master/extensions/authentication-jwt) +- [@loopback/authentication-passport](https://github.com/strongloop/loopback-next/tree/master/extensions/authentication-passport) +- [@loopback/authorization](https://github.com/strongloop/loopback-next/tree/master/packages/authorization) +- [@loopback/boot](https://github.com/strongloop/loopback-next/tree/master/packages/boot) +- [@loopback/booter-lb3app](https://github.com/strongloop/loopback-next/tree/master/packages/booter-lb3app) +- [@loopback/context-explorer](https://github.com/strongloop/loopback-next/tree/master/extensions/context-explorer) +- [@loopback/cron](https://github.com/strongloop/loopback-next/tree/master/extensions/cron) +- [@loopback/extension-health](https://github.com/strongloop/loopback-next/tree/master/extensions/health) +- [@loopback/extension-logging](https://github.com/strongloop/loopback-next/tree/master/extensions/logging) +- [@loopback/extension-metrics](https://github.com/strongloop/loopback-next/tree/master/extensions/metrics) +- [@loopback/pooling](https://github.com/strongloop/loopback-next/tree/master/extensions/pooling) +- [@loopback/rest](https://github.com/strongloop/loopback-next/tree/master/packages/rest) +- [@loopback/rest-crud](https://github.com/strongloop/loopback-next/tree/master/packages/rest-crud) +- [@loopback/rest-explorer](https://github.com/strongloop/loopback-next/tree/master/packages/rest-explorer) +- [@loopback/typeorm](https://github.com/strongloop/loopback-next/tree/master/extensions/typeorm) ### Create your own extension diff --git a/packages/cli/generators/extension/index.js b/packages/cli/generators/extension/index.js index 9188c86c371b..7afa0c00998f 100644 --- a/packages/cli/generators/extension/index.js +++ b/packages/cli/generators/extension/index.js @@ -60,12 +60,6 @@ module.exports = class ExtensionGenerator extends ProjectGenerator { promptOptions() { if (this.shouldExit()) return; - const titleCase = - this.projectInfo.name.charAt(0).toUpperCase() + - this.projectInfo.name.slice(1); - this.projectInfo.optionsInterface = `${titleCase}Options`; - this.projectInfo.bindingsNamespace = `${titleCase}Bindings`; - this.projectInfo.defaultOptions = `DEFAULT_${this.projectInfo.name.toUpperCase()}_OPTIONS`; return super.promptOptions(); } @@ -75,6 +69,13 @@ module.exports = class ExtensionGenerator extends ProjectGenerator { } scaffold() { + const titleCase = + this.projectInfo.name.charAt(0).toUpperCase() + + this.projectInfo.name.slice(1); + this.projectInfo.optionsInterface = `${titleCase}Options`; + this.projectInfo.bindingsNamespace = `${titleCase}Bindings`; + this.projectInfo.defaultOptions = `DEFAULT_${this.projectInfo.name.toUpperCase()}_OPTIONS`; + return super.scaffold(); } diff --git a/packages/cli/generators/extension/templates/src/component.ts.ejs b/packages/cli/generators/extension/templates/src/component.ts.ejs index 29da0a07fca9..e2d7097bd9e6 100644 --- a/packages/cli/generators/extension/templates/src/component.ts.ejs +++ b/packages/cli/generators/extension/templates/src/component.ts.ejs @@ -1,8 +1,18 @@ -import {Component, ProviderMap} from '@loopback/core'; +import { + Application, + bind, + Component, + // eslint-disable-next-line @typescript-eslint/no-unused-vars + config, + ContextTags, + CoreBindings, + createBindingFromClass, + inject, +} from '@loopback/core'; import {<%= project.bindingsNamespace %>} from './keys' import {<%= project.defaultOptions %>, <%= project.optionsInterface %>} from './types'; -@bind({tags: {[ContextTags.KEY]: {<%= project.bindingsNamespace %>.COMPONENT}}) +@bind({tags: {[ContextTags.KEY]: <%= project.bindingsNamespace %>.COMPONENT}}) export class <%= project.componentName %> implements Component { constructor( @inject(CoreBindings.APPLICATION_INSTANCE) diff --git a/packages/cli/generators/extension/templates/src/index.ts.ejs b/packages/cli/generators/extension/templates/src/index.ts.ejs index bb824842ced8..a31115f3abee 100644 --- a/packages/cli/generators/extension/templates/src/index.ts.ejs +++ b/packages/cli/generators/extension/templates/src/index.ts.ejs @@ -1 +1,3 @@ export * from './component'; +export * from './keys'; +export * from './types'; diff --git a/packages/core/src/component.ts b/packages/core/src/component.ts index 7ef70aa3f943..a86868047b15 100644 --- a/packages/core/src/component.ts +++ b/packages/core/src/component.ts @@ -33,7 +33,7 @@ export interface ClassMap { } /** - * A component declares a set of artifacts so that they cane be contributed to + * A component declares a set of artifacts so that they can be contributed to * an application as a group */ export interface Component {