Falcon Space. Работа с формами

Описание компонента Форма

Пример форм можно посмотреть на демостенде компонентов.
Формы используются для создания сущностей (itemID=0), а также для редактирования параметров некой сущности (itemID>0).
Форма может содержать либо стандартную, либо кастомную разметку.

Пример формы без параметров - интерактивный виджет статистики на демостенде.

Howto по формам можно посмотреть здесь - howto по формам Falcon Space.

Для вывода формы на странице используется сниппет

<div class="as-form" data-code="{code}" data-itemid="falcon-space--rabota-s-formami">div>


Для создания формы необходимо сделать следующее:

  • Создать форму в разделе Формы
  • Настроить параметры формы
  • Настроить поля формы
  • Создать хранимую процедуру fm_{code}_getItem (для формы редактирования. Она получает данные для загрузки текущего состояния формы. Для формы добавления это не нужно делать).
  • Создать хранимую процедуру fm_{code}_checkItem. Она вызывается для проверки полей формы перед сохранением. Если ее нет, то проверка не производится.
  • Создать хранимую процедуру fm_{code}_saveItem. Она сохраняет в базе значения формы при нажатии на кнопку Сохранить.

Настройка параметров формы

Также среди настроек есть 3 параметра подключения внешних источников (коды API запросов через запятую, для выполнения исходящих запросов при различных событиях формы):

  • GetItem API - запускается перед GetItem процедурой (загрузка формы).
  • SaveItem API - запускается перед SaveItem процедурой (нажали кнопку Сохранить).
  • CheckField API - запускается перед CheckField процедурой (изменили поле).

Результат ответ запроса API передается в хранимую процедуру через параметр @parameters ExtendedDictionaryKey (в Key пишется код запроса). 

Документация по запросам API

Если вам требуется на форме кнопка очистки полей формы - используйте любую кнопку  классом as-form-reset

<a href="#" class="as-form-reset">Reset form</a>

Настройка колонок формы

Примечание

  • В настройках формы для процедур sqlCheckItem и в sqlSaveItem должно быть ровно столько параметров сколько есть в форме и у них есть префикс в виде "field".
  • В параметр data-itemID можно передать значение - оно будет заменяться на значение URL параметра param1. Это необходимо для формы редактирования. Для формы добавления data-itemID необходимо установить в 0.
  • Ширину поля формы можно устанавливать в любых единицах CSS - px, % и др.
  • Имена хранимых процедур - fm_{code}_functionName
  • Пример кастомной разметки формы:

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

