Добавление нового свойства элементов управления

Элементы управления обладают набором свойств, которые определяют их поведение в веб-браузере пользователя: внешний вид, получение данных (для разметки карточки), обработка событий.

Когда программист формирует список свойств элемента управления нового типа, он может ссылаться только на существующие стандартные свойства (Стандартные свойства и события элементов управления). Если стандартные свойства не позволяют описать все особенности элемента управления, программист может сформировать новое свойство.

Добавить новое свойство элементов управления в Конструктор Web-разметок можно с помощью Расширения.

Перечень необходимых инструментов

Visual Studio.
Docsvision WebClient SDK (запрашивается через портал ТП).

Описание файлов проекта

В корне репозитория расположено решение для Visual Studio (Samples.sln) и ключ для подписания сборок примеров (StrongNameKey.snk).
Assemblies — сборки, необходимые для использования примеров
ServerExtension.cs — входная точка расширение, в которой регистрируются описания контролов и прочие сущности.
Sign.snk — файл подписи сборки. Для установки сборки должны быть подписаны. Рекомендуется сгенерировать новый файл подписи в настройках проекта.
Resource.resx, Resource.ru.resx — локализации, используемые в расширении.
Constants.cs — файл для объявления констант.

Добавление свойства

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

Убедитесь, что установлен Docsvision WebClient SDK.

В этом случае в переменной окружения DocsvisionWebClientSDK содержится путь к его папке, например, C:\Program Files (x86)\Docsvision\WebClient\5.5\SDK.
Создайте проект расширения программы Конструктор Web-разметок.

Добавьте в ядро расширения (файл TemplateDesignerExtension.cs) функцию, предоставляющую описатель свойства элемента управления.

Описатель свойства элемента управления — это объект с типом PropertyDescription, содержащий информацию о свойстве: название свойства, тип, категория, редактор, который должен использоваться для изменения значения, возможность локализации и настройки значения для определённого типа устройств.

PropertyDescription GetSuperPropertyDescription()
{
    var propertyDescription = new PropertyDescription();
    propertyDescription.Name = "SuperProperty";
    propertyDescription.DisplayName = "Супер свойство";
    propertyDescription.Type = typeof(string); (1)
    propertyDescription.Category = PropertyCategoryConstants.DataCategory; (2)
    return propertyDescription;
}

1	Строковый тип свойства.
2	Указывает категорию свойства (`DataCategory` — Данные).

При составлении описания элемента необходимо:

Указать название свойства в Name.
```
propertyDescription.Name = "SuperProperty";
```
Указать отображаемое название свойства в DisplayName. С данным названием свойство отображается в списке свойств элемента управления в программы Конструктор Web-разметок.
```
+propertyDescription.DisplayName = "Супер свойство";
```
Указать тип значения свойства в Type.
```
propertyDescription.Type = typeof(string); (1)
```
1 Строковый тип свойства.
Указать категорию свойства в Category. Категория используется для группировки свойств в настройках элемента управления в программе Конструктор Web-разметок. Категория выбирается из перечня в классе PropertyCategoryConstants.
```
propertyDescription.Category = PropertyCategoryConstants.DataCategory; (1)
```
1 Указывает категорию свойства (DataCategory — Данные).

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

Переопределите метод GetPropertyDescriptions базового класса, чтобы он возвращал коллекцию с парой: ключ — имя. Возвращаемая коллекция позволяет получить описатель данного свойства. Используйте имя, указанное в propertyDescription.Name и метод, предоставляющий описатель свойства в качестве значения:
```
protected override Dictionary<string, PropertyDescription> GetPropertyDescriptions()
{
    return new Dictionary<string, PropertyDescription>
    {
        { "SuperProperty", GetSuperPropertyDescription()}
    };
}
```
Скомпилируйте проект.
Скопируйте safeprojectnamesafeprojectname.dll и safeprojectnamesafeprojectname.dll.pdb из папки bin\Plugins в Каталог-установки-Web-клиента\Plugins.

Ресурсные сборки скопируйте в папки Каталог-установки-Web-клиента\ru\ (для русской локализации), Каталог-установки-Web-клиента\uk\ (для английской локализации) и т.д.
Перезапустите Конструктор Web-разметок.

Проверка свойства

Чтобы проверить пример:

Создайте новый тип элемента управления.

Добавьте Супер свойство в список свойств элемента управления (в PropertyDescriptions).

Для получения описателя свойства используйте метод PropertyFactory.Create, передав в него имя свойства, указанное при его регистрации в методе GetPropertyDescriptions.

PropertyDescriptions = {
    PropertyFactory.GetNameProperty(),
    PropertyFactory.GetVisibilityProperty(),
    PropertyFactory.Create("SuperProperty"), (1)

    PropertyFactory.GetClickEvent() (2)
}

1	Получаем описатель свойства "SuperProperty".
2	Событие "При щелчке".

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

Рисунок 1. Свойство элемента управления из расширения в редакторе разметок