С чего начать

Исходные коды примеров серверных и клиентских расширений, расширений программы Конструктор Web-разметок, а также элементов управления содержатся в репозитории WebClient-Samples на ресурсе GitHub.

Загрузите к себе репозиторий, чтобы начать работать с примерами.

Пример рассчитан на версию Web-клиента 6.1 или выше.

Подготовка

Для сборки примеров в Visual Studio[1] (серверные расширения и расширения программы Конструктор Web-разметок) необходимы актуальные версии компонентов Web-клиента и системы Docsvision, которые можно скопировать в папку Assemblies из каталога установки Web-клиента и системы Docsvision.

Для проверки зависимостей и быстрой сборки сразу всех примеров можно воспользоваться установочным пакетом Docsvision Web-client SDK. При установке файлы примеров будут собраны и помещены в соответствующие каталоги. При необходимости (например, если Web-клиент уже установлен) вы можете изменить путь сборки через переменную окружения в node и проектах Visual Studio[2]. Если в примере требуется загрузка разметки или библиотеки карточек, это необходимо произвести вручную.

После установки SDK в C:\Program Files (x86)\Docsvision\WebClient\SDK\USAGE.md указаны инструкции по разворачиванию примеров.

  1. Подготовьте среду разработки.

    На компьютере разработчика должны быть установлены:

    • Microsoft Visual Studio 2022.

    • NodeJS v18.12.1 и выше или выше.

    • TypeScript 3.8.

      Если указанные компоненты не установлены, при установке SDK будет предложено их автоматически загрузить и установить.

  2. Загрузите на компьютер репозиторий WebClient-Samples.

  3. Установите шаблоны проектов из полученного репозитория:

    • TemplateDesignerExtension — шаблон проекта для разработки расширения программы Конструктор Web-разметок.

    • TemplateServerExtension — шаблон проекта для разработки серверного расширения.

Чтобы установить шаблоны:

  1. Скопируйте папки Docsvision Web-layout designer extension template и Docsvision Web-client server extension template из каталога репозитория ProjectTemplates\VSTemplates\ в каталог шаблонов проектов Visual Studio[3] (C:\Users\\%username%\Documents\Visual Studio %version%\Templates\ProjectTemplates\).

  2. Запустите Visual Studio[4]. Будут добавлены новые типы проектов: TemplateDesignerExtension и TemplateServerExtension.

Что дальше

  1. Определите цель разработки.

    Web-клиент имеет несколько точек расширения функциональных возможностей.

    Программист может разработать:

    • Серверное расширение, добавляющее методы WebAPI, для вызова с клиентского уровня.

      Серверные методы могут быть использованы для взаимодействия с сервером Docsvision: создание карточек, запуск БП и т. д.

    • Новый тип элементов управления для создания разметок.

      Данный тип расширения включает два компонента: расширение программы Конструктор Web-разметок (обеспечивает возможность настройки разметки с использованием ЭУ) и клиентское расширение (обеспечивает функционирование ЭУ на клиентской стороне).

    • Клиентский скрипт, содержащий обработчики событий разметки.

      Данные скрипты могут добавлять в Web-клиент необходимую бизнес-логику или обеспечивать другие функции клиентского уровня.

    • Клиентское расширение — общее название компонентов, обеспечивающих функциональность клиентского уровня.

  2. Ознакомьтесь с инструкцией по разработке требуемого типа компонента Web-клиента в данном руководстве.

  3. Ознакомьтесь с предоставляемыми примерами.

Примеры

Папка репозитория WebClient-Samples содержит каталоги:

  • Assemblies — папка с подключаемыми сборками Web-клиента, платформы Docsvision и др..

  • ClientScripts — папка с исходными кодами клиентских расширений, предоставляющих обработчики событий. Исходные коды приведены на TypeScript (подкаталог TypeScript).

  • ControlProperties — папка с исходным кодом расширения программы Конструктор Web-разметок, добавляющего новый тип свойств элемента управления.

  • Controls — папка с исходными кодами элементов управления.

  • Others — папка с прочими примерами.

  • Obsolete — устаревшие примеры, работа которых не поддерживается в текущей версии Web-клиента.

  • ProjectTemplates — папка с шаблонами проектов серверного расширения и расширения программы Конструктор Web-разметок.

  • ServerExtensions — папка с исходными кодами серверных расширений.

  • Install и другие папки — служебные директории.

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

