Шаблоны входных форм
СОДЕРЖАНИЕ
- Описание
- Автовключаемый шаблон
- Создание шаблона
- Редактирование шаблона
- Удаление шаблона
- Создание копии существующего шаблона
- Внутренние команды
- Соглашение о названиях
Сам по себе шаблон входной формы, равно как и шаблон выходного документа представляет собой текстовый документ. На этом различия заканчиваются. Шаблон является JSON-структурой данных, состоящей из определенных ключей и их значений, а также порядковых списков (массивов).
Для тех, кто слабо знаком с программированием, приведём небольшой экскурс в типизацию переменных. В JSON поддерживаются следующие типы данных:
- Скаляр, строка - простая переменная, содержащая набор любых символов. Необходимо заключать в кавычки, двойные или одинарные. Пример: "какие-то слова".
- Число - простая переменная содержащая только цифры. Не нужно заключать в кавычки. Примеры: 10, 0, 1.
- Массив, список - последовательный набор любых других переменных, разделяемых знаком запятой: ,. Сам массив заключается в квадратные скобки: []. Каждая переменная в составе массива в свою очередь может быть простого или сложного типа, строкой, числом, другим массивом или хэшем. Порядок переменных в массиве имеет значение - обычно в таком же порядке переменные и обрабатываются. Примеры: ["hello",10,"world"], ["someone","foo",0,["a","b",1]].
- Хэш - несортированный набор пар переменных, в которой первая переменная является простой и называется ключом, вторая может быть простой или сложной и называется значением. Переменные внутри пар разделяются знаком двоеточия: :. Пары между собой, как и в массиве, разделяются точкой с запятой: ,. Обращение к переменной-значению производится по ключу - то есть, чтобы получить значение, необходимо знать содержимое переменной-ключа. Порядок пар в хэше не имеет значения - обращение к значениям производится с указанием ключа. Примеры: {"parameter1":"value1", "parameter2": {"subparam1": "subvalue1"}, "parameter3": ["one","two"] }.
Между любыми символами, за исключением символов внутри значений (внутри кавычек) допустимо любое количество знаков пробела, табуляции или переносов строки, что заметно улучшает наглядность и восприятие вложенности структуры человеком.
Для шаблонов входных форм существует два неявных подтипа - пользовательский и автовключаемый шаблон. Автовключаемый шаблон существует в единственном экземпляре, имеет первый номер, любое название и неудаляем. Также его невозможно выбрать при создании заявки. Однако его можно изменять, как любой другой пользовательский шаблон, если у вас есть право делать это. Смысл существования автовключаемого шаблона состоит в содержании стандартных полей, добавляющихся автоматически в ЛЮБУЮ входную форму при создании или обработки заявки на всех уровнях элементов (параметры заявки, параметры клиентов, параметры услуг и наборы выходных документов). Использование автовключаемого шаблона, с одной стороны, уменьшает объём кода, требуемый ко вводу в КАЖДЫЙ шаблон входной формы, зачастую в разы. Например, если во всех шаблонах входных форм используется одно и то же поле, скажем, имя клиента - имеет смысл вынести его в системный шаблон и тем самым уменьшить объем и повысить читаемость всех остальных шаблонов. Второе применение автовключаемого шаблона - использование в качестве уникальной части настройки под клиента для типовой конфигурации (набора входных форм, устанавливаемого и обновляемого автоматически). Специфичные настройки будут храниться в автовключаемом шаблоне, базовые - в остальных шаблонах. Таким образом снижаются затраты на поддержку и обновление версии типовой конфигурации.
Создание шаблона входной формы подразумевает под собой написание JSON-документа с определенными ключами, перечень и структура которых подробно приведены ниже:
Существуют типы объектов, которые представляют собой верхние уровни иерархии в документе. Это:
- element - Самый базовый и простой тип, состоящий всего из одного поля ввода. Применяется непосредственно к самой заявке, например, цена, скидка или дата начала действия заявки. Не может быть задублирован при вводе (наборе заявки).
- offer - Услуга - набор объектов, могущих быть дублированными в одной и той же заявке - естественно, с разным наполнением. Этот объект имеет вложенные параметры, которые внешне будут выражаться в нескольких полях ввода.
- client - Объект, описывающий туриста(ов), для которого создается заявка. Также может быть задублирован и имеет вложенные параметры, выражающиеся в одном или нескольких полях ввода.
- outdoc - Набор объектов, описывающий выходные документы, могущие быть созданными для заявки, созданной на основе этого шаблона. Включает в себя политику создания конкретного выходного документа в рамках этого шаблона.
- action - Набор объектов, описывающий действия, могущие быть выполненными для заявки, созданной на основе этого шаблона. Включает в себя политику выполнения этого действия.
Ссылки в виде структуры данных
{}
Описание ключей объекта типа element (параметр):
- type - Текстовый ключ, необязателен, допустимы следующие значения: "text", "checkbox", "radio", "hidden". Можно не указывать, значение по умолчанию будет "text". Указывает тип элемента: поле ввода, переключатель (галочка) или радио-кнопки с возможностью выбора только одного значения. Значение "hidden" делает элемент невидимым на форме, в этом случае ключ "label" не играет роли. Также невидимый элемент не будет доступен на форме поиска данных. На данный момент поддерживаются только значения text, hidden, checkbox.
- name - Текстовый ключ, обязателен, значение должно удовлетворять следующим условиям: разрешено употреблять только латинские буквы, цифры и знаки подчеркивания ([a-zA-Z0-9_]), первым символом должна быть буква. Употребляется для формирования имени переменной, присылаемой заполненной формой. Постарайтесь создать уникальное имя переменной. Дело в том, что на сервер передаются все переменные в простом массиве и есть шанс перезаписывания Вашей переменной значением другой переменной с таким же именем. Передача параметров в виде POST-массива не поддерживает пространства имен переменных и поэтому уникальность достигается увеличением длины их имени. Вы можете делать общий префикс в имени переменной, обозначающий её принадлежность к тому или иному типу данных. Например, можно начинать все переменные, относящиеся к услугам на 'offer', к клиентам - на 'client', к самой заявке на 'query'. См. соглашение о названиях для избежания возможных проблем в дальнейшем. Учтите, что переменные услуг и клиентов из-за возможности употребления несколько раз (пять туристов, два перелета) увеличиваются автоматически порядковым номером объекта в конце. Так, элемент с name=c_name сформирует переменную c_name_0.
- label - Текстовый ключ, обязателен для не-скрытых (hidden) элементов, значение не должно содержать двойных кавычек. Содержимое выводится в качестве ассоциируемого человеком названия поля для ввода. См. соглашение о названиях для избежания возможных проблем в дальнейшем.
- title - Текстовый ключ, необязателен, значение не должно содержать двойных кавычек. Содержимое выводится в виде всплывающей подсказки при наведении курсором на поле ввода.
- id - Текстовый ключ, необязателен, значение должно удовлетворять следующим условиям: разрешено употреблять только латинские буквы, цифры и знаки подчеркивания ([a-zA-Z0-9_]). Употребляется при привязках событий или плагинов. При отсутствии формируется из ключа "name".
- value - Текстовый ключ, необязателен, содержит значение по умолчанию в форме ввода. Допустимо любое содержимое, исключая двойные кавычки. Если указан тип (type) равный "radio", в качестве значения по умолчанию допустимо указывать массив данных, например так: ["one","two","tree"]. Обязано быть заданным, если type равно checkbox или radio.
- readonly - Булевый ключ (0/1), необязателен, значение по умолчанию 0. Если значение равно 1, поле блокируется для ручного ввода. Может сочетаться с autocomplete для эмуляции выпадающего списка или в качестве автовычисляемых ячеек в дальнейшем. Не поддерживается, если type=checkbox.
- size - Числовой ключ, необязателен, допустимы только значения от 1 до 255. Графическая длина элемента ввода на форме. Умолчание зависит от браузера, для длинных полей рекомендуется указывать число от 50 и выше.
- maxlength - Числовой ключ, необязателен, допустимы только значения от 1 до 255. Ограничивает количество вводимых символов в поле ввода. Не имеет большого смысла, если указан ключ pcre. Максимальное число 255 продиктовано базой данных, так как все данные хранятся в строке varchar(255).
- class - Текстовый ключ, необязателен, значение должно удовлетворять следующим условиям: разрешено употреблять только латинские буквы, цифры и знаки подчеркивания ([a-zA-Z0-9_]). Содержит имя CSS-класса для стилизации внешнего вида элемента ввода. Также употребляется при привязках плагинов.
- pcre - Текстовый ключ, необязателен, содержит регулярное выражение, perl-совместимое (pcre). Служит для проверки введенного пользователем значения. Настоятельно рекомендуется к употреблению независимо от типа элемента (type). Правильно созданное выражение должно определять начало и конец строки (^, $), а также осуществлять захват значения в 1й буфер ('()') для сохранения именно буфера, а не введенной строки. Не поддерживается, если type=checkbox. Эта проверка производится дважды - и на стороне клиента и на стороне сервера.
- charset - Текстовый ключ, необязателен, содержит набор элементов в стиле регулярного выражения, perl-совместимо (pcre). Служит для исправления введенного пользователем значения на лету, оставляет только те символы, которые перечислены в наборе. Работает только на стороне клиента, рекомендуется употреблять вместе с pcre, так как он работает и на стороне сервера.
- required - Булевый ключ, необязателен, может содержать значения "0" или "1". По умолчанию (если не указывать ключ) - значение "0". Является одним из типов проверки введенного значения и блокирует отправку заявки при значении "1", если пользователь не ввел данные. Это не сработает, если указан ключ "value" (значение по умолчанию). Не поддерживается, если type=checkbox.
- autocomplete - Массив с ключами (hash), необязателен. Включает автоподстановку значений или всплывающий список с возможностью выбора из предлагаемых значений. Механизм autocomplete является мощным и гибким механизмом, облегчающим ввод данных, делает возможным использование значения из справочников при создании заявки, наполнение этих справочников "на лету" и заполнение множества связанных полей одним щелчком. Не поддерживается, если type=checkbox.
Подключи:
- type - Текстовое поле, обязательно, указывает способ автоподстановки. Доступны два значения: "inline" (автонабор при вводе начальных букв найденного значения) и "list" (показ выпадающего списка для выбора одного из подходящих значений). Если указан ключ readonly и равен 1, тип "inline" неприменим, доступен только "list".
- source - Текстовое поле или массив значений (list), обязательно. Массив значений указывает на выбор только из указанных значений. В случае текстового поля ожидается ID или кодовое имя справочника на сервере, откуда будут браться подставляемые значения. В случае, если указано "type":"inline", в качестве источника (это поле) обязан быть ТОЛЬКО массив заранее заданных значений. Это связано с тем, что inline-дополнение менее наглядно и менее удобно при автодополнении из большого списка похожих значений. Таким образом, inline-автодополнение следует использовать для ускорения набора небольшого количества типичных значений по первым буквам, а list-автодополнение при большом списке возможных значений. TODO: JavaScript-функция в качестве source.
Примечание: вместо ID или кодового имени справочника можно указывать следующие значения: "client", "currency" - в этом случае будут подставляться данные из списка клиентов или специально обработанные данные из справочника валют (актуальный курс).
- column - Текстовое поле, необязательно. Актуально в случае указания в ключе source серверного справочника. Содержит номер или название столбца таблицы справочника, откуда будут браться значения для подстановки в переменную. По умолчанию - первый столбец. Является аналогом ключа map в перечисляемых элементах в ключе others. Если использовать этот ключ совместно с ключом addnew, могут возникнуть проблемы при добавлении в справочник записи, если первый столбец справочника не будет заполнен одним из отправляемых значений.
- others - Хэш-массив, необязательно. В ключах содержатся имена (name) ДРУГИХ элементов, значение которых будет учитываться при формировании вариантов автоподстановки или заполняться автоматически при выборе какого-либо варианта текущего поля. В значениях указывается хэш-массив политики заполнения или учета значения поля в разных ситуациях. Например, автодополнение в поле "Название города" должно учитывать значение поля "Страна", чтобы выдать только тот список городов, которые находятся внутри уже указанной страны. Если значение связанного элемента ("Страна") будет пустым, оно не будет рассматриваться в качестве ограничивающего фактора и Вы получите полный список всех городов мира. Причем, если выбрать какой-либо город из этого полного списка, автоматически вместе с заполнением поля города заполнится поле страны. Примечание: выборка возвращает значения полей всех столбцов связанных справочников, сколько бы их не было привязано друг к другу.
Например: к полю с name=hotelname подключен для автозаполнения справочник отелей "hotels", который связан со справочником городов/курортов, которой в свою очередь, связан со справочником стран. Если выбрать отель, то из массива всех присланных значений отелей выберется строка с названием отеля и попытаются заполниться другие поля, имеющие совпадающие с именами столбцов справочников, если не указан явный запрет. Таким образом, если рядом с элементом name=hotelname существуют элементы name=town и name=country, то будут заполнены и они, если в привязанных справочниках есть такие столбцы со значениями.
Ключи значений столбцов, определяющие политику учета значения другого (связанного) элемента и его автозаполнения:
- search - Булевый ключ, необязателен, означает использование значения этого элемента при фильтрации для построения списка. Значение по умолчанию: 1 (включено). Имеет смысл указывать только со значением 0 (отключено). То есть, если Вы собираетесь, например, автозаполнять поле страны, но не хотите, чтобы оно участвовало в фильтре при выборе списка отелей, имеет смысл указать это поле.
- fill - Булевый ключ, необязателен, означает возможность или невозможность автоматического заполнения указанного элемента при выборе значения из списка для основного элемента. Значение по умолчанию: 1 (включено). Имеет смысл указывать только со значением 0 (отключено). Например, поле отсылается при записи строки в справочник на лету, но не должно заполняться автоматически при выборе из списка значения основного элемента.
- save - Булевый ключ, необязателен, означает использование значения указанного элемента при внесении в справочник нового значения основного элемента. Значение по умолчанию: 1 (включено). Имеет смысл указывать только со значением 0 (отключено). Например, поле не отсылается при записи строки в справочник на лету, но должно участвовать в фильтрации.
- show - Числовой ключ, необязателен, означает показ значения поля в списке для выбора наряду со значением основного поля. Значение по умолчанию: 0 (не показывать). Часто востребованная вещь, если основное поле не уникально в строках справочника, например, разные номера одного и того же отеля. Порядок следования показанных элементов в строке списка задается размером значения - т.е. при show=1 значение будет идти вторым сразу за значением главного поля, при show=2 - третьим и тд. others
- map - Текстовое поле, необязательно, содержит имя столбца справочника, соотнесенного с указанным элементом. Используется при несоответствии названия столбца справочника и имени элемента. Повышает гибкость именования элементов.
- value - Текстовое поле, необязательно, содержит жестко заданное в форме значение, подставляемое при поиске в справочнике. Поддерживается только при поиске и сохранении в справочнике, не поддерживается для соотнесения (map) и заполнения реальных элементов (fill). Например, value=1 для элемента fieldname приведет к тому, что из справочника будут найдены все строки, fieldname в которых равен единице.
Пример:{
"name":"o_name",
"label":"Название отеля",
"autocomplete":{
"source":"hotels",
"type":"list",
"column":"name",
"addnew":1,
"policy":{"new":["warning","text"]},
"others":{
"o_pansion":{
"map":"pansion",
"show":1,
},
"o_town":{
"search":0,
"map":"town"
},
"country":{
}
}
}
}
- button - Булевое поле, необязательно. Значение по умолчанию: 0.Чтобы включить функционал, укажите 1 (без кавычек). Добавляет кнопку принудительного выпадения списка возможных значений. Сочетание этого ключа с ключом самого элемента "readonly" превращает элемент в подобие listbox-а (тег select в HTML), так как у сервера запрашивается список ВСЕХ возможных значений элемента без учета уже вбитых букв (потому что их нельзя вбить, можно только выбрать). При этом фильтром служат значения других элементов, привязанных через others.
- addnew - Булевое поле, необязательно. Значение по умолчанию: 0.Чтобы включить функционал, укажите 1 (без кавычек). Добавляет возможность внесения введенных уникальных данных в справочник сервера, из которого производится запрос на подстановку значений. При вводе уникального значения в поле элемента и возвращении пустого списка совпадений с сервера справа от элемента будет появляться кнопка "+" для добавления введенных данных в справочник сервера. При нажатии на кнопку производится отсылка значения на сервер и внесение его, если такого не существует. В случае существования поля появится диалог с ошибкой. При заполнении поля others на сервер происходит отсылка всех введенных значений. Если значение любого из полей, указанного в ключе others пусто, и поле находится в другом, связанном справочнике, вернется ошибка добавления поля. Если в справочнике есть дополнительные, неуказанные в others поля, они заполнятся пустыми значениями или нулями.
- showall - Булевое поле, необязательно. Значение по умолчанию: 0.Чтобы включить функционал, укажите 1 (без кавычек). Заставляет показать все имеющиеся варианты подстановки. Срабатывает только в случае с локальными вариантами (не из справочника, а перечисленными в виде массива). Альтернативный вариант того, чтобы показывались все варианты подстановок - локальных или из справочника - поле должно быть readonly.
- policy - Сложный ключ, хэш, необязателен. Определяет поведение формы при различных случаях. Формат значений ключей: массив с двумя ячейками, первая из которых содержит настройку политики, вторая - текст сообщения. Доступные ключи:
- new - Политика поведения при указании элемента, которого нет в списке автоподстановок. Работает только для не-локальных список автоподстановки (только для списков из справочника). Допустимые значения: warning (При указании несуществующего значения в списке - выводится сообщение с текстом), reject (При указании несуществующего значения в списке - выводится сообщение с текстом и поле очищается). Пример: "policy":{"new":["reject","Вы указали несуществующего поставщика услуг. Чтобы добавить нового поставщика услуг, нажмите кнопку [+] справа."]}
- autofill - Текстовое поле или массив текстовых полей, необязательно. Указывает имя (name) элемента, значение которого будет использовано для автозаполнения поля текущего элемента. Например, существует другой элемент для ввода каких-либо данных. При создании текущего элемента, если в другом элементе с указанным именем будут указаны какие либо данные, они будут скопированы в текущий элемент. Типичное применение: даты начала и конца действия заявки автоматически вносятся в каждую добавляемую услугу, чтобы уменьшить количество необходимых действий оператора. Если параметр "value" уже задан и содержит что-нибудь, параметр "autofill" будет проигнорирован.
Внимание: не все элементы заявки доступны для донорства данных через этот механизм. Элементы дублируемых блоков могут быть недоступны. Связано это с тем, что блоки одинакового типа имеют одинаковые базовые имена элементов. Например, если в заявку добавлены две услуги "транспорт туда", то нет возможности указать через autofill донором элемент из первой услуги - доступны элементы только из последней услуги этого типа. Чтобы обратиться к элементу услуги, требуется указывать перед именем элемента тип услуги, разделяя два значения точкой, например, вот так: "transfer_to.o_date_from".
Поддерживается только если type=text или type=hidden.
Также, в значении допустим javascript-код: если поле содержит кроме букв, точек и цифр что-то еще, то строка исполняется в eval, результат выполнения используется в качестве значения текущего элемента.
Донор - базовый элемент заявки: "autofill":"q_date_from"
Донор - элемент услуги заявки: "autofill":"flight.o_start_town"
Донор - функция: "autofill":"change_date('q_date_from','+1d');"
В случае указания массива текстовых полей, программа будет исследовать поля по очереди, пытаясь заполнить элемент. Например, первый трансфер возьмет дату выезда из даты начала тура, второй трансфер - из первого, если будет указан массив вида "autofill":["transfer_to.o_date_from",".q_date_from"]
- onClick - Текстовое поле, необязательно. Содержит javascript-код, выполняемый при щелчке мышью на элементе.
- onChange - Текстовое поле, необязательно. Содержит javascript-код, выполняемый при изменении содержимого элемента. Не будет работать, если указан ключ readOnly (например, вкупе с autocomplete)
- onExec - Текстовое поле, необязательно. Содержит javascript-код, выполняемый при щелчке мышью на кнопке со звездочкой, расположенной рядом с элементом ввода. Собственно, само объявление onExec укажет интерпретатору, что нужно создать кнопку.
- execlabel - Текстовое поле, необязательно. Содержит название кнопки предыдущей директивы onExec. По умолчанию: *
- nosave - Булевый ключ, необязателен. Значение по умолчанию 0. При указании ключа и выставлении значения в 1, элемент не сохраняет значение в базе при обработке формы. Используется для вспомогательных контейнеров с информацией, например, при реализации корректного запроса autocomplete. Также поиск по значениям этого элемента не будет доступен при поиске данных.
- access - хэш ключей, необязателен. Используется для переключения скрытия/отображения элемента для разных пользователей в системе. Структура ключ=значение такова: "право":[]. Например: "CreateAnyQuery":[]. Объяснение примера: элемент доступен тому, у кого есть право "CreateAnyQuery". Также, есть специальные права "owner" - владелец заявки, "all" или "any" - любой пользователь. По умолчанию элемент отображается для любого пользователя. Пустой массив в качестве значения ([]) указывается из соображений совместимости с таким же ключом в более верхних структурах (offer, outdoc, action).
- description - TODO
- noindent - TODO
Дополнительные ключи объектов КОРНЕВОГО массива "element" (не "offer" и не "type")
- last - Булевый ключ, необязателен. Значение по умолчанию: 0. Если указать значение 1, элемент будет отображен ниже всех блоков ("client","offer"). Это сделано для удобства ввода - некоторые данные логичнее вносить последними.
Для поля "name" существуют зарезервированные, запрещенные к употреблению слова, которые уже используются самим скриптом передачи данных в служебных целях. Это:clientcounter
offercounter
number
columns
uniques
offers
formid
firmid
id
offerid
clientid
documentid
offerid
Также имя поля не должно оканчиваться на подчеркивание и число. Например, такое поле неправильно: foobar_12.
Тренажер создания элементов
Описание ключей объекта типа offer (услуга):
- type - Текстовый ключ, обязателен. Должен быть уникальным в рамках списка услуг (массива "offer"). Допустимы латинские буквы и цифры ([a-zA-Z0-9]). Содержит записываемое в БД краткое понятное название типа услуги. Например: "hotel" или "transfer".
- label - Текстовый ключ, обязателен. Должен быть уникальным в рамках списка услуг (массива "offer"). Допустимы любые символы, кроме двойных кавычек. Содержит понятное название типа услуги. Например : "Размещение" или "Трансфер" или "Гид".
- description -
- deletable - Числовой ключ, необязателен, по умолчанию: 1. Если 0, отсутствует кнопка удаления созданной услуги из списка.
- onCreate - Текстовый ключ, необязателен. Если задан, содержимое выполняется как javascript-код после создания услуги.
- onDelete - Текстовый ключ, необязателен. Если задан, содержимое выполняется как javascript-код после удаления услуги.
- maxCount - Числовой ключ, необязателен. Если задан, услуга может быть добавлена максимум указанное число раз, затем будет выведено сообщение о превышении лимита таких услуг в заявке. Если число будет равно 0, услугу нельзя добавить.
- element - Перечень элементов ввода в виде массива ([]), необязателен. Описание подключей элементов идентично базовому классу "element".
Примечания:
В ключах элементов onClick, onChange, onExec, autofill, onSave Вы можете указывать фрагмент _%N в идентификаторах элементов. Они заменятся на _0, если это первая услуга, _1, если это вторая услуга и так далее. Это нужно потому, что из-за принципа набора услуг реальные имена и идентификаторы элементов каждой услуги дополняются порядковым номером для распознавания принадлежности.
Следует учесть, что в содержимое ЛЮБОЙ услуги автоматически добавятся поля из стандартного набора, который можно отредактировать в системном шаблоне входных форм. Поэтому добавочные элементы (параметр "element") должны быть указаны только если существует необходимость выбора дополнительных параметров.>
Описание ключей объекта типа client (клиент):
- element - Перечень элементов ввода в виде массива ([]), необязателен. Описание подключей элементов идентично базовому классу "element".
Вы можете указать элементы ввода клиентских данных как в системном шаблоне (тогда они будут стандартными для каждого шаблона входной формы), так и отдельно указывать в каждом шаблоне. Два поля ввода (объекта типа element) обязательны в рамках клиента - это ФИО и дата рождения. Параметр name элемента, в который вводится ФИО клиента должен включать в себя слово name (например: clientname, cname или touristname), а поле с датой рождения должно иметь в параметре name фрагмент 'born'. Это нужно, чтобы обеспечить уникальность добавляемых клиентов и при совпадении использовать уже имеющиеся данные о клиенте.
Дополнительные ключи объектов массива "element" в объекте "client"
- only_first - Булевый ключ, необязателен. Значение по умолчанию: 0. Если указать значение 1, элемент будет отображен только для первого в списке клиента.
- intitle - Булевый ключ, необязателен. Значение по умолчанию: 0. Если указать значение 1, значение элемента будет отображено в заголовке блока клиента. Полезно при идентификации свернутого блока.
Примечания:
В ключах элементов onClick и onChange Вы можете указывать фрагмент _%N в идентификаторах элементов. Они заменятся на _0, если это первый клиент, _1, если это второй клиент и так далее. Это нужно потому, что из-за возможности указывания нескольких клиентов реальные имена и идентификаторы элементов каждого клиента дополняются порядковым номером для распознавания принадлежности.
Существуют зарезервированные слова, которые нельзя в рамках объекта client употреблять в качестве значений параметра name для любого из элементов ввода. Это: id, created, changed, params_array, age.
Описание объекта action (действие):
Действия над заявкой указываются в виде массива ([]). Существуют как стандартные действия, могущие быть выполненными имеющимся функционалом модуля (удаление, редактирование, пометка сбойности), так и нестандартные, для выполнения которых нужно указывать внешние скрипты или SQL-команды. Смысл указания доступных действий во входной форме обусловлен прежде всего гибкостью соотношения текущего статуса заявки с перечнем возможных действий над нею. Скажем, редактирование и удаление одного типа заявки доступно лишь до выписки первого приходно-кассового ордера, в то же время, другой тип заявки может быть удален в любом статусе, третий тип заявок допускает дополнительные статусы, которые будут получены выполнением предопределенных действий - например, получением от туриста устного согласия на дополнительные условия.
Ключи:
- action - Текстовый ключ, обязателен. Допустимы символы из латинницы и цифр. Содержит имя действия (код), выполняемого над заявкой. Пример: delete.
- label - Текстовый ключ, необязателен. Допустимы любые символы, кроме двойных кавычек. Содержит понятное человеку название действия. Пример: Удалить.
- exec - Текстовый ключ или массив текстовых ключей, необязателен. Допустимы любые символы, кроме двойных кавычек. Содержит тип и тело команды, которую нужно выполнить для выполнения действия над заявкой. Примите во внимание, что этой команде недоступны переменные, доступные в рамках создания выходного документа. В случае массива команды выполняются в том порядке, в котором они указаны. В случае возвращения отрицательного результата любой командой, следующие по списку команды не выполняются.
- access - хэш ключей, необязателен. Используется для смены политики доступа к выполнению действия. Структура ключ=значение такова: "право":["status1","status2",..,"statusN"]. Например: "ManageTickets":["new","partpaid"]. Объяснение примера: действие доступно тому, у кого есть право "ManageTickets", при условии, что заявка находится в статусе "new" или "partpaid". Если указать пустой массив ([]), не перечисляя статусов заявки, действие будет доступно при любом статусе заявки. Также, есть специальные права "owner" - владелец заявки, "all" или "any" - любой пользователь. По умолчанию выполнение действия доступно любому пользователю в любом статусе заявки.
- description - TODO
- provide - TODO
Описание объекта outdoc (выходной документ):
Выходные документы указываются во входной форме в виде списка/массива ([]), указывая на шаблоны выходных документов продуцируемой заявки. Кроме указания конкретного шаблона (templateid) возможно указать некоторые другие значения, определяющие политику возможности создания документа при тех или иных условиях (minstatus, maxstatus, offertype, multiple, default, nocreate) и дополнительные ключи, обеспечивающие выходной документ необходимыми переменными (vars, element) и возможностями влиять на заявку (precreate, postcreate, predelete, postdelete). Таким образом, выходной документ из простого HTML-файла с переменными превращается в часть бизнес-логики, сопровождающей заявку уже после ее создания.
Ключи:
- element - Перечень элементов ввода в виде массива ([]), необязателен. Описание подключей элементов идентично базовому классу "element". Если хотя бы один из элементов указан, при создании документа будет выведена промежуточная страница, на которой указанные поля ввода будут предложены к заполнению.
Примечание: в ключе value каждого элемента выходного документа допустимо указывать переменные, которые будут заменены их значениями на момент вывода формы заполнения данных выходного документа. Обращение к переменным допустимо указывать в формате шаблонизатора. Перечень доступных переменных можно увидеть через дамп переменных в выходном документе. Пример указания переменной в элементе: "value":"[tmpl_var params_hash.q_cost]". Применение шаблонизатора позволяет использовать гибкий доступ к сложным структурам данных.
- templateid - Числовой ключ, обязателен. Должен быть уникальным в рамках списка услуг (массива "offer"). Содержит ID шаблона выходного документа.
- precreate - Текстовый ключ ИЛИ массив текстовых ключей, необязателен. Допустимы любые символы, кроме двойных кавычек. Содержит тип и тело команды, которую следует выполнить ПЕРЕД созданием документа в базе. Доступные типы команд: exec и sql. В случае использования массива ([]) команды будут выполняться одна за другой. Если одна из команд вернет undefined (ошибку), выполнение следующих команд прекратится, а также отменится сохранение документа в БД. В случае обнаружения ошибки скрипт должен зарегистрировать эту ошибку, пользуясь конструкцией:
$g->{'err'}->Collect($g,'ТЕКСТ ОШИБКИ',1);
- postcreate - Текстовый ключ ИЛИ массив текстовых ключей, необязателен. Допустимы любые символы, кроме двойных кавычек. Содержит тип и тело команды, которую следует выполнить ПОСЛЕ создания документа в базе. Доступные типы команд: exec и sql. В случае использования массива ([]) команды будут выполняться одна за другой. Если одна из команд вернет undefined (ошибку), выполнение следующих команд прекратится.
- default - Булевый ключ, необязателен, допустимые значения: 1, 0. По умолчанию: 0. Указывает на то, что именно этот документ следует использовать при просмотре заявки, как корневой документ (при переходе по ссылке /Voucher/queries/QID/view, где QID - номер заявки). При этом шаблон выходного документа, указанный в templateid должен быть сконфигурирован не для печати на принтере.
- predelete - Текстовый ключ ИЛИ массив текстовых ключей, необязателен. Допустимы любые символы, кроме двойных кавычек. Содержит тип и тело команды, которую следует выполнить ПЕРЕД удалением документа в базе. Доступные типы команд: exec и sql. В случае использования массива ([]) команды будут выполняться одна за другой. Если одна из команд вернет undefined (ошибку), выполнение следующих команд прекратится, а также отменится удаление документа из БД. В случае обнаружения ошибки скрипт должен зарегистрировать эту ошибку, пользуясь конструкцией:
$g->{'err'}->Collect($g,'ТЕКСТ ОШИБКИ',1);. Надо заметить, что удаление документа не является часто используемым действием и регламентировано отдельным видом права. Следует ограничить круг лиц, имеющих право удалять документы для сохранения контроля над делопроизводством.
- postdelete - Текстовый ключ ИЛИ массив текстовых ключей, необязателен. Допустимы любые символы, кроме двойных кавычек. Содержит тип и тело команды, которую следует выполнить ПОСЛЕ удаления документа из базы. Доступные типы команд: exec и sql. В случае использования массива ([]) команды будут выполняться одна за другой. Если одна из команд вернет undefined (ошибку), выполнение следующих команд прекратится. Надо заметить, что удаление документа не является часто используемым действием и регламентировано отдельным видом права. Следует ограничить круг лиц, имеющих право удалять документы для сохранения контроля над делопроизводством.
- nocreate - Булевый ключ, необязателен, допустимые значения: 1, 0. По умолчанию: 0. Определяет возможность сохранения документа в БД с присвоением ему уникального номера документа. Если ключ указан и равен 0, документ не сохраняется. Если указан ключ default, значение ключа nocreate игнорируется и равно 1, так как документ, отображаемый по умолчанию, как корневой - является просто страничкой для дальнейшей работы с другими документами и заявкой, а не реальным документом.
- vars - Хеш-массив, необязателен. Содержит в себе ключи и команды в значениях ключей, которые преобразуются в переменные перед созданием и отображением документа. Требуется для получения дополнительных сведений, не предоставляемых основным набором значений, доступных для каждого выходного документа. Ссылка на описание переменных в выходных документах. Поддерживаются следующие типы команд: sqlrow, sqlarray, exec, dict.
- access - хэш ключей, необязателен. Используется для смены политики доступа к созданию документа (или, при nocreate:1 - просмотру без создания). Структура ключ=значение такова: "право":["status1","status2",..,"statusN"]. Например: "ManageTickets":["new","partpaid"]. Объяснение примера: документ доступен тому, у кого есть право "ManageTickets", при условии, что заявка находится в статусе "new" или "partpaid". Если указать пустой массив ([]), не перечисляя статусов заявки, документ будет доступен при любом статусе заявки. Также, есть специальные права "owner" - владелец заявки, "all" или "any" - любой пользователь. По умолчанию создание документа доступно любому пользователю в любом статусе заявки.
- access_created - хэш ключей, необязателен. Используется для смены политики доступа к распечатке или промотру уже созданного документа. Структура ключей и значений аналогична ключу created.
- multiple - Булевый ключ, необязателен. Допустимые значения: 1, 0. По умолчанию: 0. Указывает на возможность создания этого документа в пределах одной и той же заявки несколько раз. Типичный пример: приходно-кассовый ордер о частичной оплате стоимости заявки.
- offertype - Текстовый ключ или массив текстовых ключей, необязателен. Содержит в себе название типа услуги, к которой привязывается документ. Если поле задано, документ доступен для создания ТОЛЬКО если в заявке указана одна или более услуг названного типа. В сочетании с ключом multiple получает следующий функционал: при привязке документа к услуге через задание этого ключа и при multiple=0 (по умолчанию) - для всех услуг указанного типа, сколько бы ни было их указано в заявке, возможно создать всего один документ, описывающий ВСЕ услуги этого типа. Если же multiple=1 (явно задан), то на каждую созданную услугу указанного типа возможно распечатать по одному текущему выходному документу. Если указано сразу несколько типов услуг, достаточно наличия в заявке хотя бы одной услуги одного из указанных типов, чтобы проверка вернула истину.
- run - Текстовый ключ, необязателен. Содержит имя скрипта для обработки введенных данных через форму в выходном документе. Ключ предназначен для обработки сложных документов, например, для подготовки и отправки формы на сторонние сайты. Указание ключа несколько видоизменяет цепочку обработки документа (см. ниже). Функционал ключа по сути заменяет примитивный element, так как здесь в виде формы с набором элементов выступает сам выходной документ. После ввода или просмотра/корректировки данных формы происходит запуск указанного скрипта, которому передаются все данные формы в виде хэша $self->'post'}. В отношении остальных переменных скрипту доступны те же данные, что и скрипту в ключе precreate. Скрипт должен обработать данные и вернуть результат в виде HTML для отображения в том же окне формы. Если скрипт сгенерирует ошибку, сохранение документа отменится. Также скрипт должен уметь запоминать состояние, чтобы отобразить корректную страницу при повторном открытии уже созданного документа. При этом (при открытии созданного документа) скрипту доступны те же данные, что и скрипту в ключе postcreate
- description - TODO
- provide - TODO
Примечания: если указан ключ default, указание каких-либо других ключей не имеет большого смысла - они будут игнорироваться и документ будет использоваться только в качестве корневого для оперирования заявкой. Если несколько документов имеют ключ default, использоваться в качестве корневого будет первый в списке, имеющий ключ default, а остальные будут просто всегда доступны, не будут подлежать созданию в БД и обработке входных параметров.
Варианты стадий обработки и вывода выходного документа в зависимости от указанных ключей:
- Ключи: default:1 Пример: корневая форма просмотра заявки
Создание заявки
- > Просмотр выбранного документа как корневого
- Ключи: nocreate:1 Пример: приложение к договору
Создание заявки
- > Просмотр корневого документа
- > Открытие выбранного документа на просмотр или печать
- Ключи: nocreate:0 (создаваемый) Пример: любой простой документ, например, договор.
Создание заявки
- > Просмотр корневого документа
- > Создание выбранного документа
- > Открытие на просмотр или печать
- Ключи: nocreate:0 (создаваемый), element:[{...},{...},...] Пример: приходно-кассовый ордер с внесением суммы
Создание заявки
- > Просмотр корневого документа
- > [element] Показ формы ввода дополнительных данных
- > Создание выбранного документа
- > Открытие на просмотр или печать
- Ключи: nocreate:0 (создаваемый), precreate: "...", postcreate: "..." Пример: приходно-кассовый ордер или договор, меняющие статус заявки
Создание заявки
- > Просмотр корневого документа
- > [precreate] Выполнение кода. Прерывание в случае ошибки
- > Создание выбранного документа
- > [postcreate] Выполнение кода
- > Открытие на просмотр или печать
- Ключи: nocreate:0 (создаваемый), offertype:"..." Пример: билет на автобус
Создание заявки
- > Просмотр корневого документа
- > [offertype] Проверка существования услуги указанного типа
- > Создание выбранного документа
- > Открытие на просмотр или печать
- Ключи: nocreate:0 (создаваемый), run:"..." Пример: автоматическое создание страховки на другом сайте
Создание заявки
- > Просмотр корневого документа
- > [run] Открытие на просмотр и корректировку большой формы
- > [run] Запуск скрипта для обработки данных формы
- > Создание выбранного документа
- > [run] Вывод результата обработки скрипта в этом же окне
- Ключи: nocreate:0 (создаваемый), vars: {...} Пример: приходно-кассовый ордер с выводом суммы прописью
Создание заявки
- > Просмотр корневого документа
- > Создание выбранного документа
- > [vars] Подготовка переменных скриптами, запросами
- > Открытие на просмотр или печать
- Ключи: nocreate:0 (создаваемый), status:N, precreate:"...", postcreate:"...", offertype:"...", run:"...", vars: {...} Максимально сложный цикл
Создание заявки
- > Просмотр корневого документа
- > [offertype, status, maxstatus, minstatus] Проверка существования услуги указанного типа, проверка правильного статуса заявки
- > [vars] Подготовка переменных формы скриптами, запросами
- > [run] Открытие на просмотр и корректировку большой формы
- > [run] Запуск скрипта для обработки данных формы
- > [precreate] Выполнение кода. Прерывание в случае ошибки
- > Создание выбранного документа
- > [postcreate] Выполнение кода
- > [run] Вывод результата обработки скрипта в этом же окне
Система ссылок для обработки документов:
Так как выходные шаблоны используются для отображения промежуточных форм (шаблон выходной формы для отображения заявки), а также документы могут иметь несколько стадий состояния (см. ключи run, nocreate:0), при построении шаблонов необходимо знать "точки входа" в виде правильных URL, чтобы формировать правильные HTML-ссылки и посылать HTML-формы по правильным адресам. Ниже приведены доступные действия над документами и сопутствующие URL:
- Создание документа, могущего быть созданным (nocreate:0): /Voucher/queries/[query.id]/createdoc/[templateid]
- Открытие документа на печать: /Voucher/queries/[query.id]/printdoc/[templateid]?did=[outdoc.id]
- Открытие документа на просмотр: /Voucher/queries/[query.id]/view/[templateid]?did=[outdoc.id]
- Сохранение формы (run:...): /Voucher/queries/[query.id]/run/[templateid]
- Удаление заявки: /Voucher/queries/[query.id]/delete
- Изменение заявки: /Voucher/queries/[query.id]/edit
- Исправление заявки: /Voucher/queries/[query.id]/fix
- Выполнение доступных действий над заявкой: /Voucher/queries/[query.id]/exec/[actionname]
Пример шаблона входной формы
{
"element": [
{
"name": "startdate",
"label": "Начало предоставления услуг",
"title": "Введите дату начала действия заявки в виде 'YYYY-MM-DD', например: 2010-12-31.",
"type": "text",
"id": "date1",
"size": 10,
"maxlength": 10,
"pcre": "^(20\d{2}-\d{2}-\d{2})$",
"class": "date",
"required": 1
},{
"name": "enddate",
"label": "Конец предоставления услуг",
"title": "Введите дату конца действия заявки в виде 'YYYY-MM-DD', например: 2010-12-31.",
"type": "text",
"id": "date2",
"size": 10,
"maxlength": 10,
"pcre": "^(20\d{2}-\d{2}-\d{2})$",
"class": "date",
"required": 1
},{
"name": "price",
"label": "Цена",
"size": 6,
"pcre": "^(\d{3,6})$",
}
],
"offer": [
{
"name": "Трансфер",
"type": "transfer",
},{
"name": "Проживание",
"type": "hotel",
"element": [
{
"name": "hotelquality",
"label": "Класс отеля",
"title": "Введите количество звезд отеля (от 1 до 5).",
"size": 1
"maxlength": 1
"pcre": "^([1-5])$",
"required": 1
},{
"name": "hotelfood",
"label": "Питание",
"title": "Введите код типа питания.",
"size": 5,
"maxlength": 5,
"pcre": "^([A-Z\+]{2,5})$",
"required": 1,
"autocomplete": {
"source": ["OB","BB","HB","HB+","FB","FB+","EXTFB","ALL","AI","UAL","UAI","HCAL"],
"type": "inline"
}
}
]
}
],
"client": {
"element": [
{
"name": "clientname",
"label": "ФИО",
"title": "Введите полную фамилию имя и отчество (если есть) туриста.",
"size": 50,
"maxlength": 255,
"required": 1
},{
"name": "clientborn",
"label": "Дата рождения",
"title": "Введите дату рождения туриста в виде 'YYYY-MM-DD', например: 1980-11-29.",
"type": "text",
"size": 10,
"maxlength": 10,
"pcre": "^(20\d{2}-\d{2}-\d{2})$",
"class": "date",
"required": 1
}
]
},
"outdoc": [
{
"templateid": 5,
"default": 1
},{
"templateid": 3,
"precreate": "exec appendmoney",
"postcreate": "exec appendmoney",
"minstatus": 1,
"maxstatus": 1,
"element": [
{
"name": "money",
"label": "Укажите сумму",
"title": "Укажите сумму, вносимую туристом в единицах валюты",
"size": 6,
"maxlength": 6,
"required": 1,
"pcre": "^([0-9]{3,6})$",
}
],
"vars": {
"var1": "exec somescriptname",
"params": "sqlarray select pid, param from vchr_params;"
}
}
]
}
Внутренние команды допустимы в рамках создания или распечатки выходных документов. Команда является текстовым полем и разделена ПЕРВЫМ в строке пробелом на две части: тип команды и тело команды. Примеры:
'sqlrow select columnname from tablename where id=N;'
'exec changequerystate'
Существующие типы команд и их описание:
- sql - Выполнение sql DML-команды (insert, update, delete). В теле допустима переменная $QID, подменяющаяся во время выполнения на номер заявки.
- sqlrow - Выполнение sql-выборки (select), возвращающая ОДНУ строку (хэш-массив). В теле допустима переменная $QID,
- sqlarray - Выполнение sql-выборки (select), возвращающая МНОГО строк (массив хэш-массивов). В теле допустима переменная $QID, подменяющаяся во время выполнения на номер заявки.
- dict - Получение массива данных из справочника с указанным номером. Первый параметр - номер справочника, следующие - пара ключ=значение (where). Спецключи без значений: distinct.
- string - Возвращает указанную строку (используется для передачи переменных-переключателей в выходной документ).
- http - Зарезервировано на будущее.
- dictrow - Получение одной (первой) данных из справочника с указанным номером. Первый параметр - номер справочника, следующие - пара ключ=значение (where).
- exec - Выполнение файла скрипта через eval. Файл должен находиться в каталоге $PREFIX/share/tourservice/Modules/Voucher/docscripts или в подкаталоге scripts в каталоге хоста (например, /var/www/hostname/scripts), иметь расширение .pl и не содержать в своем имени слешей (/). Указывать имя файла нужно без расширения. В скрипте доступны переменные:
- $self->{'inform'} - объект входной формы
- $self->{'query'} - объект текущей заявки
- $self->{'queryid'} - номер текущей заявки
- $self->{'queryparams'} - хэш параметров заявки (большая вложенность) (доступно только на этапе просмотра выходного документа - в хэше-ключе "vars" )
- $self->{'template'} - объект шаблона текущего выходного документа
- $self->{'policy'} - хэш-массив настроек текущего выходного документа в контексте входной формы (объект outdoc)
- $self->{'templateid'} - номер шаблона текущего выходного документа
Кроме того, скрипту (exec) можно передавать аргументы командной строки для более гибкой реакции. Как и в аналогии с командной строкой, параметры нужно указывать после имени скрипта через пробел, разделяя между собой пробелами. В скрипте все параметры доступны через массив @params.
Пример: "exec switchquerybymoney querycost document_money 2"
При использовании внутренних команд для выходных документов заявки в теле SQL-запросов(sqlrow, sqlarray, sql) доступны следующие переменные:
- $QID - подменяется во время выполнения на номер заявки.
- $TID - подменяется во время выполнения на номер шаблона обрабатываемого документа.
- $DID - подменяется во время выполнения на номер обрабатываемого документа. Эта переменная доступна только для действия, указанного в ключах vars и postcreate и только для документов, могущих быть созданными (без ключа nocreate), так как в иных случаях ID документа отсутствует.
При использовании внутренних команд для отчетов доступны следующие переменные:
- $request->{parameter} - где parameter - посланный GET-ом или POST-ом параметр. Вся конструкция подменится на значение этого параметра. Если значение пусто или параметр не был послан, команда отменяется (выполнение не состоится). Таким образом удобно писать множество запросов, срабатывать из которых будут лишь те, которым достаточно переменных для выполнения.
В контексте входной формы Вы создаете множество мелких элементов, каждый из которых должен обладать уникальным именем (name) и понятным названием (label). Содержимое этих ключей не играет особой роли, если Вы создали и пользуетесь всего одной входной формой. Однако, как только у Вас появляется несколько форм, а также выходные документы со своими элементами, то, чтобы избежать проблем и путаниц, Вы должны будете соблюдать какие-либо условия.
Примите во внимание следующие размышления:
- Одинаковые по смыслу элементы в разных услугах и даже в разных входных формах лучше всего называть одинаково (и name и label) - это минимизирует количество полей формы поиска и изрядно облегчит массовые операции на любом этапе по типовым элементам, например, суммирование цен услуг. Также это позволит минимизировать код шаблонов выходных документов и вообще использовать для разных входных форм одни и те же шаблоны выходных документов. Это достаточно весомый аргумент, чтобы унифицировать имена (name) и названия (label) элементов.
- Имя элемента (name) должно однозначно определять, к какому типу объекта относится элемент - Вам это поможет на этапе написания шаблонов выходных форм и на этапе построения отчетов. Для этого можно использовать префиксы вида q_, d_, o_, c_ или подобные. Не начинайте имена элементов со знака подчеркивания - часто с него начинаются внутренние переменные в коде, да и шаблонизатор может повести себя неправильно при их обработке.
- Название (label) элементов выходного документа должно косвенно указывать на причастность их именно к выходному документу, а не к входной форме. Дело в том, что на форме поиска выводятся названия элементов всех под-объектов входной формы, включая и названия элементов выходных документов. Необходимо легко определить, к какой именно части относится тот или иной элемент по его названию. Скажем, похожий по смыслу элемент "q_cost" во входной форме можно назвать "Стоимость тура", однако его аналог "d_cost" в выходном документе (приходно-кассовый ордер) должен выглядеть примерно как "Вносимая сумма", в расходно-кассовом ордере "d_money" - "Возвращаемая сумма". Избегайте излишне кратких названий, понятных только в контексте конкретной услуги или формы - например:
Неправильно: "Длительность", "Стоимость", "Дата начала", "Название",
Правильно: "Длительность тура", "Стоимость путевки", "Начало услуги", "Название отеля"
TODO:+class, value="..tmpl_var ...", noindent:1 (autocomplete.others ... indent with arrow), intitle:1, autocomplete{"fill":{}},autocomplete{"showfilter":"functionname"} autofill:"function(){...}", "onCreate","onDelete" (offer, client, выполняется последним - может быть полезно). Внимание: нельзя одновременно указывать ключи access и required в элементе. settings:{statuses:[], collapseObjects:1, collapseBlocks:1, autoCollapseObjects:1, autoCollapseBlocks:0, addBlockView:list, onLoad:"jscode", addFirstBlock:['blocktype1','blocktype2'] },action:[{exec:["javascript somecode"]}],
offer:deletable,client:deletable,
onSave:execute_code_at_save_query_for_every_element_and_check_output_for_positive_(extra_checks)_replace_pcre_and_required
outdoc:depend:[templatename,templateid] or string - доступен, если создан хотя бы один из перечисленных типов документов
inform:action,outdoc:[{"extra_check":"exec helper IsPacketQuery $QID"}]
<< Оглавление | Наверх…