[ELMA3] Создание и настройка кастомной формы документа

Не всегда стандартные формы представления документа удобны для использования. С помощью дизайнера форм их можно редактировать. Можно добавлять панели, вкладки, колонки, делать поля обязательными для заполнения. Также имеется возможность добавлять свои фрагменты разметки на Razor. Делать это целесообразно, когда требуется сделать какую-то уникальную, сложную и удобную форму.

Чтобы перейти к редактированию необходимой формы, откройте вкладку Документооборот в Дизайнере, выберите тип документа и выберите вкладку Формы (представления). Любой тип документа, созданный в системе, имеет три формы представления: форму редактирования, форму создания и форму просмотра. На рис. 1 отмечены вкладки Формы(представления) документа.

Рис. 1. Общий вид вкладки "Формы (представления)"

При переходе к редактированию необходимой формы попадаем в Конструктор форм – раздел Дизайнера, позволяющий править формы и представления объектов системы.

Рис. 2. Конструктор форм

Цифрами на рис. 2 обозначены следующие элементы:

1. Содержание текущей формы документа.
2. Панель слева отображает все свойства документа, которые могут быть расположены на форме. Размещение и закрепление свойства на форме происходит с помощью механизма drag-and-drop – перемещение свойства из левой панели в необходимое место на форме.
3. Верхнее меню. Раздел Основные элементы: колонка, панель, вкладки и текст. Это инструменты, позволяющие создавать определённые элементы разметки на форме.

Рис. 3. Верхнее меню дизайнера форм

На рис. 3 изображено верхнее меню. Цифрами обозначены следующие кнопки:

1. Кнопка Сохранить (сохранение изменений на форме).
2. Кнопка Закрыть без сохранения.
3. Кнопка Настройки формы позволяет настроить выполнение определённого сценария при загрузке формы или изменить имя формы.
4. Инструмент Колонка позволяет добавить колонку на форму. Элемент Колонка позволяет расположить данные в нескольких столбцах на форме. Их может быть несколько в рамках всей формы или какого-то отдельного элемента.
5. Инструмент Панель позволяет создать элемент, который объединяет в группу различные атрибуты на форме. Панель может сворачиваться в одну строку, скрывая содержимое, или разворачиваться, показывая расположенные на ней поля. Возможность сворачивания может быть заблокирована в настройках элемента.
6. Инструмент Вкладки позволяет разбить содержимое формы на несколько вкладок. Выглядит и работает аналогично вкладкам в браузере или в Дизайнере ELMA.
7. Инструмент Текст позволяет расположить надпись где-либо на форме документа. Эту надпись нельзя будет впоследствии редактировать при работе в веб-приложении.

Для примера взят тестовый документ, который может заполняться клиентом страховой компании, желающим застраховать своё транспортное средство. Документ имеет следующие 8 атрибутов:

1. ФИО.
2. Марка.
3. Модель.
4. Год Выпуска.
5. Пробег.
6. Тип ТС.
7. Место приобретения.
8. Сумма страхования.

На протяжении всей статьи будет использоваться данный документ. Рассмотрим пример редактирования формы документа с помощью возможностей, предоставляемых констуктором форм.

1. Форма просмотра.

Рис. 4. Первая вкладка формы просмотра

Рис. 5. Вторая вкладка формы просмотра

На рис. 4 и 5 изображены две вкладки формы просмотра документа. Вкладки сделаны в конструкторе форм с использованием инструмента Вкладки.

Рассмотрим подробнее процесс изменения внешнего вида формы.

Рис. 6. Пользовательские атрибуты документа

На рис. 6 представлена панель, на которой по умолчанию отображаются все атрибуты документа, созданные пользователем. Если необходимо как-то изменить их порядок или отображение, эту панель следует удалить и создать новую.

Изменим порядок отображения атрибутов на форме документа. Для этого использованы инструменты из блока Основные элементы верхнего меню конструктора форм. Вкладки добавляются с помощью инструмента Вкладки. Перетащите элемент Вкладки в нужное место на форме. Он будет выглядеть следующим образом:

Рис. 7. Пустой элемент вкладки

На рис. 7 стрелка указывает на заготовку для будущих вкладок. Вкладки создаются нажатием на зелёный плюс на заготовке. При нажатии на плюс появляется окно, в котором необходимо ввести имя вкладки.

Рис. 8. Окно настроек новой вкладки инструмента «Вкладки»

Пропишите название вкладки в окне, изображённом на рис. 8.

Рис. 9. Созданные вкладки

На рис. 9 изображены созданные вкладки – на них можно добавить атрибуты из бокового меню. Удалить добавленную вкладку, как и любой другой элемент, можно в контекстном меню правой кнопки мыши. На рис. 10 показано контекстное меню с пунктом Удалить.

