Skip to content

values

Jump to bottom
do- edited this page Apr 9, 2020 · 15 revisions

Table of Contents

values

Вспомогательная функция, предназначенная для сбора данных с полей ввода (input и select) при запуске query и download.

Пример

Допустим, на экране отрисован HTML: 

 <div class=toolbar>
  <input name=q value=foo>
  <select name=status>
   <option selected>OK<option>
  </select>
 </div>

Тогда вызов 

 query ({}, {
  search: 
   values ($('.toolbar'))
 }, done)

инициирует AJAX-запрос (подробнее см. query), в POST-теле которого будет передано 

 {"q":"foo","status":"OK"}

а корректный JSON-ответ будет обработан функцией done().

Параметр

Единственный параметр — объект jQuery, содержащий (на любых уровнях вложенности) поля, которые требуется передать.

Результат

Функция values возвращает js-объект, ключами которого являются имена (атрибут name) полей input (кроме type=password), textarea и select.

Значениями для большинства полей, кроме input type=checkbox, является то, что возвращает для них функция jQuery.val().

Из значений input type=tel удаляются все символы, кроме цифр. Имеется в виду, что телефонные номера могут вводиться с пробелами, дефисами, скобками и т. п. но все эти символы, как незначащие, не должны отправляться на сервер. Форматирование телефонных номеров, как и дат -- чисто презентационная задача, следовательно, решаться она должна на клиенте.

Что касается checkbox'ов — они обрабатываются по-разному:

  • checkbox без атрибута value считается скалярным полем (переключателем — поле с таким name на форме должно быть только одно), ему соответствует числовое значение 0 либо 1;
  • checkbox с атрибутом value воспринимается как инструмент множественного выбора, ему всегда соответствует массив, состоящий из значений value выбранных (checked) полей. Если ни один checkbox с заданным name не выбран, для него возвращается пустой массив.
И ещё его прототип имеет пару методов зачистки/проверки данных, о которых чуть ниже.

$_REQUEST._secret: передача конфиденциальных данных

Имена полей типа password собираются в массив $_REQUEST._secret. Вызов await response (query) передаёт упомянутые там поля не в JSON-теле POST-запроса, а в дополнительных HTTP-заголовках X-Request-Param-..., что позволяет скрыть их от автоматического логирования.

actual (): игнорирование скрытых полей

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

Например: переключатель "физическое/юридическое лицо" открывает раздел с соответствующими реквизитами (методом вроде $.slideAsNeeded).

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

 values ().actual ()

Он выдаёт тот же объект, но после удаления значений всех полей, кроме:

  • видимых (jQuery-селектор :visible);
  • имеющих тип hidden;
  • имеющих атрибут data-hidden.
Последний предусмотрен для полей, технически скрытых из вида и замещённых другими элементами, но сохраняющих свои имена, типы и смысл в качестве источников данных (обычная практика доопределения стандартных элементов ввода HTML средствами jQuery).

validated (): проверка значений

Этот метод вызывается ради побочного эффекта: если он находит поле, значение которого не попадает в допустимую область, то фокусирует на нём ввод и показывает сообщение об ошибке (die).

Область допустимых значений определяется атрибутами:

  • required;
  • maxlength;
  • minlength;
  • min;
  • max;
  • pattern:
    • заданным явно;
    • автоматически применяемым для type=email (ошибка определяется по наличию CSS-псевдокласса :invalid).
Все атрибуты, кроме required, принимаются в расчёт только для непустых значений. Например, пустая строка подходит и для minlength=3, и для pattern=^\d\d\d$, а строка "00" -- не подходит. Пустое значение отсеивается только атрибутом required.

В действительности все проверки производятся ещё при создании результата values. Вызов validated () лишь проверяет приготовленный список. И список этот может быть отфильтрован предшествующим вызовом actual (). Что позволяет реализовывать условно обязательные поля: например, СНИЛС обязателен для физического лица (когда он только и виден), а ОГРН -- для юридического.

Поэтому набор данных с формы рекомендуется получать следующим образом: 

 values ().actual ().validated ()

Сообщения валидации формируются функциями, перечисленными в объекте $_DO.outspeak. Например: 

  $_DO.outspeak.max: (e) => {	
    if (e.title) return `${e.title} не может быть более ${e.max}`	
    return "Это значение не может быть более " + e.max
  },

При этом e.title определяется изначально по label for=... для проблемного поля; если такого не находится, то по атрибуту title самого элемента ввода. На крайний случай предусмотрены анонимные формулировки про "это значение": в любом случае фокус ввода будет установлен на него.

Всего в $_DO.outspeak присутствуют (и доступны для переопределения в приложении) следующие элементы:

  • fixlength (нарушение фиксированной длины: когда minlength=maxlength, а введённая строка короче)
  • max (выход за максимум для чисел)
  • max_date (выход за максимум для дат)
  • maxlength (этого не может быть, если только не сломается браузер. Но мало ли...)
  • min (недопустимо малое число)
  • min_date (недопустимо ранняя дата)
  • minlength (слишком короткая строка)
  • pattern (несоответствие регулярному выражению)
  • required (пустое значение у обязательного поля)

Clone this wiki locally