Файловый контент пакетов

1. Создать модуль с локализуемыми ресурсами 

Для перевода ресурсов на разные языки рекомендуется использовать отдельный модуль с локализуемыми ресурсами, созданный встроенными инструментами Creatio в разделе [ Конфигурация ] ([ Configuration ]).

define("Module1", ["Module1Resources"], function(res) {
  return res;
});

2. Импортировать модуль локализуемых ресурсов 

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

define("MyPackage-MyModule", ["Module1"], function(module1) {
  console.log(module1.localizableStrings.MyString);
});

i18n — это плагин для AMD-загрузчика (например, RequireJS), предназначенный для загрузки локализуемых строковых ресурсов. Исходный код плагина можно найти в GitHub-репозитории.

1. Добавить плагин 

Добавьте плагин в папку с *.js-файлами исходных кодов ..\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\MyPackage1\content\js\i18n.js.

Здесь MyPackage1 — рабочая папка пакета MyPackage1.

2. Создать папку с локализуемыми ресурсами 

Создайте папку ..\MyPackage1\content\nls и добавьте в нее *.js-файл с локализуемыми ресурсами.

Можно добавлять несколько *.js-файлов с локализуемыми ресурсами. Имена файлов могут быть произвольными. Содержимое файлов — AMD модули, которые содержат объекты.

Структура объектов AMD модулей:

• Поле root.

  Поле содержит коллекцию "ключ-значение", где ключ — это название локализуемой строки, а значение — локализуемая строка на языке по умолчанию. Значение будет использоваться, если запрашиваемый язык не поддерживается.

• Поля культур.

  В качестве имен полей установите стандартные коды поддерживаемых культур (например, en-US, ru-RU), а значение имеет логический тип (true — поддерживаемая культура включена, false — поддерживаемая культура отключена).

Ниже представлен пример файла ..\MyPackage1\content\js\nls\ContactSectionV2Resources.js.

define({
    "root": {
        "FileContentActionDescr": "File content first action (Default)",
        "FileContentActionDescr2": "File content second action (Default)"
    },
    "en-US": true,
    "ru-RU": true
});;

3. Создать папки культур 

В папке ..\MyPackage1\content\nls создайте папки культур. В качестве имен папок установите код той культуры, локализация которой будет в них размещена (например, en-US, ru-RU).

Структура папки MyPackage1 с русской и английской культурами представлена ниже.

content
    nls
        en-US
        ru-RU

4. Добавить файлы с локализуемыми ресурсами 

В каждую созданную папку локализации поместите такой же набор *.js-файлов с локализуемыми ресурсами, как и в корневой папке ..\MyPackage1\content\nls. Содержимое файлов — AMD модули, объекты которых являются коллекциями "ключ-значение", где ключ — это наименование локализуемой строки, а значение — строка на языке, соответствующем названию папки (коду культуры).

Например, если поддерживаются только русская и английская культуры, то создайте два файла ContactSectionV2Resources.js.

define({
    "FileContentActionDescr": "File content first action",
    "FileContentActionDescr2": "File content second action"
});

define({
    "FileContentActionDescr": "Первое действие файлового контента"    
});

Поскольку для русской культуры перевод строки "FileContentActionDescr2" не указан, то будет использовано значение по умолчанию — "File content second action (Default)".

5. Отредактировать файл bootstrap.js 

Чтобы отредактировать файл bootstrap.js:

1. Подключите плагин i18n, указав его название в виде псевдонима i18n в конфигурации путей RequireJS и прописав соответствующий путь к нему в свойстве paths.
2. Укажите плагину культуру, которая является текущей для пользователя. Для этого свойству config объекта конфигурации библиотеки RequireJS присвойте объект со свойством i18n, которому, в свою очередь, присвойте объект со свойством locale и значением, полученным из глобальной переменной Terrasoft.currentUserCultureName (код текущей культуры).
3. Для каждого файла с ресурсами локализации укажите соответствующие псевдонимы и пути в конфигурации путей RequireJS. При этом псевдоним должен являться URL-путем относительно директории nls.