Часть исходных кодов представляет собой проекты Visual Studio[5] (решение Samples), а часть — отдельные файлы клиентских расширений (TypeScript, CSS).

Список примеров

Примеры клиентских расширений

Все клиентские скрипты также включают в себя проекта расширения Web-клиента.

Примеры клиентских расширений с обработчиками событий (скриптов):

  • ClientScripts\TypeScript\ChangeLogoAndBackground — демонстрирует пример реализации скрипта, изменяющего заголовок страницы и её фоновое изображение для папок и дашборда.

  • ClientScripts\TypeScript\ControlsRelation — пример демонстрирует способ организации взаимодействия элементов разметки, через обработчики событий (в примере видимость одного элемента управления зависит от значения другого).

  • ClientScripts\TypeScript\CopyValueToControl — пример метода, в котором выполняется копирование значения одного элемента управления в другой.

  • ClientScripts\TypeScript\ExtendServerQueryData — индикатор высокого приоритета для просроченных заданий.

  • ClientScripts\TypeScript\FileListHighlightRow — добавляет красную обводку при скачивании файла.

  • ClientScripts\TypeScript\GridColumnBackgroundRows — новая колонка таблицы грида — Фон строки.

  • ClientScripts\TypeScript\GridContextMenuItem — новый пункт контекстного меню Открыть карточку в модальном окне.

  • ClientScripts\TypeScript\GridHoverPanelGrouping — группировка по столбцу.

  • ClientScripts\TypeScript\GridToolbarButton — кнопка в гриде отображает общее количество карточек, а также количество непрочитанных.

  • ClientScripts\TypeScript\LoginPage — настройка страницы авторизации.

  • ClientScripts\TypeScript\ShowRequiredFields — отображение незаполненных обязательных полей.

  • ClientScripts\TypeScript\ValidateOnStateChanging — пример реализации обработчика изменения состояния карточки, осуществляющего проверку значения текстового поля, с отменой изменения состояния, если поле не заполнено или количество знаков в строке больше 100.

  • ClientScripts\AdvancedTypeScript — примеры клиентских расширений, в которых задействован React API:

    • ClientScripts\AdvancedTypeScript\AdaptiveMenuBar — пример реализации панели меню с собственным набором элементов.

    • ClientScripts\AdvancedTypeScript\MessageBox — пример вызова стандартных диалоговых окон Web-клиента.

    • ClientScripts\AdvancedTypeScript\ModalDialog — пример реализации диалогового окна с собственным содержимым.

    • ClientScripts\AdvancedTypeScript\ModalSidebar — пример вызова стандартной боковой панели Web-клиента.

