Шаблоны входных форм


СОДЕРЖАНИЕ
  1. Описание
  2. Автовключаемый шаблон
  3. Создание шаблона
  4. Редактирование шаблона
  5. Удаление шаблона
  6. Создание копии существующего шаблона
  7. Внутренние команды
  8. Соглашение о названиях

Описание

Сам по себе шаблон входной формы, равно как и шаблон выходного документа представляет собой текстовый документ. На этом различия заканчиваются. Шаблон является JSON-структурой данных, состоящей из определенных ключей и их значений, а также порядковых списков (массивов).

Для тех, кто слабо знаком с программированием, приведём небольшой экскурс в типизацию переменных. В JSON поддерживаются следующие типы данных:

Между любыми символами, за исключением символов внутри значений (внутри кавычек) допустимо любое количество знаков пробела, табуляции или переносов строки, что заметно улучшает наглядность и восприятие вложенности структуры человеком.

Автовключаемый шаблон

Для шаблонов входных форм существует два неявных подтипа - пользовательский и автовключаемый шаблон. Автовключаемый шаблон существует в единственном экземпляре, имеет первый номер, любое название и неудаляем. Также его невозможно выбрать при создании заявки. Однако его можно изменять, как любой другой пользовательский шаблон, если у вас есть право делать это. Смысл существования автовключаемого шаблона состоит в содержании стандартных полей, добавляющихся автоматически в ЛЮБУЮ входную форму при создании или обработки заявки на всех уровнях элементов (параметры заявки, параметры клиентов, параметры услуг и наборы выходных документов). Использование автовключаемого шаблона, с одной стороны, уменьшает объём кода, требуемый ко вводу в КАЖДЫЙ шаблон входной формы, зачастую в разы. Например, если во всех шаблонах входных форм используется одно и то же поле, скажем, имя клиента - имеет смысл вынести его в системный шаблон и тем самым уменьшить объем и повысить читаемость всех остальных шаблонов. Второе применение автовключаемого шаблона - использование в качестве уникальной части настройки под клиента для типовой конфигурации (набора входных форм, устанавливаемого и обновляемого автоматически). Специфичные настройки будут храниться в автовключаемом шаблоне, базовые - в остальных шаблонах. Таким образом снижаются затраты на поддержку и обновление версии типовой конфигурации.

Создание шаблона

Создание шаблона входной формы подразумевает под собой написание JSON-документа с определенными ключами, перечень и структура которых подробно приведены ниже:

Существуют типы объектов, которые представляют собой верхние уровни иерархии в документе. Это:

Ссылки в виде структуры данных

{}

Описание ключей объекта типа element (параметр):

Дополнительные ключи объектов КОРНЕВОГО массива "element" (не "offer" и не "type")

Для поля "name" существуют зарезервированные, запрещенные к употреблению слова, которые уже используются самим скриптом передачи данных в служебных целях. Это:
clientcounter
offercounter
number
columns
uniques
offers
formid
firmid
id
offerid
clientid
documentid
offerid
Также имя поля не должно оканчиваться на подчеркивание и число. Например, такое поле неправильно: foobar_12.

Тренажер создания элементов

JSON-объект:

Второе поле, id='other_field':

Элемент:
Исходный код

Описание ключей объекта типа offer (услуга):

Примечания:
В ключах элементов onClick, onChange, onExec, autofill, onSave Вы можете указывать фрагмент _%N в идентификаторах элементов. Они заменятся на _0, если это первая услуга, _1, если это вторая услуга и так далее. Это нужно потому, что из-за принципа набора услуг реальные имена и идентификаторы элементов каждой услуги дополняются порядковым номером для распознавания принадлежности.
Следует учесть, что в содержимое ЛЮБОЙ услуги автоматически добавятся поля из стандартного набора, который можно отредактировать в
системном шаблоне входных форм. Поэтому добавочные элементы (параметр "element") должны быть указаны только если существует необходимость выбора дополнительных параметров.

Описание ключей объекта типа client (клиент):

Вы можете указать элементы ввода клиентских данных как в системном шаблоне (тогда они будут стандартными для каждого шаблона входной формы), так и отдельно указывать в каждом шаблоне. Два поля ввода (объекта типа element) обязательны в рамках клиента - это ФИО и дата рождения. Параметр name элемента, в который вводится ФИО клиента должен включать в себя слово name (например: clientname, cname или touristname), а поле с датой рождения должно иметь в параметре name фрагмент 'born'. Это нужно, чтобы обеспечить уникальность добавляемых клиентов и при совпадении использовать уже имеющиеся данные о клиенте.