(function() {
    require.config({
        paths: {            
            "MyPackage1-Utilities": Terrasoft.getFileContentUrl("MyPackage1", "content/js/Utilities.js"),
            "MyPackage1-ContactSectionV2": Terrasoft.getFileContentUrl("MyPackage1", "content/js/ContactSectionV2.js"),
            "MyPackage1-CSS": Terrasoft.getFileContentUrl("MyPackage1", "content/css/MyPackage.css"),
            "MyPackage1-LESS": Terrasoft.getFileContentUrl("MyPackage1", "content/less/MyPackage.less"),
            "i18n": Terrasoft.getFileContentUrl("MyPackage1", "content/js/i18n.js"),
            "nls/ContactSectionV2Resources": Terrasoft.getFileContentUrl("MyPackage1", "content/js/nls/ContactSectionV2Resources.js"),
            "nls/ru-RU/ContactSectionV2Resources": Terrasoft.getFileContentUrl("MyPackage1", "content/js/nls/ru-RU/ContactSectionV2Resources.js"),
            "nls/en-US/ContactSectionV2Resources":  Terrasoft.getFileContentUrl("MyPackage1", "content/js/nls/en-US/ContactSectionV2Resources.js")
        },
        config: {
            i18n: {
                locale: Terrasoft.currentUserCultureName
            }
        }
    });
})();

6. Использовать ресурсы в клиентском модуле 

Чтобы использовать ресурсы в клиентском модуле, укажите в массиве зависимостей модуль с ресурсами с префиксом "i18n!".

Ниже представлен пример использования локализуемой строки FileContentActionDescr в качестве заголовка для нового действия раздела [ Контакты ] ([ Contacts ]).

define("MyPackage1-ContactSectionV2", ["i18n!nls/ContactSectionV2Resources", 
    "css!MyPackage1-CSS", "less!MyPackage1-LESS"], function(resources) {
    return {
        methods: {
            getSectionActions: function() {
                var actionMenuItems = this.callParent(arguments);
                actionMenuItems.addItem(this.getButtonMenuItem({"Type": "Terrasoft.MenuSeparator"}));
                actionMenuItems.addItem(this.getButtonMenuItem({
                    "Click": {"bindTo": "onFileContentActionClick"},
                    "Caption": resources.FileContentActionDescr
                }));
                return actionMenuItems;
            },
            onFileContentActionClick: function() {
                console.log("File content clicked!")
            }
        },
        diff: /**SCHEMA_DIFF*/[]/**SCHEMA_DIFF*/
    }
});

Файловый контент позволяет использовать при разработке клиентской функциональности компилируемые в JavaScript языки, например, TypeScript. Подробнее о TypeScript можно узнать на сайте https://www.typescriptlang.org.

Установка TypeScript 

Одним из способов установки инструментария TypeScript является использование менеджера пакетов NPM для Node.js. Для этого необходимо выполнить в консоли Windows следующую команду:

npm install -g typescript

Исходный код 

Пакет с реализацией примера можно скачать по ссылке.

Алгоритм реализации примера 

1. Перейти в режим разработки в файловой системе 

2. Создать структуру хранения файлового контента 

Общий принцип создания рекомендуемой структуры хранения файлового контента:

1. В выгруженном в файловую систему пользовательском пакете создайте каталог Files.
2. В каталог Files добавьте папку src, а внутри нее создайте подкаталог js.
3. В каталог Files добавьте файл descriptor.json.
   descriptor.json

   Код скопирован

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

4. В каталог Files\src\js добавьте файл bootstrap.js.
   bootstrap.js

   Код скопирован

   (function() {
       require.config({
           paths: {
               "LettersOnlyValidator": Terrasoft.getFileContentUrl("sdkTypeScript", "src/js/LettersOnlyValidator.js")
           }
       });
   })();

3. Реализовать класс валидации значения на языке TypeScript 

