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

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

   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.