================================ Валидация и процессинг страницы ================================ Для формирования полноценного приложения требуется взаимодействие с пользователем. Всё, что делает пользователь, необходимо складывать в базу данных. Однако пользователь может испортить приложение введя не корректные данные – возложите сохранение и проверку данных на XRAD. Валидация страницы ------------------- В любом приложении имеются формы взаимодействия с пользователями, но некорректные данные, введенные пользователем, могут навредить приложению. Поэтому перед отправкой данных используют валидацию данных. Что такое валидация ~~~~~~~~~~~~~~~~~~~~ *Валидация* – это проверка корректности введенных пользователем данных в поля ввода формы. Для системы XRAD – это различные функции и процедуры, которые выполняются перед тем как данные будут отправлены на сервер для обработки. На случай возникновения исключения у разработчика имеется возможность задать текст сообщения, который будет отображен пользователю. Разработчику доступно 11 типов валидаторов: 1. *Exists (SQL query returns at least one row)* – позволяет выполнить проверочный SQL-запрос. Проверка считается пройденной успешно, если запрос вернул хотя бы 1 строку; 2. *Value of Item / Column in Expression 1 Is NOT NULL* – встроенная проверка на заполненность поля или ячейки таблицы. Проверка считается пройденной успешно, если поле ввода или ячейка таблицы содержит какое-либо значение; 3. *Value of Item / Column in Expression 1 != Zero* – встроенная проверка на значение отличное от 0 (нуль) поля ввода или столбца таблицы. Проверка считается пройденной успешно, если объект проверки будет содержать значение отличное от 0 (нуль); 4. *Value of Item / Column in Expression 1 Is NULL* – встроенная проверка на значение *NULL* (пустое значение) поля ввода или столбца таблицы. Проверка считается пройденной успешно, если объект проверки содержит *NULL* (пустое значение); 5. *Value of Item / Column in Expression 1 Is NULL or Zero* – встроенная проверка на значение *NULL* (пустое значение) или 0 (нуль) поля ввода или столбца таблицы. Проверка считается пройденной успешно, если объект проверки содержит *NULL* (пустое значение) или равно 0 (нуль); 6. *Value of Item / Column in Expression 1 = Zero* – встроенная проверка на значение 0 (нуль) поля ввода или столбца таблицы. Проверка считается пройденной успешно, если объект проверки будет содержать значение 0 (нуль); 7. *Value of Item / Column in Expression 1 Is NOT null and the Item / Column Is NOT Zero* – встроенная проверка на заполненность и значение отличное от 0 (нуль) поля ввода или столбца таблицы. Проверка считается пройденной успешно, если объект проверки не содержит *NULL* (пустое значение) и не равно 0 (нуль); 8. *NOT Exists (SQL query returns no rows)* – позволяет выполнить проверочный SQL-запрос. Проверка считается пройденной успешно, если запрос не вернул ни одной строки; 9. *SQL Expression* – позволяет выполнить SQL-запрос возвращающий *TRUE* или *FALSE*. В поле ввода запроса указывается только тело запроса, без ключевых слов *SELECT* и/или *FROM*. Если необходимо выполнить какой-то подзапрос, то его необходимо обернуть в “(” “)”. Проверка считается пройденной успешно, если запрос вернул *TRUE*; 10. *Function returning Error Text* – позволяет выполнить SQL-запрос возвращающий текст ошибки. В поле запроса необходимо указать полноценный запрос возвращающий строку. Проверка считается пройденной успешно, если запрос вернул *NULL*. В противном случае будет отображен возвращенный запросом текст ошибки; 11. *Regular Expression* – позволяет проверить значение поля формы по регулярному выражению. В поле *Item* указывается проверяемое поле, а в поле *Value* регулярное выражение. Проверка считается пройденной успешно, если значение поля *Item* будет соответствовать регулярному выражению. Однако имеется отдельный тип валидации – это флаг обязательности заполнения поля формы. Для любого поля ввода можно поставить флаг что поле обязательно для заполнения. В таком случае, даже если не сформировать иных валидаторов, при попытке отправить данные на сервер будет проведена проверка на заполненность поля. Что происходит когда валидация не выполняется ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ В случае возникновения исключения в любом, из присутствующих на форме, валидаторе отправка на сервер блокируется и пользователю выдается заданное разработчиком предупреждение. Если валидатор привязан к полю ввода, то так же будет подсвечено поле ввода, на котором произошло исключение. .. _Создание валидации: Создание валидации ~~~~~~~~~~~~~~~~~~~ Для создания валидатора необходимо системе xRadBuilder открыть на редактирование страницу формы, на которой планируется произвести валидацию и в левой части перейти на вкладку (процессы). .. image:: /_static/images/creatval.png :width: 700 Далее щелкнуть ПКМ по раскрывающемуся списку Validations. .. image:: /_static/images/creatvalid2.png :width: 400 Далее выбрать Create Validation. Будет создан шаблон валидатора где автоматически будет сгенерировано имя валидатора и его порядковый номер. .. image:: /_static/images/creatvalid3.png :width: 700 В шаблоне валидатора обязательные поля будут подсвечены красным. Сразу после создания обязательно требуется выбрать только тип проверки (о типах проверки будет рассказано в разделе :ref:`Про роли пользователей <Про роли пользователей>`). .. image:: /_static/images/creatvalid4.png :width: 500 В зависимости от выбранного типа проверки будет отображено дополнительное поле, которое требуется обязательно заполнить. .. image:: /_static/images/creatvalid5.png :width: 700 По желанию можно указать к какому полю ввода относится валидатор. В этом случае при возникновении исключения поле будет подсвечено как ошибочное и текст ошибки будет отображен под этим полем. .. image:: /_static/images/creatvalid6.png :width: 500 Так же, по желанию, в блоке Server-side Condition можно указать в зависимости от каких условий должна выполняться валидация. Отображение ошибок валидации ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Если поле отмечено как обязательное, но оно не заполнено, то можно валидаторы не создавать, а пользователь будет уведомлен о необходимости заполнить обязательные поля всплывающей подсказкой красного цвета, а так же красной подписью под полем ввода, на котором возникла ошибка: .. figure:: /_static/images/creatvalid7.png :scale: 100 % :align: center :alt: Не заполнены обязательные к заполнению поля Однако, если на поле требуется дополнительно добавить иную обработку, то необходимо создать валидатор. А для удобства пользователя привязать валидатор к полю ввода. В таком случае сначала будет выполнена проверка на заполенность, а затем будет запущен созданный валидатор и, в случае возникновения ошибки, она так же будет показана во всплывающей подсказке и текст будет продублирован под полем ввода: .. figure:: /_static/images/creatvalid8.png :scale: 100 % :align: center :alt: Выполнение дополнительной проверки корректности введенных данных в поле Условия для выполнения валидации ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Так как проверки выполняются автоматически при submit страницы, то часто возникают ситуации когда необходимо ограничить их выполнение. Для этого в системе XRAD предусмотрен блок условий, по которым выполняются проверки. .. image:: /_static/images/creatvalid9.png :width: 500 Разработчику доступно 11 типов условий выполнения валидатора: 1. *Always* – выполняется всегда; 2. *Exists* (SQL query returns at least one row) – позволяет выполнить проверочный SQL-запрос. Условие считается выполненным, если запрос вернул хотя бы 1 строку; 3. *Value of Item / Column in Expression 1 Is NOT NULL* – встроенное условие на заполненность поля или ячейки таблицы. Условие считается выполненным, если поле ввода или ячейка таблицы содержит какое-либо значение; 4. *Value of Item / Column in Expression 1 != Zero* – встроенное условие на значение отличное от 0 (нуль) поля ввода или столбца таблицы. Условие считается выполненным, если объект проверки будет содержать значение отличное от 0 (нуль); 5. *Value of Item / Column in Expression 1 Is NULL* – встроенное условие на значение *NULL* (пустое значение) поля ввода или столбца таблицы. Условие считается выполненным, если объект проверки содержит NULL (пустое значение); 6. *Value of Item / Column in Expression 1 Is NULL or Zero* – встроенное условие на значение *NULL* (пустое значение) или 0 (нуль) поля ввода или столбца таблицы. Условие считается выполненным, если объект проверки содержит *NULL* (пустое значение) или равно 0 (нуль); 7. *Value of Item / Column in Expression 1 = Zero* – встроенное условие на значение 0 (нуль) поля ввода или столбца таблицы. Условие считается выполненным, если объект проверки будет содержать значение 0 (нуль); 8. *Value of Item / Column in Expression 1 Is NOT null and the Item / Column Is NOT Zero* – встроенное условие на заполненность и значение отличное от 0 (нуль) поля ввода или столбца таблицы. Условие считается выполненным, если объект проверки не содержит NULL (пустое значение) и не равно 0 (нуль); 9. *NOT Exists (SQL query returns no rows)* – позволяет выполнить проверочный SQL-запрос. Условие считается выполненным, если запрос не вернул ни одной строки; 10. *SQL Expression* – позволяет выполнить SQL-запрос возвращающий *TRUE* или *FALSE*. В поле ввода запроса указывается только тело запроса, без ключевых слов *SELECT* и/или *FROM*. Если необходимо выполнить какой-то подзапрос, то его необходимо обернуть в “(” “)”. Условие считается выполненным, если запрос вернул *TRUE*; 11. *Never* – не выполнять ни когда. .. _Процессинг страницы: Процессинг страницы -------------------- При работе приложения часто требуется выполнять запросы к базе данных (далее БД). Для этих целей в системе XRAD предусмотрены процессы различных видов. Управление процессами происходит по генерации приложением различных запросов (*Requests*). При появлении запроса от приложения выполняются все процессы соответствующего запросу типа в порядке очередности (*Sequence*). Что такое процесс ~~~~~~~~~~~~~~~~~~ **Процесс** – это механизм взаимодействия приложения с базой данных. В системе XRAD предусмотрены следующие виды процессов: 1. *Before page load* – процессы данного вида выполняются непосредственно перед загрузкой страницы. Их основное назначение подготовить окно для взаимодействия с пользователем (например заполнить поля формы значениями из БД); 2. *Process* – процессы данного вида выполняются при отправке формы на сервер; 3. *Ajax Callback* – процессы данного вида призваны взаимодействовать с БД по требованию от JS-скрипта. Процессы первых 2 видов так же могут самостоятельно взаимодействовать с пользователем сообщая об успешности выполнения запроса или о возникшей ошибке. Ответ от процессов третьего вида должен обрабатываться разработчиком в JS-скрипте. По завершению работы процесса с типом Process автоматически возможно выполнить такие действия как: 1. закрытие диалогового окна – *Accept Modal* 2. переход на другую страницу – *Branches* 3. загрузка файла – *Downloads* Создание процесса ~~~~~~~~~~~~~~~~~~ Для создания процесса необходимо в системе xRadBuilder открыть на редактирование страницу формы, для которой планируется сформировать процесс и в левой части перейти на вкладку (процессы). .. image:: /_static/images/validproc.png :width: 700 Далее можно щелкнуть ПКМ по раскрывающемуся списку Process .. image:: /_static/images/validproc1.png :width: 700 и выбрать Create Process. Будет создан шаблон процесса типа Process где автоматически будет сгенерировано имя процесса и его порядковый номер. При данном варианте потребуется указать тип процесса (Process Point) и SQL-запрос. Заполнение других полей будет зависеть от выбранного типа процесса и целесообразности .. image:: /_static/images/validproc2.png :width: 700 Так же можно развернуть блок Process – буду показаны типы процессов: * *Before page load* – при щелчке на который ПКМ будет предложено 2 варианта: * *Create Process* – будет создан шаблон процесса выполняемого перед загрузкой страницы; * *Create Branch* – будет создан шаблон процесса, по выполнению условия (Server-side Condition) которого произойдет перенаправление на другую страницу. .. image:: /_static/images/validproc3.png :width: 700 * *Process* – при щелчке на который ПКМ будет предложен 1 вариант: * *Create Process* – будет создан шаблон процесса .. image:: /_static/images/validproc4.png :width: 700 * *Ajax Callback* – при щелчке на который ПКМ будет предложен 1 вариант: * *Create Process* – будет создан шаблон AJAX процесса При создании процесса через меню любого из типов поле типа процесса (Process Point) будет заполнено согласно выбранного типа. В шаблоне процесса обязательные поля будут подсвечены красным. Для большинства процессов сразу после создания обязательно требуется заполнить только выполняемый SQL-запрос. .. image:: /_static/images/validproc5.png :width: 200 Однако, для процессов типа Download так же обязательными являются поля Request Name, File Name Column и File Content Column .. image:: /_static/images/validproc6.png :width: 200 а для типа Branch обязательным является только поле Link .. image:: /_static/images/validproc7.png :width: 200 Для недопущения неконтролируемого выполнения процессов рекомендуется всем процессам указывать поле Request Name или выставить условие в блоке Server-side Condition. Редактирование процесса ~~~~~~~~~~~~~~~~~~~~~~~~ Для редактирования процесса необходимо в системе xRadBuilder открыть на редактирование страницу формы, на которой расположен процесс и в левой части перейти на вкладку (процессы). .. image:: /_static/images/validproc8.png :width: 700 Далее выбрать требуемый процесс и внести в его настройки требуемые изменения. Условия выполнения процесса ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Для выполнения процесса есть 2 вида условий: 1. выполнение по запросу (*Request*); 2. условие на стороне сервера (*Server-side condition*) Выполнение по запросу (Request) """""""""""""""""""""""""""""""" При работе приложение постоянно посылает различные запросы. Будь то *submit* страницы или запрос из JS-скрипта. В зависимости от источника запроса исполняются процессы различного типа, но их всех объединяет вид исполнения – выполняются все процессы одного типа в порядке очередности. Для того, чтобы на запрос не были выполнены не нужные процессы используется поле *Request Name*: .. image:: /_static/images/validproc9.png :width: 500 Если поле *Request Name* пустое, то процесс будет выполнен при любом запросе со стороны приложения, если тип процесса подходит под тип запроса. Однако, если указать конкретное имя запроса в поле *Request Name*, то процесс будет выполнен только в том случае, если имя запроса, посланного приложением, совпадет с именем в поле *Request Name*. Того же эффекта можно достичь используя условие на стороне сервера (*Server-side Condition*) с типом **SQL Expression**, а в качестве входного поля указать поле **REQUEST** Условие на стороне сервера (Server-side condition) """"""""""""""""""""""""""""""""""""""""""""""""""" .. image:: /_static/images/validproc10.png :width: 500 Разработчику доступно 11 типов условий выполнения процесса: 1. *Always* – выполняется всегда; 2. *Exists (SQL query returns at least one row)* – позволяет выполнить проверочный SQL-запрос. Условие считается выполненным, если запрос вернул хотя бы 1 строку; 3. *Value of Item / Column in Expression 1 Is NOT NULL* – встроенное условие на заполненность поля или ячейки таблицы. Условие считается выполненным, если поле ввода или ячейка таблицы содержит какое-либо значение; 4. *Value of Item / Column in Expression 1 != Zero* – встроенное условие на значение отличное от 0 (нуль) поля ввода или столбца таблицы. Условие считается выполненным, если объект проверки будет содержать значение отличное от 0 (нуль); 5. *Value of Item / Column in Expression 1 Is NULL* – встроенное условие на значение *NULL* (пустое значение) поля ввода или столбца таблицы. Условие считается выполненным, если объект проверки содержит *NULL* (пустое значение); 6. *Value of Item / Column in Expression 1 Is NULL or Zero* – встроенное условие на значение *NULL* (пустое значение) или 0 (нуль) поля ввода или столбца таблицы. Условие считается выполненным, если объект проверки содержит *NULL* (пустое значение) или равно 0 (нуль); 7. *Value of Item / Column in Expression 1 = Zero* – встроенное условие на значение 0 (нуль) поля ввода или столбца таблицы. Условие считается выполненным, если объект проверки будет содержать значение 0 (нуль); 8. *Value of Item / Column in Expression 1 Is NOT null and the Item / Column Is NOT Zero* – встроенное условие на заполненность и значение отличное от 0 (нуль) поля ввода или столбца таблицы. Условие считается выполненным, если объект проверки не содержит *NULL* (пустое значение) и не равно 0 (нуль); 9. *NOT Exists (SQL query returns no rows)* – позволяет выполнить проверочный SQL-запрос. Условие считается выполненным, если запрос не вернул ни одной строки; 10. *SQL Expression* – позволяет выполнить SQL-запрос возвращающий *TRUE* или *FALSE*. В поле ввода запроса указывается только тело запроса, без ключевых слов *SELECT* и/или *FROM*. Если необходимо выполнить какой-то подзапрос, то его необходимо обернуть в “(” “)”. Условие считается выполненным, если запрос вернул *TRUE*; 11. *Never* – не выполнять ни когда. Сообщения успешного выполнения или ошибки ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Процессы типа *Before page load* и *Process* могут самостоятельно взаимодействовать с пользователем сообщая об успешности выполнения или о возникновении ошибки. Текст, который будет показан пользователю при успешном выполнении процесса указывается в разделе *Success Message* .. image:: /_static/images/validproc11.png :width: 300 Текст, который будет показан пользователю при возникновении ошибки указывается в разделе *Error Message* .. image:: /_static/images/validproc12.png При успешном выполнении на запрос нескольких процессов будет показано сообщение об успешности только последнего процесса из цепочки. Управление транзакцией ~~~~~~~~~~~~~~~~~~~~~~~ При выполнении цепочки запросов к базе данных иногда возникает ситуация при которой возникновении ошибки в очередном шаге не должно приводить к отмене результатов предыдущих шагов. Эта ситуация разрешается завершением транзакции при успешном завершении процесса. Чтобы завершить транзакцию необходимо процессу выставить флаг завершения транзакции (*Commit TX*) .. image:: /_static/images/validproc13.png :width: 200 Если данный флаг не выставлен, то, в случае возникновения ошибки в любом из процессов, будут отменены все изменения внесенные другими процессами у которых так же не выставлен флаг завершения транзакции. Таким образом имеется возможность разбивать большое действие на группы более мелких действия ошибки в которых не будут влиять на действия выполненные в предыдущих группах. Закрытие диалога ~~~~~~~~~~~~~~~~~ В работе приложений часто используются модальные окна для выполнения некоторых действий. Например: создание пользователя. При нажатии на кнопку “Создать” выполняется некоторый, привязанный к кнопке, процесс. В таких случаях задача модального окна выполнена и окно можно закрыть. Для облегчения задачи у процессов имеется специальный флаг .. image:: /_static/images/validproc14.png :width: 200 При выставленном флаге в случае успешного выполнения процесса модальное окно будет автоматически закрыто с результатом *Accept*. При успешном выполнении на запрос нескольких процессов модальное окно будет закрыто автоматически только в случае, если у последнего из цепочки процессов выставлен флаг *Accept Modal*. .. _Глобальные процессы: Глобальные процессы -------------------- В главе :ref:`Процессинг страницы <Процессинг страницы>` были рассмотрены процессы привязанные к текущей странице. Однако, при работе приложения бывают ситуации когда необходимо выполнять один и тот же запрос к базе данных не зависимо от открытой страницы. Создавать на каждой странице приложения одинаковые процессы – не выход. Для этого предназначены глобальные процессы. Что такое глобальный процесс ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Глобальный процесс** – это процесс XRAD не имеющий привязки к какой-либо странице. Такие процессы, так же как и процессы на страницах, выполняются по команде от приложения (*Request*). Порядок выполнения глобального процесса ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ При появлении команды от приложения сначала выполняются все удовлетворяющие условиям команды глобальные процессы в порядке следования (*Sequence*), затем процессы текущей открытой страницы. Асинхронные процессы --------------------- При рассмотрении процессов в разделе :ref:`Процессинг страницы <Процессинг страницы>` был упомянут такой тип процессов как *Ajax Callback*. Данный тип процессов позволяет выполнить запрос к базе данных из JS-скрипта приложения. А так же получить результат выполнения и обработать его в рамках скрипта. Отличие данного типа процессов от других состоит в том, что процесс не может взаимодействовать с пользователем через поля *Success Message* и *Error Message*. Для возврата результата выполнения запроса в JS-скрипт доступна глобальная переменная *RESPONSE*. Создание асинхронного процесса ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Создание AJAX-процесса ни чем не отличается от создания простого процесса описанного в разделе :ref:`Создание валидации <Создание валидации>`. Если процесс должен вернуть какие-либо данные для обработки в скрипт, то в поле *Output Parameters* необходимо указать глобальную переменную *RESPONSE*. Переменная *RESPONSE* принимает только текстовый результат запроса. Вызов процесса ~~~~~~~~~~~~~~~ Для выполнения AJAX-процесса необходимо в JS-скрипте воспользоваться методом jsAPI.process: :: jsAPI.process("MyRequest", {}, { onSuccess: function (resp) { // Действия после успешного выполнения процесса // Если процесс возвращает какие-то данные в глобальную переменную RESPONSE, // то значение будет содержаться в параметре функции resp (тип JSON) в блоке data (resp.data) }, onError: function (e) { // Действия в случае возникновения ошибки при выполнении асинхронного процесса // Информация об ошибке будет передана в парметр функции e } }) Переходы между страницами (branches) ------------------------------------- При работе приложения бывают ситуации при которых необходимо произвести автоматический переход на некоторую страницу при загрузке выбранной или после выполнения какого-либо процесса. Для этих целей используются переходы между страницами (Branch). Если *Branch* расположен в блоке **Before page load**, то переход на указанную в поле Link страницу будет осуществлён при загрузке страницы, на которой расположен *Branch* при выполнении условия в блоке *Server-side Condition*. Для безусловного перенаправления в блоке *Server-side Condition* необходимо оставить значение *Always*, для отключения перенаправления – *Never*. Если *Branch* расположен в блоке *After Processing*, то переход на указанную в поле *Link* страницу будет осуществлён при завершении всех процессовпри выполнении условия в блоке *Server-side Condition*. Для безусловного перенаправления в блоке *Server-side Condition* необходимо оставить значение *Always*, для отключения перенаправления – *Never*.