Библиотечные проекты
Библиотечные проекты

Выпуск собственных библиотечных проектов

Введение

Подключение UI сторонних проектов в прикладной web-проект

Любой web-проект на платформе Q.Palette может быть собран в виде npm-пакета (opens in a new tab). Такие npm-пакеты могут быть подключены в другой проект в виде зависимости и упакованы в собранном виде в каталог assets прикладного UI-микросервиса. При подключении библиотек сторонних проектов необходимо гарантировать, что все взаимодействия, которые происходят с UI подключаемой библиотеки, будут работать при её использовании в различных прикладных web-проектах, вне зависимости от фреймворка этого проекта.

Типы взаимодействий:

  • Взаимодействие с бэкендом - в качестве бэкенда может выступать микросервис с именем, отличным от основного, но с теми же контрактами АПИ, поэтому необходимо предусмотреть параметризацию адреса вызовов АПИ с которыми происходит взаимодействие из данной UI-библиотеки
  • Дополнительные параметры определяющие специфику работы данной библиотеки при подключении к произвольному прикладному проекту - контракты методов и событий, которые предоставляет UI-библиотека.
  • Для использования библиотеки в прикладных проектах все контракты взаимодействия должны быть задокументированы. Рекомендуется использовать документацию в виде README.MD-файла в составе библиотеки.

Подключение UI-библиотеки в прикладной продукт

⚠️

Подключаемая библиотека должна быть опубликована в доступный репозиторий в виде NPM-пакета.

При подключении библиотеки в прикладной продукт нужно:

  • Добавить библиотеку нужной версии в зависимости web-проекта
  • В контроллере инициализировать библиотеку необходимыми параметрами контекста прикладного проекта (если требуется)
  • Доступные параметры контекста использования библиотеки определяются функционалом самой библиотеки и документируются в файле README.MD
  • Взаимодействие с функционалом библиотеки осуществляется посредством передачи событий, как при взаимодействии с q-web-component. Функционал определяется самой библиотекой и документируется в README.MD
  • В случае если функционал библиотеки взаимодействует с backend-сервисами необходимо предусмотреть возможность параметризации вызовов которые происходят из библиотеки.

Рекомендуется создавать дополнительный проект для библиотечного проекта и использовать его в основном проекте так же как npm-пакет. Это позволит вам выпускать более качественные пакеты, сразу же тестируя их на себе. Для того чтобы тестировать пакет локально, не выпуская beta-версии в nexus, используйте npm link (opens in a new tab).

Создание проекта библиотечного UI

⚠️

Обновитесь до Q.Palette 5.3.12 и выше для работы этого функционала.

⚠️

Имя нужно указывать в нижнем регистре в соответствии с сокращённым названием вашего проекта из QArcher! Примеры: qvrn, qbpm, qpuid...

Перейдите в корневую директорию вашего основного приложения (там, где angular.json) и выполните команду:

ng g app --style="scss" --routing=true --name="qname"

В корне появившегося проекта создайте файлpackage.json:

{
  "name": "@diasoft/qnameui-lib",
  "version": "0.0.1",
  "peerDependencies": {
    "@angular/common": "^12.2.0",
    "@angular/core": "^12.2.0",
    "@diasoft/qpalette-visual": "^5.3.11"
  }
}

Скопируйте зависимости вашего основного проекта в этотpackage.json. В будущем здесь должны будут оказаться все зависимости этого библиотечного проекта. Старайтесь класть зависимости в peerDependencies и реже использовать dependencies.

Там же создайте файлREADME.MD. В нём вы будете хранить инструкцию для использования вашего библиотечного проекта.

Превратите получившийся проект в Q.Palette-совместимый веб-компонент:

ng g @diasoft/qpalette-updater:qpalettize --name="qname"

В случае успешного завершения операции, в директории вашего проекта появится директория projects, внутри которой будет находиться ваш новый проект, который осталось превратить в npm-пакет.

