Работа с формами

Способы вывода формы на странице

Форму можно вывести в следующих вариантах: 

1. Просто сразу на странице в виде сниппета div с классом as-form

<div class="as-form" data-code="x1" data-itemid="123"></div>

2. Как ссылка на модальную форму. Подробнее про форму в модальном окне.

3. Как контекстное окно рядом с кнопкой (окно закрывается по нажатию на крестик). Подробнее про popover формы.

4. Как выпадающее окно рядом с кнопкой (окно закрывается по нажатию вне окна). Подробнее про dropdown формы.

5. Загрузка формы по ссылке в некий контейнер на странице. Подробнее про загрузку форм по ссылке.  

Настройка хранимых процедур для формы

Какие есть процедуры у формы: 

• GetItem - заполнение полей формы и изменение настроек файлы.
• CheckItem - проверка полей формы перед сохранением.
• SaveItem - сохранение формы по кнопке. 
• Progress - отображение полоски прогресса при заполнении полей формы. 
• CheckField - вызывается при изменении поля формы (например, для проверки корректности его значения)
• SaveField - вызывается для одиночного сохранения поля (поменял поле, ушел с него и поле сразу сохранилось)

Процедуры формы генерируются автоматически в настройках формы. 

Важно следовать общему стилю и виду шаблонных процедур (они имеют префикс fm_example_).

Хранимая процедура извлечения данных формы GetItem

CREATE PROCEDURE [dbo].[fm_tatest_getItem]
@itemID int, --Стандартные параметры, они всегда приходят в эту процедуру.
@username nvarchar(256)
AS BEGIN -- инициализация формы данными. Названия вывода 1 SELECT должны совпадать с элементами формы
  if(@itemID>0) begin --Перед началом можно проверить права данного username -- 1 SELECT значения элементов формы
     select * from as_trace t1 where id = @itemID -- 2 SELECT дополнительные параметры настройки формы
/* select 'Редактирование "'+header+'"' Title, '' Subtitle, 'Сохранить' ButtonText, 'success' Background */
-- 3 SELECT некие табличные данные в свободном формате для вывода в форме через JS Render
  end else
  begin
     select 1
  end
select '' Title, '' Subtitle, 'h2' HeaderTag, 1 LineLabel
END

На входе: 

username - текущий пользователь

itemID - что передано в data-itemID сниппета формы (может быть и строкой, по умолчанию int)/ 

в процедуру может передаваться необязательный параметр @parameters ExtendedDictionaryParameter в котором передаются системные параметры:

• langID - текущий язык пользователя
• falconGuid - guid пользователя, хранящийся у него в куки (работает для всех пользователей, в том числе неавторизованных), также в этом параметре передаются параметры URL страницы, на которой находится форма

НА выходе 3 SELECT:

1. SELECT 1 - данные формы (колонки). 

Также в этом запросе указываются метаданные к колонкам:

• возможные дополнительные CSS классы к элементам ставятся через class_{colCode}
• для списковых полей можно задать через параметр dict_{colCode} список возможных значений для элемента в формате Value1,Text1||Value2,Text2||...
• блокировать поле можно через установку в 1 для disabled_{colCode}
• disableXSS_{colCode}. Если 1 то отключает проверку XSS на данном поле
• можно указать что поле можно одиночно редактировать через префикс edt_{colCode}
• можно указать дополнительные подсказки для поля (при клике на них будет меняться значение поля)  example_{colCode}. В качестве значения можно указать несколько значений через "||", например value1||value2||value3
• у поля можно указать гибкие настройки через JSON в поле options_{colCode}. Более подробно про настройки по каждому типу поля - /docs/formy--upravlenie-nastroykami-polya-cherez-options--polya
• подмена названия поля title_{colCode}
• тип поля можно переопределить через type_{colCode}

2. SELECT 2 - Настройки формы.