Примеры серверных расширений

  • ServerExtensions\CSPSignatureVisualization — пример изменения визуализации штампа электронной подписи: вставки собственных изображений штампов электронной подписи в файл, приложенный к карточке Docsvision.

  • ServerExtensions\CreateCard — пример реализации функции создания исходящих документов, представленной в виде клиентской и серверной частей:

    • ServerExtensions\CreateCard\CreateCardServerExtension — серверное расширение, добавляющее метод WebAPI, создающий карточку исходящего документа.

    • ServerExtensions\CreateCard\CreateCardWebExtension — клиентское расширение, добавляющее клиентский сервис создания документа (вызывает метод расширения CreateCardServerExtension) и пример обработчика событий, использующего клиентский сервис.

  • ServerExtensions\CreateCardDialog — серверное расширение, добавляющее в Web-клиент возможность создания карточек типа Этап согласования:

    • ServerExtensions\CreateCardDialog\CreateCardDialogServerExtension — серверное расширение, добавляющее фабрику карточек, позволяющую создавать карточки Этап согласования.

    • ServerExtensions\CreateCardDialog\CreateCardDialogWebExtension — клиентское расширение, регистрирующее новый тип карточек на стороне клиента.

  • ServerExtensions\CustomConditionTypes — отображение разметки в соответствии с заданными условиями.

    • ServerExtensions\CustomConditionTypes\CustomConditionTypesDesignerExtension — проект-расширение для программы Конструктор Web-разметок. Содержит класс CustomConditionTypesProvider, в котором реализованы методы для отображения новых условий выбора разметки по группе, пользователю, роли

    • ServerExtensions\CustomConditionTypes\CustomConditionTypesLayoutExtension — проект-расширение для Web-клиента, которое позволяет определить — выполняется условие выбора разметки или нет для текущего контекста.

    • ServerExtensions\CustomConditionTypes\CustomConditionTypesInterfaces — проект-расширение для программы Конструктор Web-разметок и серверного расширения, содержащий все константные значения для этих проектов.

  • ServerExtensions\CustomLibrary — пример демонстрирует способ добавление нового типа карточек. Пример включает несколько компонентов:

    • ServerExtensions\CustomLibrary\CardDefs — схема новой библиотеки карточек с карточкой справочника.

    • ServerExtensions\CustomLibrary\CustomLibrary.ObjectModel — классы объектной модели библиотеки карточек.

    • ServerExtensions\CustomLibrary\CustomLibraryServerExtension — серверное расширение, добавляющее в Web-клиент поддержку нового типа карточек и WebApi функцию получения данных карточек нового типа.

    • ServerExtensions\CustomLibrary\CustomLibraryWebExtension — клиентское расширение, добавляющее клиентский сервис для вызова функции серверного расширения CustomLibraryServerExtension и пример обработчика событий, использующего клиентский сервис.

  • ServerExtensions\DataGridControlExtension — плагин загружает информацию о файлах для документа.

    • ServerExtensions\DataGridControlExtension\DataGridControlServerExtension — проект-расширение для Web-клиента. Содержит плагин Files (FilesDataGridControlPlugin), реализующий загрузку информации о файлах документа.

  • ServerExtensions\ExcelExport — экспорт в Excel.

    • ServerExtensions\ExcelExport\ExcelExportServerExtension — проект-расширение для Web-клиента, позволяющего вмешать в процесс экспорта в Excel.

  • ServerExtensions\ExtendedCardInfo — пример демонстрирует возможность получения данных карточки, которые по умолчанию не загружаются и не передаются клиенту. Пример представлен в виде клиентской и серверной частей:

    • ServerExtensions\ExtendedCardInfo\ExtendedCardInfoServerExtension — серверное расширение, добавляющее WebApi функцию загрузки из Docsvision данных карточки.

    • ServerExtensions\ExtendedCardInfo\ExtendedCardInfoWebExtension — клиентское расширение, добавляющее клиентский сервис для вызова функции серверного расширения ExtendedCardInfoServerExtension и пример обработчика событий, использующего клиентский сервис.

  • ServerExtensions\LicenseCheck — демонстрация способа проверки лицензии Docsvision на наличие дополнительной опции. Пример представлен в виде клиентской и серверной частей:

    • ServerExtensions\LicenseCheck\LicenseCheckServerExtension — серверное расширение, реализующее функцию проверки лицензии.

    • ServerExtensions\LicenseCheck\LicenseCheckWebExtension — клиентское расширение, добавляющее клиентский сервис для вызова функции проверки лицензии из серверного расширения LicenseCheckServerExtension и пример обработчика событий, использующего клиентский сервис.

  • ServerExtensions\ShiftTasksEndDate — пример реализации функции изменения данных связанных карточек. Пример представлен в виде клиентской и серверной частей:

    • ServerExtensions\ShiftTasksEndDate\ShiftTasksEndDateServerExtension — серверное расширение, в котором реализована функция изменения времени исполнения в заданиях, связанных с документом.

    • ServerExtensions\ShiftTasksEndDate\ShiftTasksEndDateWebExtension — клиентское расширение, добавляющее клиентский сервис для вызова функции изменения связанных карточек и пример обработчика событий, использующего клиентский сервис.

  • ServerExtensions\TableControl — пример демонстрирует способ получения данных из справочника контрагентов и отображения их в таблице. Пример представлен в виде клиентской и серверной частей:

    • ServerExtensions\TableControl\TableControlServerExtension — серверное расширение с функцией WebApi, предоставляющей данные контрагентов;

    • ServerExtensions\TableControl\TableControlWebExtension — клиентское расширение, реализующее несколько функций: добавляет клиентский сервис для вызова функции серверного расширения TableControlServerExtension. Предоставляет обработчик открытия карточки, использующий клиентский сервис для получения данных контрагентов. Обеспечивает загрузку данных контрагентов в таблицу.