Перейдите в angular.json и установите префикс для компонентов вашего библиотечного проекта:

{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "projects": {
    "qname": {
      "prefix": "qname"
    }
  }
}

Пометьте текущий проект как публичный

Для этого в поле lib-pbc файла package.json нужно указать название публикуемого проекта, команду для сборки и имя, под которым пакет будет опубликован:

"lib-pbc": [
      {
        "name": "qpalette-dev-portal",
        "buildCommand": "npm run prod",
        "publishedName": "@diasoft/qpalette-dev-portal-ui-lib"
      },
      ...
    ]
  • name - Название проекта, полученное на предыдущем этапе.
  • buildCommand - Команда для сборки проекта. В данном случае будет выполнена команда prod из раздела scripts файла package.json.
  • publishedName - Имя пакета, под которым проект будет опубликован в npm. Должно удовлетворять шаблону: @diasoft/q*-ui-lib, где * - любой непустой набор символов.

Публикация

Перейдите в главныйpackage.json, находящийся в корне (рядом сangular.json) и добавьте в секцию scripts следующую запись:

{
  "scripts": {
    "lib-pbc": [
      "qname"
    ]
  }
}

Использование библиотечного проекта

Для использования библиотечного проекта в своём проекте, необходимо установить его как обычный npm-пакет:

npm i @diasoft/qnameui-lib

Откройтеangular.jsonпроекта, в который хотели бы встроить библиотечный проект, найдите блок assets и добавьте в него копирование всей файлов пакета@diasoft/ name.value ui-libв директорию assets вашего приложения:

{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "projects": {
    "YOUR_PROJECT_NAME": {
      "architect": {
        "build": {
          "options": {
            "assets": [
              {
                "glob": "**/*",
                "input": "node_modules/@diasoft/qnameui-lib",
                "output": "assets/qname"
              }
            ]
          }
        }
      }
    }
  }
}

В нужном месте вашего приложения, подключите модульQWebComponentModuleи следующий код:

<q-web-component
    [endpoint]="endpoint"
    bundleUrl="/api/SERVICE/COMPONENT/assets/qname/main.js"
></q-web-component>

Где SERVICE — ваш сервис, а COMPONENT — ваш компонент, куда встраивается библиотечный проект. Эту информацию можно найти в menu.json

endpoint = {
  service: 'qname',
  component: 'qname',
  route: '',
  caption: '',
  properties: {
    // Здесь можно передать какие-то параметры, необходимые для инициализации библиотечного проекта
  }
};

В секцию properties можно передать какие-то данные. Для получения этих данных в библиотечном проекте, можно использовать

private initialProperties: {[k: string]: any} = QWebComponentModule.endpoint?.properties

Частный случай передачи properties — конфигурирование базового адреса API бэкенда. Разберём на примере:

{
  "properties": {
    "baseUrl": "/api/myService/myEndpoint"
  }
}

Здесь мы задаём базовый адрес в properties. Получим его внутри библиотечного проекта и тут же конфигурируем QUrlService:

import { DoBootstrap, NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { QUrlService } from '@diasoft/qpalette-urls';
import { QWebComponentModule } from '@diasoft/qpalette-visual';
...
 
export class ApiUrlService extends QUrlService {
}
 
@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    ...
  ],
  providers: [
    {
      provide: ApiUrlService,
      useFactory: () => new QUrlService(
        {
            baseUrl: QWebComponentModule.endpoint?.properties?.baseUrl, // Базовый адрес api из properties
            serviceName: 'myService' ,
          }
      )
    }
  ],
  bootstrap: []
})
export class AppModule implements DoBootstrap {
  constructor(...) {
  }
 
  public ngDoBootstrap(): void {
    ...
  }
}

Таким образом библиотечный проект будет обращаться к своему API в зависимости от его окружения.

Для передачи событий в библиотечный проект, используйте атрибут[data], а для получения —(events). Подробнее здесь

SSE-клиентКастомизация табличных библиотечных проектов