• AlertOptions - JSON настройки для системного уведомления о заполнении формы (ОК или Fail).  См. подробнее...
• Background (код фона формы, напр success) - задает фон формы.
• ButtonText - текст у кнопки действия (Сохранить).
• ChangeFontSize - если 1, то вверху появляются кнпоки для изменения размера шрифта.
• ChangeTriggerFieldOnLoad - если указано поле формы (или поля формы через запятую), то при загрузке будет вызвано событие изменения поля (например, чтобы прогрузить некоторые данные через ChangeitemField).
• CopyClipboard - некий текст. Если он указан, то вверху формы возникает значок Буфера обмена, при клике происходит копирование этого текста в буфер обмена. 
• DisableAntiXSS  - если 1, то для полей ввода будет отключена обработка HTML Encode (т.е. защита от XSS будет отключена и ее надо частично будет реализовать в коде SQL).
• DisableCheckField - если 1, то проверка полей при изменении через процедуру CheckField отключена.
• DisableFocusOnLoad - если 1, то при загрузке формы по умолчанию не будет ставиться фокус ввода на 1 поле формы (актуально когда несколько форм на странице). 
• DisableSaveStateChecking - если 1, то для формы не будет выполняться проверка на изменения формы перед случайным закрытием или переходом на другую страницу. По умолчанию такая проверка есть для всех форм - если что-то меняли, то при случайном переходе на другую страницу будет возникать предупреждение о несохраненных данных. 
• EditableSuccessMessage - задает текст сообщения об успешном изменении одиночного поля.
• EnablePrint - если 1, то появляется кнопка отправки на печать (печатается только форма, а не вся страница).
• EnterKeyMode - как будет обрабатываться нажатие на Enter на поле. save - сохраняем форму. next -переход к следующему полю (но некоторые поля пропускают - Переключатель, HTML editor и другие сложные поля).
• HeaderTag - h1, h2, h3, h4, h5, h6 - позволяет указать тег для вывода заголовка формы.
• Hide - если 1, то компонент совсем не выведется (пустой div и установка класса hide).
• LineLabel - если 1, то при дефолтовой разметке формы метки полей будут выводиться на отдельной строке (по умолчанию они выводятся слева от элемента управления).
• NoForm - JSON настройки для вывода сообщения (например, нет доступа). При этом форма не показывается совсем - только вывод сообщения. Настройки: 
  • title - заголовок
  • text - текст сообщения
  • type - стилизация окна (success,warning,primary, info и т.д.)
  • icon - вывод иконки 
  • alert - если true, то будет выводиться не разметка в форме, а alert окошко справа вверху (в случае модальной формы - модальное окно будет закрываться)

• Subtitle - разметка под заголовком формы.
• Title - заголовок формы.
• TitleTooltip - подсказка-значок рядом с Title формы.        

3. SELECT 3 - дополнительные табличные данные (произвольные колонки) для вывода через jsRender разметку
   
   
4. SELECT 4 - вызов внешних действий. См. вызов внешних действий

Хранимая процедура проверки элемента CheckItem

CREATE PROCEDURE [dbo].[fm_test_checkItem]
  @username nvarchar(256),
  @itemID int,
  @parameters ExtendedDictionaryParameter READONLY
AS BEGIN -- процедура проверки корректности данных перед сохранением
  declare @ptitle nvarchar(max)
  select @ptitle = value from @parameters where [key] = 'title'

  declare @id int
  select @id = id from as_trace where header=@ptitle and id <> @itemID

  if(@id >0) begin
    select 0 Result, 'В системе уже есть элемент с выбранным Заголовком (ID='+cast(@id as nvarchar)+')' Msg
  end else begin
    select 1 Result, '' Msg
  end
END

Процедура возвращает модель ResultModel: Result, Msg

Если Result=1 то проверка прошла успешно.

Примечание: ранее использовался способ передачи колонок формы как параметров хранимой процедуры (он оставлен для совместимости). В настоящий момент используется коллекция @parameters для передачи колонок (также в рамках этой коллекции дополнительно передаются langID и falconGuid).

Если не хотите использвоать CheckItem - оставьте в ней только select 1 Result, '' Msg

Хранимая процедура сохранения элемента SaveItem

CREATE PROCEDURE [dbo].[fm_metric_saveItem]
  @username nvarchar(256),
  @itemID int,
  @parameters ExtendedDictionaryParameter READONLY
AS BEGIN

declare @pcode nvarchar(max), @ptitle nvarchar(max)

select @pcode = Value2 from @parameters where [key]='code'  -- всегда Value2, а не Value
select @ptitle = Value2 from @parameters where [key]='title'

update as_mt_metrics set code = @pcode, title = @ptitle
where id = @itemID


-- SELECT 1 select 1 Result, '' Msg, '' Icon, '' RefreshContainer, 10000 AlertDelay, 0 EnableSaveAlert, '' SuccessUrl, 0 HideFormAfterSubmit


