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

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

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

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

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

  • Visual Studio.

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

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

  • В корне репозитория расположено решение для Visual Studio (Samples.sln) и ключ для подписания сборок примеров (StrongNameKey.snk).

  • Assemblies — сборки, необходимые для использования примеров

  • ServerExtension.cs — входная точка расширение, в которой регистрируются описания контролов и прочие сущности.

  • Sign.snk — файл подписи сборки. Для установки сборки должны быть подписаны. Рекомендуется сгенерировать новый файл подписи в настройках проекта.

  • Resource.resx, Resource.ru.resx — локализации, используемые в расширении.

  • Constants.cs — файл для объявления констант.

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

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

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

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

  2. Создайте проект расширения программы Конструктор Web-разметок.

  3. Добавьте в ядро расширения (файл 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 — Данные).
    При составлении описания элемента необходимо:
    1. Указать название свойства в Name.

      propertyDescription.Name = "SuperProperty";
    2. Указать отображаемое название свойства в DisplayName. С данным названием свойство отображается в списке свойств элемента управления в программы Конструктор Web-разметок.

      +propertyDescription.DisplayName = "Супер свойство";
    3. Указать тип значения свойства в Type.

      propertyDescription.Type = typeof(string); (1)
      1 Строковый тип свойства.
    4. Указать категорию свойства в Category. Категория используется для группировки свойств в настройках элемента управления в программе Конструктор Web-разметок. Категория выбирается из перечня в классе PropertyCategoryConstants.

      propertyDescription.Category = PropertyCategoryConstants.DataCategory; (1)
      1 Указывает категорию свойства (DataCategory — Данные).
    Обратитесь к описанию класса PropertyDescription, чтобы получить полный перечень возможностей описателя свойства элементов управления.
  4. Переопределите метод GetPropertyDescriptions базового класса, чтобы он возвращал коллекцию с парой: ключ — имя. Возвращаемая коллекция позволяет получить описатель данного свойства. Используйте имя, указанное в propertyDescription.Name и метод, предоставляющий описатель свойства в качестве значения:

    protected override Dictionary<string, PropertyDescription> GetPropertyDescriptions()
    {
        return new Dictionary<string, PropertyDescription>
        {
            { "SuperProperty", GetSuperPropertyDescription()}
        };
    }
  5. Скомпилируйте проект.

  6. Скопируйте safeprojectnamesafeprojectname.dll и safeprojectnamesafeprojectname.dll.pdb из папки bin\Plugins в Каталог-установки-Web-клиента\Plugins.

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

  7. Перезапустите Конструктор Web-разметок.

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

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

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

    Для получения описателя свойства используйте метод PropertyFactory.Create, передав в него имя свойства, указанное при его регистрации в методе GetPropertyDescriptions.
    PropertyDescriptions = {
        PropertyFactory.GetNameProperty(),
        PropertyFactory.GetVisibilityProperty(),
        PropertyFactory.Create("SuperProperty"), (1)
    
        PropertyFactory.GetClickEvent() (2)
    }
    1 Получаем описатель свойства "SuperProperty".
    2 Событие "При щелчке".
  3. Опубликуйте расширение с элементом управления на сервере Web-клиента.

  4. Откройте для настройки любую разметку карточки.

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

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