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