- Plugin basics
- Introduction
- Platform overview
- Plugin guides
- First UI package
- Package registration
- First Backend package
- Portal package creation
- REST API
- REST API using
-
Request Formats
- HTTP GET: Getting a list of elements of type Entity
- HTTP GET: Getting a specific Element of the Entity Type
- HTTP PUT: Editing an Entity Type Element
- HTTP POST: Creating a new Element of Entity Types
- HTTP POST: Doing an Action for Element of Entity Types
- HTTP POST: Creating an new element Sub-Entity of Types
- HTTP DELETE: Deleting the element of Entity Types
- HTTP PATCH: Partially editing the element of Entity Types
- Handling Errors When Calling HTTP Methods
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
Важливо розуміти призначення поля serviceType; воно відповідає типу плагіна. | Значення | Опис | |-|-| | "UI" | Плагін містить лише додаток із інтерфейсом користувача без частини на стороні сервера | | "APIUI" | Плагін містить додаток із інтерфейсом користувача та серверною частиною |
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
Інструкції з реєстрації плагіна на платформі можна знайти за наступним спосиланням