Ajax API (описание точек входа)
СОДЕРЖАНИЕ
- Вступление
- Пакеты
- Заявки
- Справочники
- Входные формы (включая документы)
Ответы на Ajax-запросы отличаются от обычных HTML-страниц тем, что возвращают структуры данных в JSON-формате (хотя можно передавать и обычный HTML и XML-формат). В «Турпутевке» практикуется только JSON-формат ответов, как наиболее читабельный и экономный по объему. JSON-строка является сериализованным JavaScript-объектом.
Спецификация:
Для того, чтобы получить именно Ajax-ответ, необходимо в GET или POST-запросе указать параметр is_ajax=1. Кроме этого, URL запроса должен совпадать с известной платформе точкой входа для Ajax-запросов, а также содержать необходимые для этой точки входа параметры. Описание точек входа с параметрами в разбивке по сущностям дано ниже.
Если использовать функционал скриптов, идущих в комплекте с платформой «Турпутевка», код запроса в теле Javascript будет выглядеть так (пример):
Ajax.doGet('/Voucher/entrypoint',[['param1','value1'],['param2','value2'],['array_param3',['value3_1','value3_2',...,'value3_N']]],CallbackFunctionName);
function CallbackFunctionName(j){
var r = json_parse(j);
if(!r) return false;
for ( var i=0; i<r.variants.length; i++ ) {
... some code ...
}
}
Здесь указывать параметр is_ajax в запросе не нужно, он добавляется автоматически функцией Ajax.doGet. Если нет параметров запроса, кроме URL и функции обработки ответа, укажите вместо параметров пустой массив (Ajax.doPost(URL,[],CallBack)).
Если сервер вернул ошибку, то текст ответа будет являться просто строкой, а не JSON-объектом. Строка ошибки всегда начинается с символов "ERR: ". При получении ошибки функция, указанная в качестве callback-параметра, не будет вызвана, вместо этого будет показан alert с текстом ошибки. В будущем необходимо позволить все же вызвать функцию, хотя бы без параметров, чтобы javascript-код смог выполнить какие-либо блокирующие действия в случае получения ошибки, например, указанием дополнительного ключа, принуждающего это сделать.
Для передачи POST-запросов серверу существуют функции Ajax.doPost и Ajax.doDataPost. Различаются они тем, что Ajax.doDataPost принудительно кодирует значения переменных в Base64 (это стандартный подход браузера при отправке форм типа enctype="multipart/form-data". Используйте эту функцию, если в значениях переменных могут попадаться знаки плюса (+) - разбирающий скрипт на сервере при получении GET или обычного POST-запроса заменяет плюсы пробелами (особенности кодирования URL).
Кроме обычных параметров, являющихся чаще всего фильтрами для поиска строк с заранее известными значениями (аналог SQL-запроса where param='value'), существуют специальные параметры, влияющие на результат другими методами, а также модификаторы. Ниже дано перечисление таких параметров и описание их возможных значений:
- param - ключ, исторически появившийся при обработке запросов автодополнения (autocomplete) во входных формах. Значение содержит название поля в базе, в котором следует искать значение параметра w. Само по себе указание параметра param приводит к тому, что в строках ответа возвращаемое значение поля, указанного в param, дублируется с именем id. Это позволяет ловить возвращаемые значения в функции-обработчике, не зная, как называется поле (упрощает обработку результата). Например, если указать ['param','fieldname'], то в каждой строке возвращенного результата, помимо прочих полей, будут два значения: ...,"fieldname":"valueX","id":"valueX",....
- w - ключ, содержащий частичное значение главного поля, по которому производится поиск результата в справочнике. Чаще всего никак не обрабатывается в виртуальных справочниках (пакетах, заявках и проч.). Фактически, эквивалентен SQL-запросу where param like 'XXX%', где XXX - значение ключа w. Заметьте, что значение найденных ключей не просто содержит искомое значение, а именно начинается с него - так, при w=мос найдется строка со значением Москва, но не найдется Космос.
- is_unique - .
- sortby - .
- what - .
- output - .
- distinct - .
Точки входа Ajax для работы с пакетами:
-
/Voucher/packets/ID/get/param - поиск параметров в пакетах.
В качестве ID указывается номер пакета. Если ID=0, тогда будут обрабатываться все имеющиеся пакеты. Также их перечень можно ограничить переменной selectid (см ниже).
ВНИМАНИЕ: из результатов поиска исключаются пакеты, которые не готовы к использованию (см. первую вкладку настройки турпакета)
Переменные запроса:
- area - область поиска в пакете. Доступные значения: packet, products, options. Указание позволяет уточнить, где именно искать значение переменной. Обязательный ключ.
- type - тип опции. Перечень зависит от количества разных блоков option в шаблоне пакета. Обязателен, если ключ area=options.
- params - перечень параметров для поиска, может быть массивом (несколько параметров сразу). Перечень имен параметров смотрите в шаблоне пакета (имена элементов).
- selectid - содержит номер шаблона формы поиска пакетов - при этом обработке будут подлежать все пакеты, которые используют этот шаблон в качестве формы поиска пакетов. Необязательный параметр.
Пример возвращаемой структуры:
{
"variants":[
{
"11": {
"pid":"13",
"param1" : "value1",
"param2" : "value2"
}
},
}
"pid":"13",
"param1" : "value1",
"param2" : "value2"
}
],
"packets":{
"13": {
"desc": "Описание пакета",
"name": "Наименование пакета"
}
}
}
-
/Voucher/packets/ID/get/list - поиск перечня пакетов.
Здесь ID в URL расценивается как ID шаблона поиска пакетов (не ID пакета!). Если ID=0, будут найдены все пакеты в системе, иначе будут найдены все пакеты, использующие шаблон с этим ID в качестве формы поиска пакетов.
Переменные запроса: не требуются
Пример возвращаемой структуры:
{
"variants":[
{
"id": "15",
"pstatus": 0,
"name": "Турция",
"description": "Сезон 2012"
"changed": "2012-03-16 22:11:11",
"created": "2012-03-16 21:11:11",
}
]
}
-
/Voucher/packets/ID/get/columns - перечень столбцов какого-либо справочника, включая столбцы всех связанных справочников.
ID здесь не играет значения.
Переменные запроса:
- w - кодовое имя (латинницей) или ID нужного справочника.
Пример возвращаемой структуры:
{
"variants":[
{
"id": "field1",
"description": "Поле номер 1",
},
{
"id": "cost",
"description": "Цена",
},
{
"id": "price",
"description": "",
}
],
"dictid":"room_costs"
}
<< Оглавление | Наверх…