Дополнительные ключи объектов массива "element" в объекте "client"

Примечания:
В ключах элементов onClick и onChange Вы можете указывать фрагмент _%N в идентификаторах элементов. Они заменятся на _0, если это первый клиент, _1, если это второй клиент и так далее. Это нужно потому, что из-за возможности указывания нескольких клиентов реальные имена и идентификаторы элементов каждого клиента дополняются порядковым номером для распознавания принадлежности.
Существуют зарезервированные слова, которые нельзя в рамках объекта client употреблять в качестве значений параметра name для любого из элементов ввода. Это: id, created, changed, params_array, age.


Описание объекта action (действие):

Действия над заявкой указываются в виде массива ([]). Существуют как стандартные действия, могущие быть выполненными имеющимся функционалом модуля (удаление, редактирование, пометка сбойности), так и нестандартные, для выполнения которых нужно указывать внешние скрипты или SQL-команды. Смысл указания доступных действий во входной форме обусловлен прежде всего гибкостью соотношения текущего статуса заявки с перечнем возможных действий над нею. Скажем, редактирование и удаление одного типа заявки доступно лишь до выписки первого приходно-кассового ордера, в то же время, другой тип заявки может быть удален в любом статусе, третий тип заявок допускает дополнительные статусы, которые будут получены выполнением предопределенных действий - например, получением от туриста устного согласия на дополнительные условия.

Ключи:


Описание объекта outdoc (выходной документ):

Выходные документы указываются во входной форме в виде списка/массива ([]), указывая на шаблоны выходных документов продуцируемой заявки. Кроме указания конкретного шаблона (templateid) возможно указать некоторые другие значения, определяющие политику возможности создания документа при тех или иных условиях (minstatus, maxstatus, offertype, multiple, default, nocreate) и дополнительные ключи, обеспечивающие выходной документ необходимыми переменными (vars, element) и возможностями влиять на заявку (precreate, postcreate, predelete, postdelete). Таким образом, выходной документ из простого HTML-файла с переменными превращается в часть бизнес-логики, сопровождающей заявку уже после ее создания.

Ключи:

Примечания: если указан ключ default, указание каких-либо других ключей не имеет большого смысла - они будут игнорироваться и документ будет использоваться только в качестве корневого для оперирования заявкой. Если несколько документов имеют ключ default, использоваться в качестве корневого будет первый в списке, имеющий ключ default, а остальные будут просто всегда доступны, не будут подлежать созданию в БД и обработке входных параметров.

Варианты стадий обработки и вывода выходного документа в зависимости от указанных ключей:

Система ссылок для обработки документов:
Так как выходные шаблоны используются для отображения промежуточных форм (шаблон выходной формы для отображения заявки), а также документы могут иметь несколько стадий состояния (см. ключи run, nocreate:0), при построении шаблонов необходимо знать "точки входа" в виде правильных URL, чтобы формировать правильные HTML-ссылки и посылать HTML-формы по правильным адресам. Ниже приведены доступные действия над документами и сопутствующие URL:

Пример шаблона входной формы

{
	"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' Существующие типы команд и их описание:

Кроме того, скрипту (exec) можно передавать аргументы командной строки для более гибкой реакции. Как и в аналогии с командной строкой, параметры нужно указывать после имени скрипта через пробел, разделяя между собой пробелами. В скрипте все параметры доступны через массив @params.
Пример: "exec switchquerybymoney querycost document_money 2"

При использовании внутренних команд для выходных документов заявки в теле SQL-запросов(sqlrow, sqlarray, sql) доступны следующие переменные:

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

Соглашение о названиях

В контексте входной формы Вы создаете множество мелких элементов, каждый из которых должен обладать уникальным именем (name) и понятным названием (label). Содержимое этих ключей не играет особой роли, если Вы создали и пользуетесь всего одной входной формой. Однако, как только у Вас появляется несколько форм, а также выходные документы со своими элементами, то, чтобы избежать проблем и путаниц, Вы должны будете соблюдать какие-либо условия.

Примите во внимание следующие размышления:


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"}]
<< Оглавление | Наверх…