В каталоге Files\src\js создайте файл Validation.ts, в котором объявите интерфейс StringValidator.

interface StringValidator {
    isAcceptable(s: string): boolean;
}
export = StringValidator;

В этом же каталоге создайте файл LettersOnlyValidator.ts. Объявите в нем класс LettersOnlyValidator, реализующий интерфейс StringValidator.

// Импорт модуля, в котором реализован интерфейс StringValidator.
import StringValidator = require("Validation");
 
// Создаваемый класс должен принадлежать пространству имен (модулю) Terrasoft.
module Terrasoft {
    // Объявление класса валидации значений.
    export class LettersOnlyValidator implements StringValidator {
        // Регулярное выражение, допускающее использование только буквенных символов.
        lettersRegexp: any = /^[A-Za-z]+$/;
        // Валидирующий метод.
        isAcceptable(s: string) {
            return !Ext.isEmpty(s) && this.lettersRegexp.test(s);
        }
    }
}
// Создание и экспорт экземпляра класса для require. 
export = new Terrasoft.LettersOnlyValidator();

4. Выполнить компиляцию исходных кодов TypeScript в исходные коды JavaScript 

Для настройки компиляции добавьте в каталог Files\src\js конфигурационный файл tsconfig.json.

{
    "compilerOptions":
    {
        "target": "es5",
        "module": "amd",
        "sourceMap": true
    }
}

В консоли Windows перейдите в каталог Files\src\js и выполните команду tsc.

В результате выполнения компиляции в каталоге Files\src\js будут созданы JavaScript-версии файлов Validation.ts и LettersOnlyValidator.ts, а также *.map-файлы, облегчающие отладку в браузере.

Содержимое файла LettersOnlyValidator.js, который будет использоваться в Creatio, получено автоматически.

define(["require", "exports"], function (require, exports) {
    "use strict";
    var Terrasoft;
    (function (Terrasoft) {
        var LettersOnlyValidator = /** @class */ (function () {
            function LettersOnlyValidator() {
                this.lettersRegexp = /^[A-Za-z]+$/;
            }
            LettersOnlyValidator.prototype.isAcceptable = function (s) {
                return !Ext.isEmpty(s) && this.lettersRegexp.test(s);
            };
            return LettersOnlyValidator;
        }());
        Terrasoft.LettersOnlyValidator = LettersOnlyValidator;
    })(Terrasoft || (Terrasoft = {}));
    return new Terrasoft.LettersOnlyValidator();
});
//# sourceMappingURL=LettersOnlyValidator.js.map

5. Выполнить генерацию вспомогательных файлов 

Для генерации вспомогательных файлов _FileContentBootstraps.js и FileContentDescriptors.js выполните следующие действия:

1. Перейдите в раздел [ Конфигурация ] ([ Configuration ]).
2. Выполните загрузку пакетов из файловой системы (действие [ Обновить пакеты из файловой системы ] ([ Update packages from file system ])).
3. Выполните компиляцию приложения (действие [ Компилировать все ] ([ Compile all items ])).

   На заметку. Этот шаг необходимо выполнять для применения изменений в файле bootsrtap.js. Для его выполнения также можно использовать утилиту WorkspaceConsole.

6. Использовать валидатор в схеме Creatio 

В разделе [ Конфигурация ] ([ Configuration ]):

1. Выполните загрузку пакетов из файловой системы (действие [ Обновить пакеты из файловой системы ] ([ Update packages from file system ])).
2. Cоздайте замещающую схему страницы редактирования записи контрагента.
   