-- SELECT 2 Внешние действия
-- select 'notification' type, 'text1' text , 'demo1' [to], 'ticketExecutor' typeCode, 'http///' url, 'add111' additional select 'email' type, 'ru@rudensoft.ru' [to], 'sub1' subject, 'body1' body

END

Входные параметры:

@username - текущий пользователь

@itemID - переданный параметр itemID

@parameters - коллекция параметров из URL (Key, Value)

Примечание: в @parameters используйте Key, Value2, помимо полей формы там находятся еще следующие параметры: 

• buttonType - код кнопки сохранения (если используется множесто кнопок сохранения на форме)
• confirmCode - код подтвержения операции (для спец режима работы формы по подтверждению действия)
• referrer - URL страницы, на которой расположена форма
• langID - ID языка пользователя
• falconGuid -Guid посетителя из куки (в том числе и неавторизованного). 
• falconFR - первый внешний источник, откуда пришел пользователь.
• falconFP - первая посещенная страница нашего сайта.
• userIP - IP пользователя
• userPort - порт, по которому обратился пользователь (обычно это 443 или 80)
• domain - домен сайта (в случае если используем несколько доменов для одного и того же сайта). 

Первый запрос (SELECT 1) возвращает модель:

• Msg - задает текст сообщения о результате операции (Если передать 1 пробел ' ', то сообщение не будет выводиться. Если пустая строка - то результат по умолчанию),
• Result - если 1 то операция успешно выполнена,
• ItemID - переданный начальный ItemID в форму,
• SuccessUrl - если непустая строка, то после выполнения операции осуществляется переход по этому адресу,
• HideFormAfterSubmit - если 1, то форма скрывается после сохранения (а модальное окно закрывается),
• RefreshContainer - селектор контейнера, который надо обновить (например, можно ставить глобальный контейнер на странице ‘.pHtml’). В итоге после сохранения происходит обновление других компонентов в рамках указанного контейнера,
• Refresh - если 1, то выполняется обновление компонента после операции.
• Actions - JSON для действий в браузере. 
• EnableSaveAlert - если 1, то результат будет всегда выдаваться во всплывающем окне справа наверху (даже несмотря на то, что есть {form-result}),
• Icon - если указано, то будет выводиться данная иконка в сообщении справа вверху. Пример: fa-cube (подробнее о стилизации иконок можно почитать здесь, об анимации иконок здесь), 
• AlertDelay - задержка показа окна результата в мс. По умолчанию 30000,
• Type - цветовое решение окна: danger, success, warning, info, primary и т.д., 
• Confirm - JSON объект для вывода окна подтверждения выполнения действия (поля title,text, btnText, confirmCode, system). См. Как сделать окно подтверждения действия формы.
• ReplaceContainer и ReplaceContainerHtml - если есть задача заменить HTML в каком-то блоке, то указываем селектор в ReplaceContainer и разметку в ReplaceContainerHtml.
• RunAction - задается разметка кнопки (например, с as-form-modal), которая будет активирована (событие click) после успешного выполнения SaveItem.

Второй запрос (SELECT 2) это вызов внешнего действия. См. вызов внешних действий

Примечание: ранее использовался способ передачи колонок формы как параметров хранимой процедуры (он оставлен для совместимости). В настоящий момент используется коллекция @parameters для передачи колонок (также в рамках этой коллекции дополнительно передаются langID и falconGuid)

Хранимая процедура сохранения одиночного поля SaveField

CREATE PROCEDURE [dbo].[fm_metric_saveEditableField]
  @pk nvarchar(128),	  -- id for item
  @fieldCode nvarchar(64), -- form field @value nvarchar(max),	-- field value
  @username nvarchar(256) -- current user
AS BEGIN

  if(@fieldCode='XXXXXXXXXXXXXXXXXXXXX') begin
    update as_categories set typeCode = @value where id = @pk
    select 1 Result, '' Msg return
   end
  -- ...
  --SELECT 1 Result,Msg select 0 Result, 'Не найден код сущности' Msg
  -- SELECT 2 Внешние действия (notification, email и т.д.)

END

Возвращает SELECT 1 (Result, Msg) и SELECT 2 (Внешние действия)

SELECT 1 

• Result - результат операции  
• Msg - сообщения
• Icon - иконка Font Awesome
• Type - тип окна (primary, success и т.д.)
• RefreshContainer - jquery селектор для обновления части страницы (какую область страницы с компонентами обновить, например ".class1")
• Actions - JSON для действий в браузере. 
• ShowContainer - какой контейнер показать, jquery selector
• HideContainer - какой контейнер скрыть, jquery selector
• ReplaceContainer и ReplaceContainerHtml - если есть задача заменить HTML в каком-то блоке, то указываем селектор в ReplaceContainer и разметку в ReplaceContainerHtml.
• Refresh - если 1, то выполняется обновление компонента после операции.

