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.2.0

1. Creation Angular project

Створіть стандартний ангуляр проект, використовуючи Angular CLI:

 ng new <app-name>

Примітка:Вам потрібно включити Routing у процесі створення проекту або додати його вручну пізніше.

2. Adding dependencies

@natec/mef-dev-platform-connector

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

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

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

ngx-build-plus

Для збірки плагіна ми використовуємо ресурси, надані ngx-build-plus.

ng add ngx-build-plus

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

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. Щоб внести зміни, слід дотримуватися таких кроків:

// 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>
...

При використанні CLI для публікації важливо оновити властивість name у файлі package.json, щоб вона відповідала бажаному імені проекту. Крім того, вам слід перевірити, що ім'я проекту правильно налаштовано у файлі angular.json Забезпечивши узгодженість між іменем проекту, вказаним у файлі package.json, і конфігурацією у файлі angular.json, ви можете уникнути можливих проблем під час процесу публікації.

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:[
            // пропишіть шляхи тут
        ]
    }
]);
...

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.

Щоб згенерувати файл специфікації, виконайте наступну команду:

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, як показано в прикладі

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

7. Build and deploy

Щоб опублікувати нову версію, чи створити новий плагін, ви можете скористатися наступними опціями: інтерфейс командного рядка (CLI) (автоматизований) та ручний режим.

Ми настійно рекомендуємо використовувати інтерфейс командного рядка (CLI), оскільки він допомагає прискорити розробку.

CLI Publication

metadata.json

Для публікації за допомогою інтерфейсу командного рядка (CLI) потрібно створити файл з назвою metadata.json у корені проекту. Він містить основну інформацію про плагін. Важливо зазначити, що публікація може не тільки відправляти нову версію, але й реєструвати новий плагін. У разі реєстрації нового плагіна важливо правильно визначити параметри name та serviceType, а при необхідності pluginMefName, оскільки після реєстрації їхні значення не можуть бути змінені. Тому змінити ці параметри в майбутньому (під час оновлення версій) буде неможливо.

serviceType

pluginMefName

Використовується тільки для реєстрації плагінів типу APIUI. Пізніше (після успішної реєстрації) воно може не використовуватися.

Нижче наведено приклад існуючого файлу з поясненнями полів.

{
  "name": "Simple plugin example",      // Відображене ім'я плагіна
  "serviceType": "UI",                  // Лише додаток із інтерфейсом користувача
  //"pluginMefName": "TestPlugin",      // Тільки для плагінів типу APIUI або API
  "description": "Lorem ipsum",         // Короткий опис функціональності плагіна
  "dependencies": [],                   // Використані для включення попередньо завантаженого бекенду плагіна
  "config":{
    "routesUI":[                        // Збережені маршрути, відображені у меню
      {
          "lang":"en",
          "routerLink":"test",
          "label":"test"
      }
    ]
  },
  "externalUrl": null,                  // Зовнішній URL плагіна
  "configuration": null                 // Конфігурація плагіна
}

CLI Scripts

Існує два скрипти для автоматичної збірки і публікації. Для зручності, в цьому проекті наведено готові npm-скрипти:

"generate-version-file": "npm explore @natec/mef-dev-platform-connector -- npm run generate-version-file",
"build:plugin": "npm run generate-version-file && ng build --configuration production --output-hashing none --single-bundle",
"publish": "npm explore @natec/mef-dev-platform-connector -- npm run mef-dev-publish",

Якщо файл metadata.json сформований правильно, після виконання команди

npm run publish

плагін буде успішно опубліковано.

Useful links

Інструкції з реєстрації плагіна на платформі можна знайти за наступним спосиланням