3. Выполните выгрузку пакетов в файловую систему (действие [ Выгрузить пакеты в файловую систему ] ([ Download packages to file system ])).
4. В файловой системе измените файл ..\sdkTypeScript\Schemas\AccountPageV2\AccountPageV2.js.
   ..\sdkTypeScript\Schemas\AccountPageV2\AccountPageV2.js

   Код скопирован

   // Объявление модуля и его зависимостей.
   define("AccountPageV2", ["LettersOnlyValidator"], function(LettersOnlyValidator) {
       return {
           entitySchemaName: "Account",
           methods: {
               // Метод валидации.
               validateMethod: function() {
                   // Определение правильности заполнения колонки AlternativeName.
                   var res = LettersOnlyValidator.isAcceptable(this.get("AlternativeName"));
                   // Вывод результата пользователю.
                   Terrasoft.showInformation("Is 'Also known as' field valid: " + res);
               },
               // Переопределение метода родительской схемы, вызываемого при сохранении записи.
               save: function() {
                   // Вызов метода валидации.
                   this.validateMethod();
                   // Вызов базовой функциональности.
                   this.callParent(arguments);
               }
           },
           diff: /**SCHEMA_DIFF*/ [] /**SCHEMA_DIFF*/
       };
   });

После сохранения файла с исходным кодом схемы и обновления страницы приложения на странице редактирования контрагента при сохранении записи будет выполняться валидация и отображаться соответствующее предупреждение.

Неправильно заполненное поле

Правильно заполненное поле

Для встраивания 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 выполните в системной консоли команду:

   Установка Angular CLI

   Пример установки Angular CLI версии 8

   Код скопирован

   npm install -g @angular/cli

   Код скопирован

   npm install -g @angular/cli@8

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

Выполните в консоли команду ng new и укажите имя приложения, например angular-element-test.

ng new angular-element-test --style=scss

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

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

ng add @angular/elements

4. Создать компонент Angular

Чтобы создать компонент выполните в консоли команду.

ng g c angular-element

5. Зарегистрировать компонент как Custom Element 

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

1. Добавьте импорт модуля createCustomElement.
2. В модуле в секции entryComponents укажите имя компонента.
3. В методе ngDoBootstrap зарегистрируйте компонент под HTML-тегом.
   app.module.ts

   Код скопирован

   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: [AngularElementComponent]
   })
   export class AppModule implements DoBootstrap {
       constructor(private injector: Injector) {
       }
       ngDoBootstrap(appRef: ApplicationRef): void {
           const el = createCustomElement(AngularElementComponent, { injector: this._injector });
           customElements.define('angular-element-component', el);
       }
   }

6. Выполнить сборку приложения 

1. При сборке проекта сгенерируются несколько *.js-файлов. Для простоты дальнейшего использования веб-компонента в Creatio, созданные после сборки файлы рекомендуется поставлять в одном файле. Для этого необходимо в корне приложения создать скрипт build.js.

   Пример build.js

   Код скопирован

   const fs = require('fs-extra');
   const concat = require('concat');
   const componentPath = './dist/angular-element-test/angular-element-component.js';
    
   (async function build() {
      const files = [
         './dist/angular-element-test/runtime.js',
         './dist/angular-element-test/polyfills.js',
         './dist/angular-element-test/main.js',
         './tools/lodash-fix.js',
      ].filter((x) => fs.pathExistsSync(x));
      await fs.ensureFile(componentPath);
      await concat(files, componentPath);
   })();

   Если в веб-компоненте используется библиотека lodash, то для ее работы в Creatio необходимо main.js (и при необходимости styles.js) объединять со скриптом, устраняющим конфликты по lodash. Для этого в корне Angular-проекта создаем папку tools и файл lodash-fix.js.

   lodash-fix.js

   Код скопирован

   window._.noConflict();

   Важно. Если Вы не используете библиотеку lodash, то файл lodash-fix.js создавать не нужно и строку './tools/lodash-fix.js' из масива files необходимо убрать.

   Дополнительно для выполнения скрипта в build.js необходимо установить в проекте пакеты concat и fs-extra как dev-dependency. Для этого выполните в командной строке команды:

   Установка дополнительных пакетов

   Код скопирован

   npm i concat -D
   npm i fs-extra -D

   По умолчанию для созданного приложения могут быть установлены настройки файла browserslist, которые создают сразу несколько сборок для браузеров, которые поддерживают ES2015, и для тех, которым нужен ES5. Для данного примера мы собираем Angular элемент для современных браузеров. 

   Пример browserslist

   Код скопирован

   # This file is used by the build system to adjust CSS and JS output to support the specified browsers below.
   # For additional information regarding the format and rule options, please see:
   # https://github.com/browserslist/browserslist#queries
    
   # You can see what browsers were selected by your queries by running:
   #   npx browserslist
    
   last 1 Chrome version
   last 1 Firefox version
   last 2 Edge major versions
   last 2 Safari major versions
   last 2 iOS major versions
   Firefox ESR
   not IE 11

   Важно. Если Вам необходимо поставлять веб-компонент в браузеры, которые не поддерживают ES2015, нужно либо править масив файлов в build.js, либо изменить target в tsconfig.json (target: "es5"). Внимательно проверяйте названия файлов после сборки в папке dist. Если они не совпадают с названиями в масиве build.js, их нужно изменить в файле.

