Разработка расширения с клиентским сервисом

Данный раздел посвящён созданию новых сервисов клиентского уровня. Сервисы предоставляют публичные методы, которые могут быть вызваны (с помощью функции получения сервиса) из клиентских расширений (скриптов, компонентов элементов управления). Программист может реализовать сервисы различного назначения.

Рекомендуется использовать сервис в одном клиентском расширении. Использование разработанного сервиса в другом расширении сопряжено со сложностями настройки сборки.

Создание расширения

Чтобы создать расширение, добавляющее новые сервисы, выполните приведенную далее инструкцию.

  1. Создайте проект клиентского расширения.

  2. Создайте в папке src файл TypeScript (.ts, .tsx) со следующим содержимым:

    import { $RequestManager } from "@docsvision/webclient/System/$RequestManager";
import { urlStore } from "@docsvision/webclient/System/UrlStore";
import { serviceName } from "@docsvision/webclient/System/ServiceUtils";

export class CardService {
    constructor(private services: $RequestManager) {
    }
    exists(cardId: string): Promise<boolean> { (1)
        let url = urlStore.urlResolver.resolveApiUrl("Exists", "CardService"); (2)
        url = url + "?cardId=" + cardId;
        return this.services.requestManager.get<boolean>(url);
    }
}

export type $CardService = { cardService: CardService };
export const $CardService = serviceName((s: $CardService) => s.cardService); (3)
    1 Функция exists проверяет существование карточки.
    2 Проверка выполняется с помощью серверной функции Exists контроллера CardService.
    3 Объявление сервиса $CardService.

    В данном коде реализован сервис CardService, содержащий единственную функцию exists, возвращающую признак существования карточки в системе Docsvision.

    При реализации собственного сервиса, используйте его объявление, по аналогии с приведенным примером, заменив CardService на название собственного сервиса.

  3. Измените содержимое файла Index.ts.

    import { $CardService, CardService } from "./WebService"; (1)
import { extensionManager } from "@docsvision/webclient/System/ExtensionManager";
import { Service } from "@docsvision/webclient/System/Service";
import { $RequestManager } from "@docsvision/webclient/System/$RequestManager";

extensionManager.registerExtension({
    name: "Client extension with service",
    version: "1.0",
    layoutServices: [ (2)
        Service.fromFactory($CardService, (services: $RequestManager) => new CardService(services)) (3)
        ]
})
    1 Добавьте строку импорта тип/константы $CardService и класса CardService из добавленного в 2 файла (в примере — WebService).
    2 Добавьте в registerExtension поле layoutServices, в значении которого должна быть специальная конструкция.
    3 Service.fromFactory(<Тип сервиса>, (services: $RequestManager) ⇒ new <Класс реализации сервиса>(services)).

  4. Соберите проект клиентского расширения командой npm run build.

  5. Скопируйте полученный файл %BuildDir%/extension.js на сервер Web-клиента в папку /lib/docsvision/webclient/Content\/%Каталог Решения%.

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

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

    let cardService = layout.getService($CardService); (1)
    1 Получение сервиса $CardService.

Проверка работы расширения

Чтобы проверить работу сервиса CardService:

  1. Добавьте в данное расширение обработчик событий, вызывающий функцию $CardService.exists.

    В следующем коде в метод exists сервиса $CardService передается идентификатор карточки, введённый в строку cardId. Результат проверки отображается на экране. Реализованный метод onMyButtonClick должен быть назначен обработчиком события нажатия Кнопки.

    export async function onMyButtonClick(sender: CustomButton, e: IEventArgs) {

let cardId = sender.layout.controls.get<TextBox>("cardId").value;
let result = await sender.layout.getService($CardService).exists(cardId);

if (result)
MessageBox.ShowInfo('Карточка существует');
else
MessageBox.ShowInfo('Карточка не существует');
}

  2. Разработайте серверное расширение, предоставляющее функцию Exists. Инструкция по разработке такого расширения приведена в разделе Разработка расширения с методами WebApi.

  3. Опубликуйте клиентское и серверное расширения на сервере Web-клиента.

  4. Перезапустите сервер Web-клиента.

  5. Настройте разметку карточки, указав для любой Кнопки обработчик onMyButtonClick. Добавьте в разметку Строку с названием cardId.

  6. Откройте карточку с настроенной разметкой. Введите идентификатор существующей карточки в Строку и нажмите Кнопку. На экране отобразится сообщение: Карточка существует.