Creation of UI package "from scratch"

Передумови. Перед початком потрібно встановити nodejs та @angular/cli*

Дана інструкція носить інформаційний характер, для кращого розуміння принципу побудови плагіна. Для економії часу та уникнення помилок, радимо, використовувати шаблони проектів або генератор проектів, що знаходиться у межах платформи

В рамках даної інструкції описаний шлях створення так званого базового плагіна для платформи mef.dev technical preview. Базовий плагін він тому, що не матиме реалізацій коду бізнес-логіки. Його мета - технічне оформлення будь-якого початкового проекту для успішної роботи плагіна в межах платформи.

Примітка. Протестовано на таких версіях @angular/cli: 12.2.17, 13.3.8, 14.2.11, 15.2.8, 16.0.3

1. Creation Angular project

Створюємо стандартну Angular аплікацію:

Примітка. Вам потрібно підтвердити рутінг у проекті на етапі його створення, або ж вам потрібно буде додавати рутінг власноруч пізніше.
ng new <app-name>

2. Adding dependencies

@natec/mef-dev-platform-connector

В проекті в подальшому можна використовувати практично будь-які додаткові бібліотеки. Проте, для роботи на платформі потрібно використовувати @natec/mef-dev-platform-connector в якому зібраний основний функціонал роботи з платформою. Задля чого додаємо пакет:

   npm i @natec/mef-dev-platform-connector@14.0.0

Примітка. Важливо, щоб версія встановленого mef-dev-platform-connector відповідала версії ангуляру на вашому комп'ютері(Перевірити можна прописавши команду ng v у командному рядку). Табличку відношення версій ви можете переглянути за посиланням тут.

ngx-build-plus

Для збіки плагіна використовуються ресурси ngx-build-plus

ng add ngx-build-plus@^14.0.0

Примітка. Версія ngx-build-plus теж має відповідати версії встановленого ангуляру. Табличку відношення версій ви можете переглянути у таблиці нижче

Angular / CLI	ngx-build-plus
12 /12	ngx-build-plus@^12.0.0
13 /13	ngx-build-plus@^13.0.0
14 /14	ngx-build-plus@^14.0.0
15 /15	ngx-build-plus@^15.0.0
16 /16	ngx-build-plus@^16.0.0

3. Changing the base selector

При генерації проекту за допомогою @angular/cli генерується базова компонента AppComponent із селектором app-root. Нам потрібно його замінити на селектор нашого плагіну. Даний параметр резервуєтеся в межах платформи при створенні плагіну, і має назву FrontendPluginName. В прикладі нижче використовується назва проекту з package.json. Але це не обов'язково. Для зміни потрібно провести такі дії:

// src/app/app.component.ts
...
@Component({
selector:  'plugin-example', // 'app-root',
template:  '<router-outlet></router-outlet>', // <-- також замінюємо стандартний вміст
styleUrls: ['./app.component.scss']
...
})

// src/index.html
...
<body>
    <plugin-example></plugin-example>  <!-- <app-root></app-root> -->
</body>
...

4. Routing changes

Для коректної роботи роутінгів УСІ реальні шляхи повинні міститися в children секції.

Примітка. *В іншому випадку при навігації в межах плагіну буде змінюватися ВЕСЬ шлях (включно із навігацією платформи). Це не призведе до непрацездатності плагіна, проте подальше використання платформи буде непередбачуваним!*

Також, для правильної роботи навігації базові шляхи потрібно 'пропустити' через метод updatePluginsRoutes(Routes). Детальніше тут.

У результаті, оголошення шляхів виглядатиме наступним чином:

// src/app/app-routing.module.ts
import { PlatformHelper } from  '@natec/mef-dev-platform-connector';
...
// const  routes: Routes = [];
const  routes: Routes = PlatformHelper.updatePluginsRoutes([
    {
        path:"",
        children:[
            // insert routes here
        ]
    }
]);
...

5. Creating of first component

УВАГА! *Реалізація розмітки в AppComponent небажана. Для подальшого розвитку аплікації рекомендується весь функціонал вивести у власну структуру компонентів. Приклад

Для мінімальної роботи достатньо реалізувати один компонент:

ng g c test

Після чого його імпортувати та додати у маршрутизацію:

// src/app/app-routing.module.ts
import { PlatformHelper } from  '@natec/mef-dev-platform-connector';
import { TestComponent } from './test/test.component ';
...
// const  routes: Routes = [];
const  routes: Routes = PlatformHelper.updatePluginsRoutes([
    {
        path:"",
        children:[
            {
                path:"",
                redirectTo:"test",
                pathMatch:  'full',
            },
            {
                path:"test",
                component:  TestComponent
            }
        ]
    }
]);
...

6. Specification file version.json

Для завантаження на платформу в збірці повинен міститися файл специфікації. Він генерується скриптом, що знаходиться в @natec/mef-dev-platform-connector.

Насамперед, Вам потрібно створити у src папку environments , у яку в подальшому буде згенерований файл version.ts

Для генерації файлу специфікації необхідно виконати команду:

npm explore @natec/mef-dev-platform-connector -- npm run generate-version-file

Результат його виконання є генерація файлів у папці environments, що містять набір інформації про збірку плагіну.

Для копіювання файлу в результати збірки необхідно добавити шлях до нового ассету в файлі налаштувань:

// angular.json
...
"architect": {
    "build": {
        "options": {
            ...
            "assets": [
                "src/favicon.ico",
                "src/assets",
                "src/version.json" // <---    
            ]
...

Файл специфікації потрібно змінювати перед кожною збіркою для публікації. Хорошою практикою буде оформити npm scripts як в прикладі.

Також результат його роботи можна використовувати в межах аплікації. Приклад.

7. Build and deploy

Для збірки плагіна можна використовувати команду:

 ng build --output-hashing none --configuration production --single-bundle --output-path dist

Після чого вміст папки dist можна завантажувати на платформу.

Useful links

Інструкція про реєстрації плагіна на платформі: https://mef.dev/uk/dev_guides/upload_ui_plugin.md