Рис. 10. Удаление вкладки

2. Форма редактирования.

На примере формы редактирования документа рассмотрим работу с инструментами Панель и Колонка.

Рис. 11. Настройки элемента "Панель"

На рис. 11 показаны настройки инструмента Панель. Здесь указывается заголовок панели, возможность сворачивать, статус свёрнутости по умолчанию. Параметр Сохранять состояние свёрнутости – это настройка, определяющая, будет ли система запоминать в каком состоянии была панель во время последнего открытия формы или не будет. Стиль – позволяет выбрать тему оформления элемента.

Рис. 12. Пример использования инструмента "Колонка"

На рис. 12 показана пустая колонка. В неё могут быть добавлены поля путем перетаскивания их из соседней колонки или из списка атрибутов документа, который отображается на левой панели констуктора форм.

Рис. 13. Панель, настроенная с использованием различных элементов

На рис. 13 изображена панель, на которой одновременно использованы несколько инструментов настройки внешнего вида формы. Сама панель сделана сворачиваемой. Кнопка Свернуть/Развернуть выделена красным цветом. Поля разбиты на 2 колонки. Выделенные цветными рамками надписи созданы с помощью инструмента Текст. Данный инструмент позволяет добавить нередактируемую надпись на форму. Она может занимать одну или несколько строк.

Рис. 14. Обязательные для заполнения поля

Поля на форме могут быть помечены как обязательные для заполнения. Делается это в окне настроек поля. Оно вызывается нажатием правой кнопки мыши по пункту контекстного меню Настройки. Пример обязательных для заполнения полей приведён на рис. 14.

Рис. 15. Окно настроек поля на форме

На рис. 15 стрелками и цифрами обозначены следующие настройки поля на форме:

1. Параметр Обязательная для заполнения позволяет пометить поле обязательным для заполнения.
2. Параметр Только для чтения позволяет запретить редактирование поля.
3. Параметр Название на форме определяет подпись поля на форме. Она может отличаться от его названия. Параметр Описание добавить более подробное описание поля.

На вкладке Дополнительно, которая показана на рис. 16, можно указать сценарий, который будет выполняться при изменении значения поля.

Рис. 16. Вкладка "Дополнительные" окна настроек поля

Таким образом были продемонстрированы основные возможности настройки внешнего вида форм посредством конструктора форм. Но этого может оказаться недостаточно. Средствами конструктора форм нельзя регулировать ширину поля на форме, нельзя расположить несколько полей на одной строке в рамках одной колонки и т.д.. Для обхода ограничений конструктора форм имеется механизм добавления фрагментов кода на языке разметки Razor. Для этого в настройках элемента, который добавлен на форму, необходимо указать путь к файлу разметки. Для простоты используем элемент Панель. В настройках панели необходимо указать путь до файла разметки.

Рис. 17. Вкладка "Системные" окна настроек элемента "Панель"

В настройках панели в поле Форма Razor (рис. 17) указывается относительный путь до файла разметки. Он должен находиться в папке …/UserConfig/WebApplication/Modules/…. Важный момент: все символы "\" в пути (используется в Windows) необходимо заменять на ’/’ (Используется в Web).

Необходимо убедиться, что папка WebApplication/Modules/… размещена в той папке конфигурации, которая действительно подключена к серверу. Проверить это можно в файле connection.config, который располагается в папке ELMA3-Standart\Web. В нём прописан путь до папки с файлом configuration.config. Именно в эту папку и нужно добавить папку WebApplication/Modules/…

Термин Относительный путь означает, что всё то, что находится в пути до /Modules, заменяется на символ ’~’. То есть путь начинается с ~/Modules/, а продолжение зависит от того, какую форму мы хотим изменить.

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

Так как нам нужен путь до системного файла, его нужно найти в папке Web/Modules. Затем нужно скопировать путь до него, и создать аналогичную структуру вложенных папок в папке WebApplication/Modules/…, которая находится в правильной папке конфигурации.

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

1. Если путь до файла не содержит папки Shared, то прописывается полная версия ~/Modules/(остальные вложенные папки)/ИмяФайлаОтличноеОтИмениФайлаПоУмолчанию.cshtml. Блок «(остальные вложенные папки)» – это папки, вложенные в системную папку /Web/Modules/ и далее до оригинального файла разметки формы. Они должны быть продублированы внутри папки WebApplication/Modules в папке конфигурации.

2. Если же оригинальный файл находится в подпапке Shared, то не обязательно писать путь от ~/Modules/, можно использовать относительный путь от папки …/Shared/…, с указанием расширения файла с разметкой в конце пути. ~/(все папки вложенные в Shared)/имяФайлаОтличноеОтИмениФайлаПоУмолчанию.