Основные хранимые процедуры GetItem, CheckItem и SaveItem делаем через панель управления. Крайне важно следовать общему стилю и виду шаблонных процедур (они имеют префикс 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


END

Первый запрос возвращает сущность, второй дополнительные параметры формы(можно изменить заголовок, подзаголовок).

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

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

3 селекта для вывода формы:

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

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

  • тип поля можно переопределить через type_{colCode}
  • возможные дополнительные CSS классы к элементам ставится через class_{colCode}.
  • можно указать что поле можно одиночно редактировать через префикс edt_{colCode}.
  • можно указать дополнительные подсказки для поля (при клике на них будет меняться значение поля)  example_{colCode}. В качестве значения можно указать несколько значений через "||", например value1||value2||value3
  • disableXSS_{colCode}. Если 1 то отключает проверку XSS на данном поле. 
  1. SELECT 2 - Настройки формы.
  • Title - заголовок формы
  • Subtitle - разметка под заголовком формы
  • EnablePrint - если 1, то появляется кнопка отправки на печать (печатается только форма, а не вся страница).
  • Background (код фона формы, напр success) - задает фон формы.
  • ButtonText - текст у кнопки действия (Сохранить).
  • EditableSuccessMessage - задает текст сообщения об успешном изменении одиночного поля.
  • ChangeTriggerFieldOnLoad - если указано поле формы, то при загрузке будет вызвано событие изменения поля (например, чтобы прогрузить некоторые данные через ChangeitemField). 
  • DisableFocusOnLoad - если 1, то при загрузке формы по умолчанию не будет ставиться фокус ввода на 1 поле формы (актуально когда несколько форм на странице). 
  • DisableAntiXSS  - если 1, то для полей ввода будет отключена обработка HTML Encode (т.е. защита от XSS будет отключена и ее надо частично будет реализовать в коде SQL).

        

  1. SELECT 3 - дополнительные табличные данные (произвольные колонки) для вывода через jsRender разметку

    Хранимая процедура проверки элемента 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 = Value from @parameters where [key]='code'
    select @ptitle = Value from @parameters where [key]='title'
    
    update as_mt_metrics set code = @pcode, title = @ptitle
    where id = @itemID
    
    
    -- SELECT 1 select 1 Result, '' Msg
    -- 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

    Примечание: в @parameters используйте Key, Value2 

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

    • Msg - задает текст сообщения о результате операции,
    • Result - если 1 то операция успешно выполнена,
    • SuccessUrl - если непустая строка, то после выполнения операции осуществляется переход по этому адресу,
    • HideFormAfterSubmit - если 1, то форма скрывается после сохранения (а модальное окно закрывается),
    • RefreshContainer - селектор контейнера, который надо обновить (например, можно ставить глобальный контейнер на странице ‘.pHtml’). В итоге после сохранения происходит обновление других компонентов в рамках указанного контейнера.
    • EnableSaveAlert - если 1, то результат будет всегда выдаваться во всплывающем окне справа наверху (даже несмотря на то, что есть {form-result}). 

    Второй запрос (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 (Внешние действия)

    Также в процедуру можно передавать параметр @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, OptGroup, Color.

    Примечание.

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

     

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

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

    CREATE PROCEDURE [dbo].[fm_metric_checkItemField]
      @username nvarchar(256),
      @itemID int,
      @field nvarchar(256),
      @value nvarchar(max)
    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 '' Msg, 1 Result
    
    END
    

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

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

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

    На выходе:

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

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

    Хранимая процедура отображения статуса заполнения формы Progress

    CREATE PROCEDURE [dbo].[fm_knowledgeBaseArticle_progress]
      @username nvarchar(256),
      @itemID int,
      @parameters ExtendedDictionaryParameter Readonly
    AS BEGIN
      -- процедура для визуализации прогресса формы
      declare @fieldchannel nvarchar(max) = ''
      select @fieldchannel = value from @parameters where [key]='channel'
    
      -- SELECT 1 select 1 Result, '' Msg
      -- SELECT 2 набор индикаторов прогресса
       select 'Первый параметр' Title, 40 Value, 'Хорошо' [Text]
       union
       select 'Второй параметр' Title, 20 Value, 'Не очень' [Text]
    
    END
    

    Пример: [fm_example_progress]

    На входе все элементы формы (передаются из несохраненной формы в параметре @parameters, там же передаются langID и falconGuid). 

    На выходе: 

    SELECT 1 - Result, Msg

    SELECT 2 - Text, Value (от 0 до 100), Title

    Этап процедура вызывается, если установлен тип прогрессбара в GetItem Select 1: 'circle|line' ProgressType

    Вызывается при каждом изменении элементов формы и выводится там где разметка {form-progress}

    Примечание: 

    Круговая диаграмма работает только со значениями, кратными 10 (т.е. округляет до десятков). Если вам нужно использовать точные значения (например, отображать скидку в 3.5%, то используйте line режим для отображения прогресса). 

    Типы полей формы

    Пример полей формы на демостенде

    Вы можете использовать следующие типы полей

    1. Строка, string - текстовое поле в 1 строку
    2. Целое число,        int - целочисленное число
    3. Дробное число, float - число с плавающей точкой
    4. Дата выбор, date - выбор даты через плагин Datepicker (формат устанавливается в GetLayoutInfo в параметре dateFormat).
    5. HTML, html - выбор Rich редактора tinyMCE
    6. HTML Lite, html-lite  - выбор Rich редактора tinyMCE в упрощенном виде
    7. Флажок, bool - чекбокс
    8. Переключатель, switch - чекбокс в виде переключателя (Да, Нет). В placeholder можно задать текст вместо Да/Нет. Для изменения размера можно передать классы в GetItem SELECT 1 ( 'as-switch-large' class_immediatelyLoad).  as-switch-large, as-switch-mini, as-switch-small
    9. Список, select - комбосписок для одиночного выбора
    10. Список chosen, chosen - выбор из списка с возможностью поиска
    11. Список множественный chosen, chosenMiltiple - множественный выбор элементов из списка (в сохранение они идут как id через запятую).
    12. Многострочный текст, text - вывод textarea
    13. Список-поиск, select-search - поиск через autocomplete
    14. Слайдер значений, slider - выбор числа или диапазона чисел в виде ползунка. 
    15. Выбор radio, radio - одиночный выбор через радиокнопки (в стиле связанных кнопок Bootstrap)
    16. Стандартный выбор radio, defaultRadio - стандартный выбор из радиополей.
    17. Картинки Radio, imageRadio - выбор через радиокнопки с картинкой
    18. Картинки Флажки, imageCheckboxes - выбор флажков с картинками.
    19. Флажки, checkboxes - множественный выбор через галочки
    20. Editor (HTML), editorHTML - редактор HTML с подсветкой синтаксиса
    21. Editor (SQL), editorSQL - редактор SQL с подсветкой синтаксиса
    22. Editor (CSS), editorCSS - редактор CSS с подсветкой синтаксиса
    23. Editor (JS), editorJS - редактор JS с подсветкой синтаксиса
    24. HTML5 Color, html-color - редактирование цвета
    25. HTML5 Email, html-email - редактирование email
    26. HTML5 Month, html-month - выбор месяца. Формат сохранения YYYY-MM.
    27. HTML5 Week, html-week - выбор недели. Формат сохранения 2020-W01 (YYYY-WWW).
    28. HTML5 Number, html-number - выбор числа
    29. HTML5 Tel, html-tel - поле для телефона (установка формата делается через GetLayoutInfo, параметр phoneFormat)
    30. HTML5 Url, html-url - поле для ввода URL
    31. HTML5 Date, html-date - поля для ввода даты. Форма сохранения YYYY-MM-DD (и не зависит от настройки в GetLayoutInfo dateFormat!)
    32. HTML5 Time, html-time - поле для ввода времени/ Формат сохранения  HH:MM
    33. HTML5 Datetime local, html-datetime-local - поле для ввода даты и времени без учета часового пояса. Формат сохранения YYYY-MM-DDTHH:MM,  ВАЖНО - datatime-local не работает в Firefox (поэтому используйте в большинстве случаев поля date + time).
    34. Выбор места (гео), geo-autocomplete - вывод поля с поиском геолокации. Формат хранения значения - {lat}||{lon}||{geotext}||{JSONOptions}
    35. Ввод пароля, password - используется в формах регистрации. Скрывает ввод в виде звездочек.
    36. Содержимое файла, fileContent - загрузка файла через менеджер ресурсов и передача его содержимого в SQL процедуру в виде строки.
    37. Файл на внешнем ресурсе, remoteFile - указание URL и передача в процедуру saveItem тела файла, загруженного по данному URL.
    38. Выбор файла, files - можно добавлять файлы к форме (в том числе и в форме на добавление, когда еще нет сущности, к которой привязывать файлы).
    39. Таймер, timer - поле, которое позволяет запускать таймер по секундам. Время в итоге передается в виде mm:ss. 
    40. localStorage, sessionStorage, cookie, urlParameter - скрытые поля для передачи параметров в saveItem из куки, локальных ресурсов браузера или из URL. 
    41. Цвет множ. colorCheck, цвет colorRadio - выбор цвета (одиночный и множественный). В value - цвет, в text - текст (необязательно). 

    Примечание: если HTML5 будут введены некорректно, то они подсвечиваются розовым и форма не будет сохраняться, пока не будут исправлены ошибки.

    Форма с редактированием по отдельным полям (мгновенное сохранение полей, editable поля).

    Можно сделать форму, где каждое поле будет сохраняться отдельно.

    Для этого необходимо сделать следующее:

    1. В GetItem установить какие поля будут редактируемые, для этого добавляем в SELECT 1 выходные колонки вида 1 edt_{colName} (тем самым эти колонки будут реагировать на изменения и вызывать сохранение этих полей).
    2. Реализовать процедуру SaveField (сохранение отдельных полей формы).
    3. Кнопку Сохранить либо скрыть через CSS, либо использовать кастомную разметку формы и не вставлять кнопку в разметку.  

    Примечание:

    1.  Данный режим сохранения подходит для полей ввода, галочек, радиопереключателей, textarea, выбора из списка. Режим не работает для набора галочек и для сложных полей типа Code Editor.

    2. Если вам необходимо установить вывод сообщения после успешного сохранения поля, то используйте в процедуре формы GetItem в SELECT 2 параметр EditableSuccessMessage (строка).

    Форма без параметров

    Данная форма может использоваться для выполнения каких либо действий.

    Т.е. выводим информацию с помощью Getitem и кастомной разметки + выполняем действие.

    Важно! В процедурах CheckItem и SaveItem не должно быть параметров fieldName.

    Решение проблем

    Не получается корректно сохранить скрипт в форме

    При использовании 

    <script></script>

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

    Ошибка при начальной загрузке формы

    fm_{code}_getItem - всегда должна возвращаться какой-то результат. Если ваша форма на добавление, то можете просто возвращать select 1.

    Криво выводятся подписи для элементов формы

    Используйте разметку bootstrap для скелета формы (классы row, col-md-X и т.д.). Для меток используйте тег label с класс as-form-cap.

    Кастомная разметка формы будет иметь примерно такой вид:

    <div class="row">
    
    <div class="col-lg-1 col-md-1 col-sm-1 col-xs-12"><label class'as-form-cap="">Название</label></div> <div class="col-lg-4 col-md-4 col-sm-4 col-xs-12">{colcontrol-title}</div>
    
    <div class="col-lg-1 col-md-1 col-sm-1 col-xs-12"><label class'as-form-cap="">Код</label></div> <div class="col-lg-4 col-md-4 col-sm-4 col-xs-12">{colcontrol-code}</div>
    
    <div class="col-lg-1 col-md-1 col-sm-1 col-xs-12"><label class'as-form-cap="">Порядок</label></div>
    
    <div class="col-lg-4 col-md-4 col-sm-4 col-xs-12">{colcontrol-ord}</div>
    
    </div>

    Полный список вопросов, как реализовать ту или иную возможность на форме, описан в разделе Howto Формы.

    Платформа Falcon Space

    Это снижение стоимости владения

    за счет меньшего количества людей для поддержки

    Это быстрое внесение изменений

    по ходу эксплуатации программы

    Это современный интерфейс

    полная адаптация под мобильные устройства

    Бесплатное обучение разработке на Falcon Space

    Вы можете разрабатывать самостоятельно или сотрудничать с нами в плане веб-разработки на платформе Falcon Space.
    Примечание