From 917757d2663c20f36c169ea5b56df3161c738fdc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miroslav=20Bajto=C5=A1?= Date: Mon, 18 May 2020 14:50:53 +0200 Subject: [PATCH] docs: migrate LB3 components contributing models MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create a first version of the migration guide describing the simplest use case where the model is not persisted. - Add a link to a follow-up issue where we will discuss advanced scenarios. Signed-off-by: Miroslav Bajtoš --- docs/site/migration/components/models.md | 66 +++++++++++++++++-- .../2020-04-how-to-migrate-lb3-components.md | 49 +++++++++++++- 2 files changed, 109 insertions(+), 6 deletions(-) diff --git a/docs/site/migration/components/models.md b/docs/site/migration/components/models.md index 705af60cb4bd..026d43e2e46f 100644 --- a/docs/site/migration/components/models.md +++ b/docs/site/migration/components/models.md @@ -6,8 +6,64 @@ sidebar: lb4_sidebar permalink: /doc/en/lb4/migration-extensions-models.html --- -{% include note.html content=" -This is a placeholder page, the task of adding content is tracked by the -following GitHub issue: -[loopback-next#3955](https://github.com/strongloop/loopback-next/issues/3955) -" %} +Please review the content in [Migrating models](../models/overview.md) first. +Going forward, we assume that you are already familiar with the differences +between LoopBack 3 Models and LoopBack 4 Entities & Repositories, and understand +how to migrate model-related functionality from a LoopBack 3 application to +LoopBack 4. + +## Import LoopBack 3 models + +The first step is to import LoopBack 3 model definitions into your LoopBack 4 +component. This will convert LB3 model JSON files into LB4 TypeScript classes, +as explained in +[Import Model definition](../models/core.md#import-model-definition) and +[Importing models from LoopBack 3 projects](../../Importing-LB3-models.md). + +1. Create a small LB3 app that is using your component. + +2. In your LB4 extension project, run `lb4 import-lb3-models ` + to import model(s) contributed by the component from the LB3 app you created + in the previous step. Change the base class of the imported model(s) from + `Entity` to `Model` if needed. + +## Migrate behavior-less models + +Sometimes, a LoopBack 3 model does not provide any behavior, it is just +describing the shape of data (e.g. data fields in a push notification object). +Such models can be converted to LoopBack 4 models as follows: + +1. Import the LoopBack 3 model to your LoopBack 4 project as explained in + [Import LoopBack 3 models](#import-loopback-3-models). + +2. Ensure that your component's main index file exports all models: + + ```ts + // src/index.ts + export * from './models'; + ``` + +3. Update your documentation to instruct users to import the models directly + from the extension, instead of relying on loopback-boot to pick them up. + + ```ts + import {MyModel} from 'my-extension'; + ``` + +4. Optionally, if you want your models to be injectable, add them to the + artifacts contributed by the extension. + + ```ts + import {MyModel} from './models'; + + export class MyComponent implements Component { + models: [MyModel]; + } + ``` + +## Advanced scenarios + +LoopBack 4 does not yet provide recipes for extensions sharing models together +with their persistence behavior and their REST APIs. Please join the discussion +in [loopback-next#5476](https://github.com/strongloop/loopback-next/issues/5476) +to let us know about your use cases and to subscribe for updates. diff --git a/docs/spikes/2020-04-how-to-migrate-lb3-components.md b/docs/spikes/2020-04-how-to-migrate-lb3-components.md index cb4a1dba055d..629495d551e4 100644 --- a/docs/spikes/2020-04-how-to-migrate-lb3-components.md +++ b/docs/spikes/2020-04-how-to-migrate-lb3-components.md @@ -220,7 +220,54 @@ See ### Migrate Models, Entities and Repositories -TBD +> Contribute custom models (Notification) describing shape of data expected by +> the services (Push service). These models are not backed by any datasource, +> they are primarily used to describe data fields. + +See +[Migrate behavior-less models](../site/migration/components/models.md#migrate-behavior-less-models). + +> Contribute custom entities (Application, Installation) to be persisted via +> CRUD, exposed via REST and possibly further customized by the app. +> Customization options include which datasource to use, the base path where +> REST API is exposed (e.g. `/api/apps` and `/api/devices`), additional fields +> (e.g. `Application.tenantId`) and changes in persistence behavior (e.g. via +> Operation Hooks) + +See +[loopback-next#5476](https://github.com/strongloop/loopback-next/issues/5476) + +> Add a custom Operation Hook to given models, with a config option to +> enable/disable this feature. The list of models can be provided explicitly in +> the component configuration or obtained dynamically via introspection (e.g. +> all models having a "belongsTo" relation with the Group model) + +See +[loopback-next#5476](https://github.com/strongloop/loopback-next/issues/5476) + +> Add new relations, e.g. between an app-provided entity `User` and a +> component-provided entity `File`. In this variant, the relation is added on +> small fixed number of models. + +See +[loopback-next#5476](https://github.com/strongloop/loopback-next/issues/5476) + +> A model mixing adding new relations (`hasMany ModelEvents`), installing +> Operation Hooks (to generate model events/audit log entries), adding new +> Repository APIs (for working with related model events). +> +> _(The mixin-based design may be difficult to accomplish in LB4, we may want to +> use introspection and a model setting instead. The trickier part is how to +> apply changes to models added after the component was mounted.)_ + +See +[loopback-next#5476](https://github.com/strongloop/loopback-next/issues/5476) + +> For all models with a flag enabled in model settings, setup a custom +> `afterRemote` hook to modify the HTTP response (e.g. add additional headers). + +See +[loopback-next#5476](https://github.com/strongloop/loopback-next/issues/5476) ### Migrate REST API