Creatio development guide
PDF
Описание платформы

Создание Angular-компонента для использования в Creatio

Glossary Item Box

Общие сведения

Для встраивания Angular компонентов в приложение Creatio используется функциональность Angular Elements. Angular Elements - это npm пакет, который позволяет упаковывать Angular компоненты в Custom Elements и определять новые HTML-элементы со стандартным поведением (custom elements является частью стандарта Web-Components).

Создание кастомного Angular компонента

Шаг 1. Настроить окружение для разработки компонентов средствами Angular CLI

Для этого установите:

  1. Node.js® и npm package manager
  2. Angular CLI . Чтобы установить Angular CLI выполните в консоли команду: npm install -g @angular/cli

Шаг 2. Создать Angular приложение

Выполните в консоли команду ng new и укажите имя приложения, например my-app:

ng new my-app

Шаг 3. Установить пакет Angular Elements

Из папки приложения, созданного на предыдущем шаге, выполните в консоли команду:

ng add @angular/elements

Шаг 4. Зарегистрировать Angular Component как Custom Element

Чтобы настроить трансформацию компонента в кастомный HTML-элемент нужно внести изменения в файл app.module.ts:

  1. Добавьте импорт модуля createCustomElement.
  2. В модуле в секции entryComponents укажите имя компонента.
  3. В методе ngDoBootstrap зарегистрируйте компонент под html-тегом.
import { BrowserModule } from "@angular/platform-browser";
import { NgModule, DoBootstrap, Injector, ApplicationRef } from "@angular/core";
import { createCustomElement } from "@angular/elements";
import { AppComponent } from "./app.component";
@NgModule({
    declarations: [AppComponent],
    imports: [BrowserModule],
    entryComponents: [AppComponent]
})
export class AppModule implements DoBootstrap {
    constructor(private injector: Injector) {
    }
    ngDoBootstrap(appRef: ApplicationRef): void {
        const component: any = createCustomElement(AppComponent, { injector: this.injector });
        customElements.define("my-component", component);
    }
}

В файле app.component.ts укажите соответствующий html-тег:

@Component({
    selector: "my-component",
    templateUrl: "./app.component.html",
    styleUrls: ["./app.component.css"]
})

Шаг 5. Выполнить сборку приложения

Для уменьшения объема используемой памяти при создании кастомных элементов и подключения их в Creatio, реализована возможность использования единого ядра Angular. Используя инструмент ngx-build-plus необходимо изменить механизм сборки созданного Angular-приложения таким образом, чтобы все зависимости сохранялись отдельно от бизнес-логики элемента. Бизнес-логика будет сохраняться в файл main.js, который в будущем нужно будет подключить к пакету Creatio. Зависимости ядра Angular уже включены в ядро Creatio.

Чтобы использовать описанный механизм подключите инструмент ngx-build-plus, выполнив команду:

ng add ngx-build-plus

Затем установите в файле angular.json механизм сборки ngx-build-plus:build:

"architect": {
    "build": {
        "builder": "ngx-build-plus:build",
        ...
        "configurations": {
            "production": {
                ...
                "outputHashing": "none",
                ...
            }
        }
    }
}

В результате подключения инструмента ngx-build-plus будет добавлен файл webpack.externals.js. Этот файл содержит перечень зависимостей, которые не будут включены в сборку.

В механизме единого ядра используются следующие зависимости:

module.exports = {
    "externals": {
        "rxjs": "rxjs",
        "@angular/core": "ng.core",
        "@angular/common": "ng.common",
        "@angular/common/http": "ng.common.http",
        "@angular/platform-browser": "ng.platformBrowser",
        "@angular/platform-browser-dynamic": "ng.platformBrowserDynamic",
        "@angular/compiler": "ng.compiler",
        "@angular/elements": "ng.elements"
    }
}

Выполните сборку с учетом исключения зависимостей с помощью команды:

ng build --extra-webpack-config webpack.externals.js --prod --single-bundle

Подключение Custom Element в Creatio

Созданный в результате сборки файл main.js необходимо встроить в пакет Creatio как файловый контент. Подробнее об этом в статье "Использование файлового контента в пакетах".

Шаг 1. Разместить файл в статическом контенте пакета

Для этого скопируйте файл в папку [Название кастомного пакета]\Files\src\js, например, MyPackage\Files\src\js.

Шаг 2. Установить зависимость от единого ядра Angular

В файле files\src\js\bootstrap.js объявите зависимость созданного компонента от общего модуля для использования angular elements - ng-core.

Для этого необходимо в bootstrap объявить его зависимость от ng-core (общий модуль для использования angular elemetns):

(function() {
    require.config({
        paths: {
            "MyComponent": Terrasoft.getFileContentUrl("MyPackage", "src/js/my-component.js"),
        },
        shim: {
            "MyComponent": {
                deps: ["ng-core"]
            }
        }
    });
})();

Для загрузки bootstrap укажите путь к данному файлу. Для этого создайте descriptor.json в MyPackage\Files:

{
    "bootstraps": [
        "src/js/bootstrap.js"
     ]
}

Выполните загрузку из файловой системы и компиляцию.

Шаг 3. Выполнить загрузку компонента в необходимой схеме/модуле

Создайте в пакете схему или модуль, в котором должен быть использован созданный кастомный элемент и выполните его загрузку в блоке подключения зависимостей модуля:

define("CustomModule", ["MyComponent"], function() {

Шаг 4. Создать html элемент и добавить его в модель DOM

Ниже пример кода модуля, для добавления кастомного элемента my-component в модель DOM страницы Creatio:

/**
 * @inheritDoc Terrasoft.BaseModule#render
 * @override
 */
render: function(renderTo) {
   this.callParent(arguments);
   const component = document.createElement("my-component");
   component.setAttribute("id", this.id);
   renderTo.appendChild(component);
}

Работа с данными

Передача данных в Angular компонент происходит через публичные свойства/поля помеченные декоратором @Input

ВАЖНО

Свойства, описанные в camelCase, без указания в декораторе явного имени, будут переведены в html атрибуты в kebab-case.

Пример создания свойства компонента (app.component.ts):

@Input('value')
public set value(value: string) {
   this._value = value;
}

Пример передачи данных в компонент (CustomModule.js):

/**
 * @inheritDoc Terrasoft.BaseModule#render
 * @override
 */
render: function(renderTo) {
   this.callParent(arguments);
   const component = document.createElement("my-component");
   component.setAttribute("value", 'Hello');
   renderTo.appendChild(component);
}

Получение данных от компонента реализовано через механизм событий. Для этого необходимо публичное поле (тип EventEmmiter) пометить декоратором @Output. Для инициализации события необходимо у поля вызвать метод emit(T) и передать необходимые данные.

Пример реализации события в компоненте (app.component.ts):

/**
 * Emits item click.
 */
@Output() itemClick = new EventEmitter<any>();
 
/**
 * Handles item click.
 * @param eventData - Event data.
 */
handleItemClick(eventData: any) {
   this.itemClick.emit(eventData);
}

Пример обработки события в Creatio (CustomModule.js):

/**
 * @inheritDoc Terrasoft.Component#initDomEvents
 * @override
 */
initDomEvents: function() {
   this.callParent(arguments);
   const el = this.component;
   if (el) {
      el.on("itemClick", this.onItemClickHandler, this);
   }
}
© Terrasoft 2002-2020.

Был ли данный материал полезен?

Как можно улучшить эту статью?