Создаем собственный Wasaby-модуль

Все рутинные операции по созданию инфраструктуры и тестированию приложения выполняются с помощью консольной утилиты wasaby-cli, которая позволяет автоматизировать данные процессы в режиме разработки.

Полная инструкция по всем вариантам использования wasaby-cli доступна на github.

Шаг 1: Установка wasaby-cli

Установка утилиты осуществляется через пакетный менеджер npm или yarn.

Важно

Cледующие команды актуальны для npm версий ниже 7.

  1. Создайте npm-пакет, выполнив консольную команду:
npm init
  1. Установите пакет wasaby-cli в качестве development зависимости. Перед выполнением команды ниже замените строку [xx.yyyy] на версию нужной вам ветви разработки например 20.4000. Установка через npm:
npm install git+https://github.com/saby/wasaby-cli.git#rc-[xx.yyyy] --save-dev

Шаг 2: Создание интерфейсного модуля

Создать модуль можно с помощью wasaby-cli, выполнив команду:

npx wasaby-cli --tasks=createModule --path=client/MyModule

Также интерфейсный модуль можно создать, используя Genie. Достаточно только создать .s3mod файл и заполнить его список зависимостей. Остальные шаги, описанные в статье по ссылке, выполнять не нужно.

Шаг 3: Установка зависимостей приложения

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

Для установки зависимостей приложения выполните команду:

npx wasaby-cli --tasks=initStore

При этом будут загружены все интерфейсный модули, от которых оно зависит.

Шаг 4: Создание контрола

Подробную документацию с описанием базового класса контрола Wasaby вы можете прочитать в соответствующем разделе. Скопировать пример простейшего контрола можно из папки ControlExample на github. Обратите внимание на то, что основной файл с исходным кодом контрола на TypeScript расположен в папке _process (имя вы можете дать любое, но папка должна называться с подчеркивания ("_")). TypeScript отвечает не только за реализацию исходного кода, но и за подключение зависимостей от wml-шаблонов и css-файлов.

// TypeScript
import {Control, IControlOptions, TemplateFunction} from 'UI/Base';
import controlTemplate = require('wml!ControlExample/_process/Diagram');
import 'css!ControlExample/process';


class Diagram extends Control<IControlOptions> {
    protected _template: TemplateFunction = controlTemplate;
}

export default Diagram;

Обратите внимание, что в корне модуля публикуется TypeScript-файл для объявления библиотеки файлов (в примере этого модуля файл process.ts).

// TypeScript
export {default as Diagram} from './_process/Diagram';

Зависимость именно от этого файла будут подключать потребители вашего контрола. Во время сборки в файл библиотеки будут запакованы все зависимые исходники.

При обращении из wml:

<!-- WML -->
<ControlExample.process:Diagram/>

Шаг 5.1: Создание демо-примера

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

Создайте интерфейсный модуль для демо-примеров, если он отсутствует. Имя такого модуля должно заканчиваться на "-demo", например "Examples-demo".

Внтутри модуля создайте демо-примеры. Каждый пример — это контрол, создание и конфигурация которого подчиняется общим правилам. Имя TS-файла контрола должно либо совпадать с именем папки, в которой он расположен, либо соответствовть имени Index.ts. В WML-файле контрола не должны использоваться шаблон веб-страницы SbisEnvUI.Bootstrap и контрол маршрутизации Router/router:Reference. Исходные файлы контролов запрещается размещать в корне интерфейсного модуля — только в отдельных папках.

Для запустка демо-стенда используйте команду initDevEnv.

npx wasaby-cli initDevEnv

Она подготовит окружение, поднимет демо-стенд и откроет разводящую в браузере. Пример разводящей:

Шаг 5.2: Создание прямого маршрута

Если в вашем интерфейсном модуле нужно обеспечить доступ к контролу по прямой ссылке, то опишите роутинг.

Для этого в корне модуля создайте файл Index.ts:

// TypeScript
import {Control, IControlOptions, TemplateFunction} from 'UI/Base';
import controlTemplate = require('wml!ControlExample/Index');

class Index extends Control<IControlOptions> {
    protected _template: TemplateFunction = controlTemplate;
}
export default Index;

И шаблон Index.wml для него со ссылкой на ваш контрол (строчка 9):

<!-- WML -->
<UI.Base:HTML
        attr:application="MyControl/Index"
        attr:rootapp="UI/Base:Document"
        scope="{{_options}}">
    <ws:bodyTemplate>
        <ws:partial template="{{bodyTemplate.content}}">
            <ws:bodyContent>
                <ControlExample.process:Diagram />
            </ws:bodyContent>
        </ws:partial>
    </ws:bodyTemplate>
</UI.Base:HTML>

Для доступа к контролу по произвольному маршруту необходимо определить карту маршрутов в корне модуля в файле router.json в формате "путь: имя модуля".

// router.json
{
   "/index.html" : "ControlExample"
}

Шаг 6: Сборка приложения

Сборка приложения осуществляется в отдельной папке с именем application. Для сборки выполните команду:

npx wasaby-cli --tasks=build

Для сборки с минимальным набором логов и выводов исключительно ошибок, используйте флаг --log-level=error. В результате будет выведен прогресс бар и ошибки, если они есть.

npx wasaby-cli --tasks=build --log-level=error

При этом будут собраны ресурсы приложения, сконвертированые в исполняемый браузером/Node.js формат. Например, скомпилируются .less и .ts файлы.