Также в процедуру можно передавать параметр @parameters типа ExtendedDictionaryParamerer для передачи спец параметров (langID и falconGuid).

Хранимая процедура для заполнения списковых полей

Имя процедуры задается автоматически в виде fm_{formCode}_{colCode}_dict и процедура редактируется через кабинет в Управление колонками.

CREATE PROCEDURE [dbo].[fm_notificationType_categoryName_dict]
  @username nvarchar(256)
  @itemID int
AS BEGIN
  select 'Не выбрано' Text, 0 Value, 0 Selected -- 'Group1' optGroup для категорий в списке. (и по нему же должна быть сортировка)
  union
  select name Text, id Value, Selected from as_nt_notificationCategories order by Text

END

Передается ItemID на случай использования универсальной процедуры.

На выходе модель:

• Value - значение варианта выбора, 
• Text - выводимые текст варианта,
• Selected - если 1, то элемент будет выбран,
• Disabled - если 1, то элемент будет недоступен для выбора,
• OptGroup - строковая метка для организации двухуровневых списков (важно, чтобы сортировка была по этому параметру),
• Color - цвет элемента, например, #ffa
• Value2 - (в некоторых особых случаях используется это поле).

Примечание.

1. В процедуру может передаваться необязательный параметр @parameters DictionaryParameter в котором передаются системные параметры (langID, falconGuid)
2. Ранее использовалось поле для хранения имени процедуры. Он остался рабочим для совместимости. Сейчас это поле не выводится и вместо него необходимо использовать новые процедуры с редактированием через кабинет.
3. Если нужен элемент Не выбрано, то можно сделать  union select 0 Value, ‘Не выбрано’ Text
4. OptGroup используется для организации списка с категориями (для этого первый optGroup должен быть непустым и список должен быть упорядочен по optGroup).
5. Если установлен Color - то список и его элементы будут иметь указанные цвета. 
6. Если стоит Disabled=1, то элемент списка будет неактивен. 

Хранимая процедура для проверки одиночных полей при заполнении формы CheckItemField

Если существует подобная процедура с именем fm_{entity}_checkItemField, то она будет вызываться всякий раз, когда редактируется одно из полей формы.

Входные параметры:

@username - текущий пользователь

@itemID - переданный параметр itemID

@field - код поля

@value - текущее значение поля

@parameters - коллекция параметров из URL (Key, Value2)

CREATE PROCEDURE [dbo].[fm_metric_checkItemField]
  @username nvarchar(256),
  @itemID int,
  @field nvarchar(256),
  @value nvarchar(max),
  @parameters ExtendedDictionaryParameter readonly -- необязательный
AS BEGIN
  if(@field = 'roles') begin
   if(charindex(' ', @value)>0) begin
     select 'В ролях не должно быть пробелов!' Msg, 0 Result, '.projectStageCont' RefreshContainer, '.p1' ShowContainer, '.p2' HideContainer, '' ReplaceContainer, '' ReplaceContainerHtml
    end
   end

   -- SELECT 1
   select '' Msg, 1 Result

   -- SELECT 2 Outer actions

END

На входе - ID сущности, код поля, значение и текущий пользователь.

В процедуру можно передавать параметр @parameters типа ExtendedDictionaryParamerer (Key, Value2) для передачи спецпараметров (langID и falconGuid) и текущие значения других полей формы.

Этот параметр также используется для извлечения данных, полученных из внешнего API. 

На выходе:

SELECT 1

• Msg - сообщение 
• Result - 1 или 0 (если 0 - значит поле невалидное)
• RefreshContainer - jquery селектор для обновления части страницы (какую область страницы с компонентами обновить, например ".class1")
• ShowContainer - какой контейтер показать, jquery selector
• HideContainer - какой контейтер скрыть, jquery selector
• ReplaceContainer и ReplaceContainerHtml - если есть задача заменить HTML в каком-то блоке, то указываем селектор в ReplaceContainer и разметку в ReplaceContainerHtml.

SELECT 2 - вызов внешних действий

Также вы можете задать коллбек для обработки в JS результата проверки поля - as.formcallbacks["{formCode}_checkField"](params, data).