2. Добавьте в package.json команды, которые отвечают за сборку элемента. В результате их выполнения, вся бизнес логика помещается в один файл angular-element-component.js, с которым мы будем работать далее.

   package.json

   Код скопирован

   ....
   "build-ng-element": "ng build --output-hashing none && node build.js",
   "build-ng-element:prod": "ng build --prod --output-hashing none && node build.js",
   ...

   Важно. Рекомендуем при разработке, выполнять сборку приложения без параметра --prod.

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

Созданный в результате сборки файл angular-element-component.js необходимо встроить в пакет Creatio как файловый контент.

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

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

2. Встроить билд в Creatio 

Для этого необходимо в файле bootstrap.js (пакета Creatio, куда Вы хотите загрузить веб-компонент) настроить конфиг с указанием пути к билду.

(function() {
    require.config({
        paths: {
            "angular-element-component": Terrasoft.getFileContentUrl("MyPackageName", "src/js/angular-element-component.js"),
        }
    });
})();

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

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

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

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

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

define("MyModuleName", ["angular-element-component"], function() {

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

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

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

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

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

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

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

/**
 * Emits btn click.
 */
@Output() btnClicked = new EventEmitter<any>();
 
/**
 * Handles btn click.
 * @param eventData - Event data.
 */
public onBtnClick(eventData: any) {
   this.btnClicked.emit(eventData);
}

Добавьте кнопку в angular-element.component.html.

<button (click)="onBtnClick()">Click me</button>

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

Использование Shadow DOM

Некоторые компоненты, созданные с помощью Angular и встроенные в Creatio могут быть сконфигурированы так, чтобы реализация компонента была закрыта от внешнего окружения так называемым Shadow DOM.
Shadow DOM — это механизм инкапсуляции компонентов внутри DOM. Благодаря ему, в компоненте есть собственное «теневое» DOM-дерево, к которому нельзя просто так обратиться из главного документа, у него могут быть изолированные CSS-правила и т. д.

Для использования Shadow DOM необходимо в декоратор компонента добавить свойство encapsulation: ViewEncapsulation.ShadowDom.

import { Component, OnInit, ViewEncapsulation } from '@angular/core';
 
@Component({
   selector: 'angular-element-component',
   templateUrl: './angular-element-component.html',
   styleUrls: [ './angular-element-component.scss' ],
   encapsulation: ViewEncapsulation.ShadowDom,
})
export class AngularElementComponent implements OnInit {
}

Создание Acceptance Tests для Shadow DOM

Shadow DOM создает проблему для тестирования компонентов в приложении с помощью приемочных cucumber тестов. К компонентам внутри Shadow DOM нельзя обратится через стандартные селекторы из корневого документа.
Для этого необходимо использовать shadow root как корневой документ и через него обращаться к элементам компонента.

Shadow root — корневая нода компонента внутри Shadow DOM.
Shadow host — нода компонента, внутри которой размещается Shadow DOM.

В классе BPMonline.BaseItem реализованы базовые методы по работе с Shadow DOM.