Имя файла с разметкой (имяФайла.cshtml) должно отличаться от имени системного файла. Если нужно поменять несколько форм документов или одну форму в нескольких местах, то нужно создавать несколько файлов с разными именами, но все их можно поместить в одну папку. В случае совпадения имён система подключит один из них в соответствии со своими внутренними параметрами.

3. Можно все файлы с пользовательскими фрагментами разметки хранить в папке \UserConfig\WebApplication\Views\имяФайлаРазметки.cshtml и в Дизайнере указывать путь ~/Views/имяФайлаРазметки.

Изменять с помощью описанных приёмов можно не только формы документов. Все объекты системы, для которых доступен редактор форм, изменяются аналогичным способом. Так можно править карточки контрагента, формы задач, сделки и некоторые другие объекты.

Рассмотрим конкретный пример.

Путь до пользовательского фрагмента формы редактирования документа:

…/UserConfig/WebApplication/Modules/EleWise.ELMA.Documents.Web/Views/Shared/Document/EditDocumentFormPanel.cshtml – реальный системный путь. В Дизайнере можно написать так:

Рис. 18. Пример пути до файла пользовательской разметки

или коротко ~/ Document/EditDocumentFormPanel.cshtml. Если разместить файл EditDocumentFormPanel.cshtml в папку \UserConfig\WebApplication\Views\, то можно указать ~/Views/EditDocumentFormPanel.cshtml.

Далее приведён фрагмент формы и разметка, которая реализует размещение полей как на рис. 18.

Рис. 18. Форма с внедрённым фрагментом пользовательской разметки

На рис. 18 красной рамкой выделен фрагмент, реализованный с помощью внедрённого в форму файла разметки. Далее приведён код, реализующий данное расположение полей.

В коде разметки используются следующие параметры форматирования HTML:

• смещение и интервал реализованы параметром margin: 10px;;
• ширину полей задаёт параметр width: 100px;;
• конструкция @using (var data = new ObjectViewData(this)) позволяет получить доступ для редактирования к полям созданного ранее документа;
• Все поля размещены в строках и столбцах таблицы HTML-документа ( теги <tr> <td> </td> </tr>).

@using (var data = new ObjectViewData(this))// подключаем объект содержащий информацию о документе (Ключевое слово C# this обращается к объекту, с которым работает данный фрагмент кода)
{// в фигурных скобках начинается собственно разметка Razor (Html+C#)
 <tr> // Строка таблицы
    <td>// Данные в сторке (или колонка)
    <div style="float:left; width: 300px;">// задаём форматирование блока	
    @Html.Caption("FIO", a => { a.Container("div");})// Выводим подпись поля FIO в блоке div
    @Html.EditorOrDisplay("FIO", a => { a.Container("div");}) // Выводим собственно поле редактирования значения поля FIO
    </div>
  </td>
</tr> // Закрыли открытые теги
<tr>// Вторая строка формы с несколькими полями-колонками в одной.  
  <td>
    <div style="float:left; width: 100px; margin: 10px;">
      @Html.Caption("Marka", a => { a.Container("div");})
      @Html.EditorOrDisplay("Marka", a => { a.Container("div");})
    </div> 
    <div style="float:left; width: 100px; margin: 10px;">
      @Html.Caption("Modelj", a => { a.Container("div");})
      @Html.EditorOrDisplay("Modelj", a => { a.Container("div");})
    </div>
    <div style="float:left; width: 100px; margin: 10px;">
      @Html.Caption("GodVypuska", a => { a.Container("div");})
      @Html.EditorOrDisplay("GodVypuska", a => { a.Container("div");})
    </div>
    <div style="float:left; width: 100px; margin: 10px;">
      @Html.Caption("Probeg", a => { a.Container("div");})
      @Html.EditorOrDisplay("Probeg", a => { a.Container("div");})
    </div>
  </td>
</tr>
<tr>// третья строка 
  <td>	
    <div style="float:left; width: 100px; margin: 3px;">
      @Html.Caption("TipTS", a => { a.Container("div");})
      @Html.EditorOrDisplay("TipTS", a => { a.Container("div");})
    </div>
  </td>
</tr>
<tr> // Четвёртая строка
  <td>	
    <div style="float:left; width: 100px; margin: 3px;">
      @Html.Caption("MestoPriobreteniya", a => { a.Container("div");})
      @Html.EditorOrDisplay("MestoPriobreteniya", a => { a.Container("div");})
    </div>
  </td>
</tr>
<tr>//Последняя строка
  <td>	
    <div style="float:left; width: 100px; margin: 3px;">
      @Html.Caption("SummaStrahovaniya", a => { a.Container("div");})
      @Html.EditorOrDisplay("SummaStrahovaniya", a => { a.Container("div");})
    </div>
  </td>
</tr>	
}