Протокол описания нативных фоpм (FML)
Данный раздел поможет вам сформировать и настроить формы в Sender.
FML = Form Markup Language- это язык разметки, который позволяет в продвинутом режиме конструктора форм, в административной панели Sender, создать собственную форму в json-формате. Используя последовательно каждый тег, вам удастся расширить возможность форм и добавить необходимые элементы.
Ниже изложены элементы разметки, которые помогут вам с реализацией ваших идей.
Основные правила
Все элементы разметки имеют обязательный параметр "type". Константа в значении этого параметра определяет способ отображения элемента. Список возможных элементов - ниже. Элемент без type или с неизвестным type игнорируются, также игнорируются все вложенные элементы.
Элементы с типом "row" и "col" являются контейнерами т.е. содержат другие элементы в массиве "items". Вложенные элементы отображаются внутри контейнера горизонтально или вертикально соответственно.
Некоторые свойства элементов разметки наследуются. Например если контейнер верхнего уровня определяет цвет фона, а нижнего уровня - нет, то в контейнере нижнего уровня по умолчанию будет отображаться тот же цвет фона что и в контейнере верхнего уровня.
Если в описании элемента разметки не задано какое-нибудь свойство (например отступ, положение и т.п.) то принимается по умолчанию то значение, что подразумевается в стандартной разметке для данной платформы.
Числовые значения свойств элементов разметки - относительные величины, для каждой платформы максимально соответствующие пикселю.
Form elements (type attribute)
row
Контейнер с горизонтальным расположением элементов.
col
Контейнер с вертикальным расположением элементов. Корень дерева элементов всегда col.
text
Нередактируемое текстовое поле.
edit
Редактируемое текстовое поле.
img
Изображение.
video
Видео.
check
Единичный элемент выбора true/false. На текущий момент val может быть и булеаном и строкой.
radio
Элемент выбора одного из группы. При отправке формы значением является выбранный элемент или пустая строка, если ничего не выбрано
select
Элемент выбора одного из выпадающего списка. При отправке формы значением является выбранный элемент.
button
Кнопка. Может быть несколько кнопок на форме.
У этого элемента может быть свойство action - тип объект, может быть не задано.
Если action не задано - при нажатии кнопки клиент-приложение должен послать ключ - name кнопки, а значение - val кнопки. Не нажатые кнопки клиент-приложением не посылается вообще. Если хотите чтобы значением отсылалось не текст кнопки - используйте title для отображения текста и отдельно val для отсылки значения при вводе формы.
Если action задано - поведение описано по свойству action.
loader (not implemented)
Компонент предварительной загрузки ресурсов для сложных форм (игры, насыщенные формы предприятий). Внедряется в предыдущую форму бизнес-процесса. Содержит список url для загрузки в кэш и (опционально) имя класса формы, которую нужно вызвать по окончании загрузки.
timer (not implemented)
Компонент для отображения процесса с заданной продолжительностью. В значении атрибута val указывается время ожидания в секундах. Компонент визуализирует истечение времени от указанного до 0 и выполняет action при достижении 0.
map
Компонент для выбора координат по карте. Отображается в виде кнопки. Надпись на кнопке перед выбором "Выбрать". После выбора надпись устанавливается значением title, полученным с сервера. Выбранное значение в формате lat,lon помещается в поле val элемента. По клику по кнопке отображается карта в полноэкранном режиме. Если переданы элементы vars, они отображаются маркерами на карте.
tarea
Компонент для ввода многострочного текста. По умолчанию отображается как многострочное поле ввода, число строк определяется платформой. При вводе большего количества строк появляется скролл.
canvas (not implemented)
Компонент представляющий плоское игровое поле. Отображается как изображение, динамически генерируемое на основании bg и изображений персонажей. Персонажи описываются в массиве vars с vars_type = "GP". Обязательно содержит атрибут "grid", определяющий разбиение поля на условные ячейки. По клику на поле выполняется приведение локальных координат в пикселях к координатам в ячейках сетки, которые и передаются на сервер.
web (not implemented)
WebView внутри нативной формы.
file (not implemented)
Устарело. Используйте action chooseFile
Загрузка файла в форме.
Файл загружается аналогично как при отправке файла с клиента.
В значении val должна быть пустая строка(если файла нет) или ссылка на загруженный файл.
Elements options
Свойства которые наследуются от родителя к детям, явно помечены коричневым цветом.
bgfill
Константа, определяющее поведение фонового изображения. Принимает варианты true (растянуть) и false (центрировать) По умолчанию false.
name
Имя элемента формы. Используется для передачи на сервер данных из формы в ответной форме. Если параметр не задан, то значение элемента на сервер не передается.
bg
Цвет фона (всегда hex вида #a3fc1c) или ссылка на фоновое изображение (всегда вида http...). По умолчанию прозрачный.
grid
Не реализовано/Устарело
Разбиение игрового поля на условные ячейки. Представляет собой строку, составленную из двух целых чисел, разделенных запятой. Например "8,10" означает что игровое поле имеет 8 условных ячеек по горизонтали и 10 по вертикали.
relative
Не реализовано/Устарело
Имя элемента от которого зависит данный элемент. При наличии данного параметра элемент активируется только после ввода данных в элемент указанный в relative. (Если тип элемента completeselect - в запросе новых вариантов выбора отправляется значение relative-элемента вместе с значением текущего элемента).
val
Значение элемента (текст в строке или поле ввода, true/false в check или значение "v" выбранного элемента в radio или select). По умолчанию равно "".
title
Надпись на элементе. Если не задано, выводится значение val. Пока можно использовать только для type="button","check" По умолчанию не задано.
hint
Подсказка в поле ввода. По умолчанию равно "".
Также может быть использовано для картинок в качестве pop-up подсказки.
size
Размер шрифта текста в элементе, содержащем текст (text, edit, ...). По умолчанию равно 12.
Наследуется.
color
Цвет текста в элементе, содержащем текст (text, edit, ...). По умолчанию равно "#000000".
Наследуется.
tstyle
Стиль текста. Массив констант. Возможные значения bold, italic, underline. По умолчанию [] (т.е. обычный текст).
Наследуется.
talign
Выравнивание текста в элементе по горизонтали. Возможные значения left, center, right. По умолчанию left.
valign
Выравнивание элемента в родителе по вертикали. Возможные значения top, center, bottom. По умолчанию top.
halign
Выравнивание элемента в родителе по горизонтали. Возможные значения left, center, right. По умолчанию left.
it
Тип ввода. Определяет вариант возможных значений и вид soft keyboard в edit. Возможные варианты: text, number, float, phone, cardnumber, datetime, mail, uri, pass_text, pass_num.
Наследуется.
(not implemented) calendar - элемент выбора даты, целое число (или строка в котором целое число), в unixtime в секундах по UTC (брать из него только календарный день).
Должен работать с 1900 по 2100 года.
По умолчанию равно text.
(позже добавить time - для вода часов-минут-секунд, пара к calender)
w (not recommended to use)
Ширина элемента, при чём высота h (если она явно не задана) рассчитывается автоматически чтобы избежать искажения пропорций. Нет значения по умолчанию - когда не задано то используется свойство weight.
h (not recommended to use)
Высота элемента, при чём ширина w (если она явно не задана) рассчитывается автоматически чтобы избежать искажения пропорций. Нет значения по умолчанию - когда не задано то используется свойство weight.
pd
Массив целочисленных значений, каждое из которых определяет отступ содержимого от края элемента соответственно [top right bottom left]. Используется только для col и row
По умолчанию равно [0, 0, 0, 0].
mg
Массив целочисленных значений, каждое из которых определяет величину наружного отступа до родительского контейнера или соседнего объекта в контейнере. [top right bottom left].
По умолчанию равно [0, 0, 0, 0].
weight
Число "условных ячеек", которое занимает элемент в родительском контейнере. Например, в горизонтальном контейнере 2 элемента, первый имеет weight=2, второй weight=1. При отображении первый элемент будет вдвое шире второго и оба они будут растянуты на всю ширину родителя (не считая его pd-ов). По умолчанию равно 1, т.е. все элементы делят пространство поровну, если w/h их не указан. Если w/h указан у одного из элементов, остальные делят оставшееся пространство.
src
Ссылка на ресурс в сети или локальной файловой системе (assets приложения). По умолчанию равно "".
loads
Не реализовано/Устарело
Массив строк, представляющих собой url ресурсов, которые помещаются в кэш клиентского приложения при получении данного элемента (применяется в loader)
onload
Не реализовано/Устарело
Имя класса формы, которую нужно вызвать после окончания загрузки всех ресурсов из списка loads
state
Состояние элемента.
Варианты:
"enable" - отрисовать и дать возможность пользователю взаимодействовать с ним.
"disable" - только отрисовать (возможно полупрозрачным).
"invisible" - не рисовать, но выделить место.
"gone" - не рисовать и не выделять место.
Состояние элемента не влияет на передачу его val на сервер. По умолчанию равно "enable".
Наследуется по безусловному признаку.
vars
Массив объектов, описывающий варианты выбора для radio и select. При отправке формы на сервер, указывается значение поля "v" выбранного элемента из массива. Для отображения используется поле "t". Выбранным ставим тот элемент, "v" которого совпадает с атрибутом "val". Опционально может также содержать параметр "img" - значением его является url картинки, которая будет отрисована. По умолчанию равно [].
vars_type
Тип элементов в массиве vars. Принимает одно из значений: STR, MPOINT, GP (строка, точка на карте, игровой персонаж). По умолчанию - STR. Для всех случаев json имеет вид соответственно:
{
"t": "<строка в списке>",
"v": "<значение>"
}
{
"t": "<надпись на маркере>",
"lt": "<широта>",
"lg": "<долгота>",
"v": "<значение>"
}
{
"i": "<ссылка на изображение>",
"x": "<номер ячейки по горизонтали слева>",
"y": "<номер ячейки по вертикали сверху>"
}
По умолчанию равно STR.
wrap
Не реализовано/Устарело
Поведение содержимого элемента в случае если содержимое требует больше места, чем предоставляет элемент. Принимает значения cut, ext, trans (обрезать, выйти за границу, перенести на след. строку). По умолчанию для всех "cut", только для type="text" по умолчанию "trans".
maxlen
Максимально допустимое число символов в поле ввода. По умолчанию не задан.
b_size
Толщина обводки вокруг элемента. Int, пиксели.
b_color
Цвет обводки вокруг элемента. Hex.
b_radius
Радиус скруглений обводки вокруг элемента. Int, пиксели.
multiplatform images
Изображения на сервере могут быть представлены наборами копий для различных разрешений экрана. Если в названии изображения (src) присутствует подстрока _scaled, то для получения изображения с нужным разрешением в имя файла следует добавить суффикс (подстроку перед расширением) из набора:
_x1 - минимальное разрешение (ldpi Android), IOS _x2 - увеличенное в 2 раза (mdpi Android), web _x3 - увеличенное в 3 раза (hdpi Android) _x4 - увеличенное в 4 раза (xhdpi Android), планшеты
Meta
{{!meta.<Object>.<Parameter>}}
Object: 1) "me" - данные о себе. 2) "!user" - данные о компании (брать данные по companyId). 3) все остальное - userId.
Parameter: 1) "photo" - урл на фото профиля пользователя. 2) "name" - имя пользователя. 3) "desc" - описание(статус) пользователя. 4) "phone" - телефон с плюсом, или пустая строка если нет.
Урл собственной аватарки или пользователя из списка контактов Например:
Свое имя {{!meta.me.name}}
Номер телефона юзера или компании {{!meta.!user.phone}}
Actions
Динамически создаваемые элементы интерфейса приложения (в т.ч. элементы fml-форм) при их актвации пользователем могут инициировать действия, описанные c помощью actions-атрибута:
Значением атрибута actions является массив объектов, которые описывают действия, выполняемые в порядке следования в массиве.
Каждый объект одержит обязательное поле: oper - определяющее выполняемую операцию.
oper submit
Выполнить отправку формы на сервер, аналогично нажатию на кнопку. Вместе с данными формы отправляются поля объекта data, если он есть.
Пример:
{
"actions":
[
{
"oper":"submit",
"data":
{
"name":"value"
}
}
]
}
oper extCall
Выполнить вызов внешнего сервера с параметрами (опционально), введенными в форме. При ответе сервера форма с содержимым ответа отправляется обычным способом
Пример:
{
"actions":
[
{
"oper":"extCall",
"url":"<url to external get request>",
"form_data": true
}
]
}
form_data - признак, следует ли отправлять в запросе поля формы. Поля отправляются как get-параметры в формате <имя поля>=<значение>&...
oper goTo
Отправить пользователя в указанный интерфейс приложения. Обязательным атрибутом является "to", который принимает значения:
contacts|dialogs|profile|settings
В случае, если action описан в fml-форме, она должна быть отправлена на сервер перед переходом
Пример:
{
"actions":
[
{
"oper":"goTo",
"to":"<to>"
}
]
}
Возможные значения to
- contacts: список контактов
- dialogs: список диалогов
- profile: страницу профиля пользователя
- settings: страница настроек
- contact: страница текущего контакта (только в p2p чате)
oper addUser
Добавить пользователя в текущий чат: открыть диалог выбора пользователя и по результату добавить выбранного (выбранных)
Если текущий чат p2p - будет создан новый, групповой чат
Пример:
{
"actions":
[
{
"oper":"addUser"
}
]
}
oper sendMsg
Открыть окно ввода текста и введенный текст отправить сообщением в текущий чат
Пример:
{
"actions":
[
{
"oper":"sendMsg"
}
]
}
oper sendMedia
Открыть окно выбора медиа-контента (специфическое для типа контента и платформы) и выбранный контент отправить в текущий чат.
Обязательное поле type определяет тип контента. Варианты: sticker, file, photo, video, location
Пример:
{
"actions":
[
{
"oper":"sendMedia",
"type":"<type>"
}
]
}
oper scanCard: scan card by reader
При активации элемента с этим oper, показываем диалог сканирования, обращаемся к ридеру, при успешном сканировании строку к номером карты помещаем в поле "card" json-структуры, которую отправляем на серврер как model формы. Остальные ранее введенные данные этой формы также отправляются в этой структуре аналогично обычному submit формы.
Пример:
{
"actions":
[
{
"oper":"scanCard"
}
]
}
oper callPhone
В поле "phone" передается телефон в международном формате, без плюса, поле обязательно. Открываем стандартный диалог телефонного вызова с этим номером
Пример:
{
"actions":
[
{
"oper":"callPhone",
"phone":"380501234567"
}
]
}
oper callRobot
Вызывается робот в текущем чате (чате в котором форма находится).
В поле "class" передается класс робота который вызывается, поле обязательно.
Если вызывается из формы, при нажатии в model посылаются все те же элементы что и при нажатии на обычную кнопку этой формы.
Пример:
{
"actions":
[
{
"oper":"callRobot",
"class":"<robotClass>",
"data":
{
"name":"value"
}
}
]
}
Данные из объекта "data" передаются в model вместе с данными формы. Если имена полей совпадают с именами полей в форме данные из "data" считаются более приоритетными
oper callRobotInP2PChat
В поле "userId" передается UserId пользователя или компании в p2p чат с которым нужно перейти, поле обязательно.
В поле "class" передается класс робота который вызывается, поле обязательно.
При нажатии в model посылаются все те же элементы что и при нажатии на обычную кнопку.
Пример:
{
"actions":
[
{
"oper": "callRobotInP2PChat",
"userId": "<userId>",
"class": "<robotClass>",
"data":
{
"name":"value"
}
}
]
}
oper startP2PChat
В поле "userId" передается UserId пользователя или компании в p2p чат с которым нужно перейти, поле обязательно.
Пример:
{
"actions":
[
{
"oper": "startP2PChat",
"userId": "<userId>"
}
]
}
oper selectUser
При выборе элемента в поле action которого указан этот oper нужно открыть нативный диалог выбора пользователей из списка контактов.
В диалоге отображаются только зарегистрированные пользователи при "reg":true иначе - все пользователи.
При выборе конкретного пользователя его номер телефона помещается в поле формы, имя которого задано в атрибуте "to".
Если "autosubmit":true форма отправляется на сервер сразу после того, как клиент сделал выбор в списке контактов, иначе - после выбора форма доступна для работы и отправки на сервер обычным способом (кнопкой в форме)
Например:
{
"actions":
[
{
"oper": "selectUser",
"reg": true,
"to": "<field name>",
"autosubmit":true
}
]
}
oper switchView
При выборе элемента в поле action которого указан этот oper нужно скрыть элементы, name которых указаны в массиве "hide", и показать элементы, name которых указаны в массиве "show". Т.е. первой группе должен быть назначен "state":"gone" а второй - "state":"visible" выполнена перерисовка формы
{
"actions":
[
{
"oper": "switchView",
"hide":
[
elem1, elem2
],
"show":
[
elem3, elem4
]
}
]
}
oper coords
При выборе элемента в поле action которого указан этот oper нужно открыть окно с картой (google maps), при выборе точки на карте значение поля val должно быть равно занчению широты и долготы с разделителем ";" а поле title должно быть равно адресу выбранной точки.
{
"actions":
[
{
"oper": "coords"
}
]
}
oper qrScan
При выборе элемента в поле action которого указан этот oper нужно вызвать окно сканирования qr-кода и отсканированный результат отправить роботу, указанному в поле "class". model отправляемой формы должна содержать результат распознавания кода в поле "qr". Форму результата отправляем в чат указанный в поле "chatId".
Например:
{
"actions":
[
{
"oper": "qrScan",
"class":"<robotClass>",
"chatId":"<chatId>"
}
]
}
В результате отправляем форму:
{
"sid": "<sid>",
"chatId": "<chatId>",
"model": {
"qr":"<value>"
},
"class": "<robotClass>"
}
- chatId - равен чату с sender если с настроек, если из формы или кастом-бара то равен айди чата (это для гипотетического разной работы с qr в разных компаниях).
oper fullVersion
Переключить версию приложения на полную/урезанную
Пример:
{
"actions":
[
{
"oper":"fullVersion",
"full": true,
"submit": false,
"chatId": "<chatId>"
}
]
}
full: true - включить полную версию; false - урезанную
submit: true - отправлять по форме действие по нажатию кнопки; false - не отправлять
chatId - при переходе в полную версию перейти в этот чат и запросить историю
oper getBtc
При выборе элемента в поле action которого указан этот oper нужно вызвать метод получения адреса биткоин кошелька, а результат поместиться в поля формы, имя которой задано атрибутом "to" и форма сабмитится.
Например:
{
"actions":
[
{
"oper": "getBtc",
"to": "<field name>"
}
]
}
oper sendBtc
При выборе элемента в поле action которого указан этот oper нужно вызвать метод отправки биткоинов, адрес и сумма должены заранее поместиться в поля формы, имена которых заданы соответствующими атрибутами "addr" и "summ", с помощью oper scanQrTo\selectuser или ручного ввода.
Результат операции укладывается в поле модели "result" (для отображения результата роботом), и форма сабмитится.
Например:
{
"actions":
[
{
"oper": "sendBtc",
"addr": "<addr field name>",
"summ": "<summ field name>"
}
]
}
oper signFile
При выборе элемента в поле action которого указан этот oper нужно вызвать метод подписи файла, путь к которому должен заранее поместиться в поле формы, имя которого задано в атрибуте "from", с помощью oper scanQrTo.
Результат подписи укладывается в поле модели "result" (для отображения результата роботом), и форма сабмитится.
Например:
{
"actions":
[
{
"oper": "signFile",
"from": "<field name>"
}
]
}
oper notarizeFile
При выборе элемента в поле action которого указан этот oper нужно вызвать метод нотаризации файла, путь к которому должен заранее поместиться в поле формы, имя которого задано в атрибуте "from", с помощью oper chooseFile.
Результат подписи укладывается в поле модели "result" (для отображения результата роботом), и форма сабмитится.
Например:
{
"actions":
[
{
"oper": "notarizeFile",
"from": "<field name>"
}
]
}
oper scanQrTo
При выборе элемента в поле action которого указан этот oper нужно открыть сканер QR.
При скане кода его результат помещается в поле формы, имя которого задано в атрибуте "to".
Например:
{
"actions":
[
{
"oper": "scanQrTo",
"to": "<field name>"
}
]
}
oper chooseFile
При выборе элемента в поле action которого указан этот oper нужно открыть нативный диалог выбора файлов.
Параметр to - содержит name элемента, в который запишется ссылка на загруженный файл
Параметр view (не обязательный) - содержит name элемента (только с type='img'), в который запишется ссылка на загруженный файл для визуального отображения.
Например:
{
"actions":
[
{
"oper": "chooseFile",
"to": "<data field name>",
"view" : <visual field name>
}
]
}