Протокол описания нативных фоpм (FML)

Данный раздел поможет вам сформировать и настроить формы в Sender.

FML = Form Markup Language- это язык разметки, который позволяет в продвинутом режиме конструктора форм, в административной панели Sender, создать собственную форму в json-формате. Используя последовательно каждый тег, вам удастся расширить возможность форм и добавить необходимые элементы.

Ниже изложены элементы разметки, которые помогут вам с реализацией ваших идей.

Основные правила

  1. Все элементы разметки имеют обязательный параметр "type". Константа в значении этого параметра определяет способ отображения элемента. Список возможных элементов - ниже. Элемент без type или с неизвестным type игнорируются, также игнорируются все вложенные элементы.

  2. Элементы с типом "row" и "col" являются контейнерами т.е. содержат другие элементы в массиве "items". Вложенные элементы отображаются внутри контейнера горизонтально или вертикально соответственно.

  3. Некоторые свойства элементов разметки наследуются. Например если контейнер верхнего уровня определяет цвет фона, а нижнего уровня - нет, то в контейнере нижнего уровня по умолчанию будет отображаться тот же цвет фона что и в контейнере верхнего уровня.

  4. Если в описании элемента разметки не задано какое-нибудь свойство (например отступ, положение и т.п.) то принимается по умолчанию то значение, что подразумевается в стандартной разметке для данной платформы.

  5. Числовые значения свойств элементов разметки - относительные величины, для каждой платформы максимально соответствующие пикселю.

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)

Ширина элемента, при чём высота h (если она явно не задана) рассчитывается автоматически чтобы избежать искажения пропорций. Нет значения по умолчанию - когда не задано то используется свойство weight.

Высота элемента, при чём ширина 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>
        }
    ]
}