Примеры элементов управления

  • Controls\AcquaintancePanel — элемент управления Панель отправки на ознакомление, предназначен для запуска БП отправки документа на ознакомление. Пример включает несколько компонентов:

    • AcquaintancePanel\AcquaintancePanelDesignerExtension — текстовый описатель элемента управления, а также расширение программы Конструктор Web-разметок с новым типом свойств и локализованными ресурсами.

    • AcquaintancePanel\AcquaintancePanelServerExtension — серверное расширение, предоставляющее функцию запуска бизнес-процесса отправки документа на ознакомление.

    • AcquaintancePanel\AcquaintancePanelWebExtension — клиентское расширение с клиентским компонентом элемента управления и сервисом вызова функции запуска БП из расширения AcquaintancePanelServerExtension.

  • Controls\CheckBox — элемент управления "Флаг", предназначен для установки и отображения значения булева типа. Пример включает два компонента:

    • CheckBox\CheckBoxDesignerExtension — расширение программы Конструктор Web-разметок с бинарным описателем элемента управления, новым свойством DefaultValue и редактором BooleanMetadataEditor значения свойства DataField, который ограничивает список доступных для выбора полей карточки.

    • CheckBox\CheckBoxWebExtension — клиентское расширение с клиентским компонентом элемента управления.

  • Controls\DocumentSignBatchOperation — пример реализации элемента управления Групповая операция / Подписание.

    • Controls\DocumentSignBatchOperation\DocumentSignBatchOperationWebExtension — проект-расширение серверной части Web-клиента. Содержит ЭУ групповой операции Подписание документа.

    • Controls\DocumentSignBatchOperation\DocumentSignBatchOperationDesignerExtension — содержит решение для программы Конструктор Web-разметок с локализованными ресурсами.

  • Controls\DownloadFilesGroupOperation — пример реализации элемента управления группой операции — загрузки файлов выбранных карточек Документ на компьютер. Пример включает несколько компонентов:

    • DownloadFilesGroupOperation\DownloadFilesGroupOperationDesignerExtension — расширение программы Конструктор Web-разметок с бинарным описателем элемента управления, новыми свойствами downloadDocumentFileMode и BatchOperationRestrictionFoldersPropertyDescription, и источником данных DownloadDocumentFileModeSource для свойства downloadDocumentFileMode.

    • DownloadFilesGroupOperation\DownloadFilesGroupOperationServerExtension — серверное расширение с функцией, возвращающей файлы карточки.

    • DownloadFilesGroupOperation\DownloadFilesGroupOperationWebExtension — клиентское расширение с клиентским компонентом элемента управления и сервисом вызова функции получения файлов карточки из расширения DownloadFilesGroupOperationServerExtension.

  • Controls\ExchangeRates — элемент управления ExchangeRates, предназначен для отображения курса валют, получаемого с внешнего ресурса. Пример включает два компонента:

    • ExchangeRates\ExchangeRatesDesignerExtension — текстовый описатель элемента управления, а также расширение программы Конструктор Web-разметок с локализованными ресурсами.

    • ExchangeRates\ExchangeRatesWebExtension — клиентское расширение с клиентским компонентом элемента управления.

  • Controls\HyperComments — элемент управления HyperComments, предназначен для отображения виджета комментариев внешнего веб-приложения HyperComments. Пример включает два компонента:

    Обратите внимание, пример устарел. Для его использования требуется лицензия.

    • HyperComments\HyperCommentsDesignerExtension — расширение программы Конструктор Web-разметок с бинарным описателем элемента управления, новым типом свойств и локализованными ресурсами.

    • HyperComments\HyperCommentsWebExtension — клиентское расширение с клиентским компонентом элемента управления.

  • Controls\Image — элемент управления Image, предназначен для отображения галереи изображений. В примере демонстрируется возможность работы со значением элемента управления сложного типа и локализацией. Пример включает несколько компонентов:

    • Image\ImageDesignerExtension — расширение программы Конструктор Web-разметок с бинарным описателем элемента управления, новыми типами свойств и новым редактором SliderEditor.

    • Image\ImageServerExtension — серверное расширение с конвертером значения SliderConverter, который применяется при загрузке значения элемента управления в клиент.

    • Image\ImageWebExtension — клиентское расширение с клиентским компонентом элемента управления.

  • Controls\Link — элемент управления Link, предназначен для отображения ссылки. Пример включает два компонента:

    • Link\LinkDesignerExtension — текстовый описатель элемента управления, а также расширение программы Конструктор Web-разметок с локализованными ресурсами.

    • Link\LinkWebExtension — клиентское расширение с клиентским компонентом элемента управления.

  • Controls\RefCases — элемент управления RefCases, предназначен для выбора и отображения дела из Справочника номенклатуры дел.

    Обратите внимание, пример устарел. Модуль Делопроизводство 5 устарел и не поддерживается. Функциональность

    • RefCases\RefCasesDesignerExtension — текстовым описателем элемента управления, а также расширение программы Конструктор Web-разметок с дополнительными редакторами;

    • RefCases\RefCasesServerExtension — серверное расширение с конвертером значения RefCasesConverter, который применяется при загрузке значения элемента управления в клиент, и сервисами для получения данных из Справочника номенклатуры дел.

    • RefCases\RefCasesWebExtension — клиентское расширение с реализацией элемента управления.

  • Controls\TextBox — элемент управления TextBox, предназначен для текстового поля с меткой. Пример включает два компонента:

    • TextBox\TextBoxDesignerExtension — расширение программы Конструктор Web-разметок с бинарным описателем элемента управления, новым типом свойств и локализованными ресурсами.

    • TextBox\TextBoxWebExtension — клиентское расширение с клиентским компонентом элемента управления.

  • ControlProperties\Url — расширение программы Конструктор Web-разметок с описателем нового свойства Url.

Прочие примеры

  • Others\CustomStageService — демонстрационный вариант специального сервиса логики этапа согласования.

  • Others\ExternalWebService — пример отдельного веб-сервиса, предоставляющего методы для взаимодействия с платформой Docsvision через WebApi:

    • Получение информации о карточке документа по её идентификатору.

    • Создание карточки документа по переданной модели.

    • Обновление данных карточки документа.

    • Удаление карточки документа по её идентификатору.

    • Изменение состояния карточки документа.

    • Прикрепление файла к карточке документа.

    • Получение файла по его идентификатору.

    • Получение результата выполнения расширенного отчёта.

  • Others\KonturIntegration — пример реализации сервиса интеграции с системой Контур.Фокус, который открывает возможность:

    1. При создании Контрагента заполнить реквизиты, полученные из Контур.Фокус на основе указанного ИНН.

    2. В карточке Документа получить из Контур.Фокус отчёт о Контрагенте и приложить его в карточку Документа.

    Содержит следующие компоненты:

    • KonturServerExtension — папка с серверным расширением Web-клиента, в котором реализовано проксирование запросов к Контур.Фокус (для обхода ограничений CORS в браузере).

    • KonturWebExtension — папка с клиентским расширением, в котором реализовано открытие отчета о контрагенте и загрузка информации.

  • Others\SignalForUsers — пример использования сервиса отправки оповещений пользователям Web-клиента:

    • Others\SignalForUsers\SignalServerExtension — серверное расширение, предоставляющее функцию рассылки оповещений.

    • Others\SignalForUsers\SignalWebExtension — клиентское расширение с клиентским сервисом и обработчиком, вызывающим функцию рассылки оповещений.

  • Others\Watermark — пример расширения программы _DVWebTool_s, добавляющего водяной знак в PDF файлы документа:

    • Others\Watermark\WatermarkServerExtension — серверное расширение, предоставляющее методы для получения и добавления файлов в документ.

    • Others\Watermark\WatermarkWebExtension — клиентское расширение, вызывающее функцию добавления водяного знака.

    • Others\Watermark\WatermarkWebToolExtension — расширение программы _DVWebTool_s, реализующее функцию добавления водяного знака в PDF-файлы на компьютере пользователя.

Шаблоны проектов серверных расширений

Папка ProjectTemplates содержит шаблоны проектов для создания серверных расширений Web-клиента, программы Конструктор Web-разметок, а также клиентских расширений.

  • ProjectTemplates\TemplateDesignerExtension — шаблон проекта расширения программы Конструктор Web-разметок.

  • ProjectTemplates\TemplateServerExtension — шаблон проекта серверного расширения Web-клиента.

  • ProjectTemplates\TemplateWebExtension — шаблон проекта web-расширения.

  • ProjectTemplates\TemplateXmlDesignerExtension — XML-шаблон нового ЭУ.

1. Рекомендуется использовать Visual Studio Code 2022.
2. Рекомендуется использовать Visual Studio Code 2022.
3. Рекомендуется использовать Visual Studio Code 2022.
4. Рекомендуется использовать Visual Studio Code 2022.
5. Рекомендуется использовать Visual Studio Code 2022.