Виджеты Примеры Демо Форум Сервисы
Документация
СтартКомпоненты

Form

Справочник по API

Обзор

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



Инициализация

Компонент Form наследуется от view. По своей организации форма похожа на layout т.к. также разделена на столбцы и строки, в которые помещаются контролы.

  • elements - массив вертикально упорядоченных контролов и групп контролов;
  • cols - массив горизонтально упорядоченных контролов и групп контролов;
  • rows - (или elements) массив вертикально упорядоченных контролов и групп контролов.

Существует возможность указать общую конфигурацию для всех контролов, включенных в ту или иную форму.

Форма авторизации 

webix.ui({
    view:"form", 
    id:"log_form",
    width:300,
    elements:[
        { view:"text", label:"Email", name:"email"},
        { view:"text", type:"password", label:"Password", name:"password"},
        { margin:5, cols:[
            { view:"button", value:"Login" , css:"webix_primary"},
            { view:"button", value:"Cancel"}
        ]}
    ]
});

Related sample:  Form: Basic Initialization

Для удобства последующего взаимодействия с контролами (задание/получение значений, валидация), необходимо задать свойство name каждому из этих контролов. Имена всегда должны быть уникальными. Если вам необходимо связать их между собой (или сделать что-то еще), мы рекомендуем отказаться от использования bind() и вручную обработать нужную логику.

Related sample:  Form: Custom Binding Logic

Как задать исходное значение

Задать исходные значения для формы можно несколькими способами:

Задать value каждого элемента отдельно

Каждый контрол содержит свойство value:

{ view:"text", id:"fname", value:"Adam Smith"}

Также вы можете вызвать для этого метод setValue():

$$("fname").setValue("Adam Smith");

Тем не менее этот способ не эффективен при работе со всей формой.

Использовать setValues API

Чтобы задать несколько значений, вы можете использовать метод setValues. Метод принимает объект с набором value в качестве первого (и обязательного) параметра:

$$("$form1").setValues({
    value1:"111", value2:"222"
});

Имена данных этих значений должны совпадать со значениями параметров name соответствующих элементов формы:

elements:[
    { view:"text", name:"value1" },
    { view:"text", name:"value2" }
]

Complex Data

Вы можете задать форме любой уровень сложности, используйте для этого следующие настройки:

  • свойство complexData со значением true;
  • имена элементов должны быть заданы через точку. 
webix.ui({
    view:"form",
    id: "sets",
    complexData:true,
    elements:[
        { label:"Width", view:"text", name:"layout.width" },
        { label:"Height", view:"text", name:"layout.height" }
    ]
});
 
$$("sets").setValues({
    layout:{
        width:250,
        height:480
    }
});

Related sample:  Form: Data with Complex Properties

Загрузка/парсинг значений

Webix Form может загружать и парсить данные как и любой другой компонент управления данными. Для формы работают все общие правила загрузки данных.

Атрибуты данных должны совпадать со значениями параметров name полей формы:

Парсинг 

var data = {id:1, fname:"Ann", lname:"Brown"};
 
webix.ui({
    view:"form", id:"myform", elements:[
        { view:"text", name:"fname"},
        { view:"text", name:"lname"}
    ],
    data:data
});    
// или
$$("myform").parse(data);

Загрузка 

$$("myform").load("data.php");

Группировка контролов

Разделение формы на разделы

Элементы (elements) формы можно разделить на столбцы и строки любого уровня сложности.

{ view:"form", elements:[
    {cols:[
        { rows:[
            { view:"text"},
            { view:"datepicker"}
        ]},
        { view:"checkbox"},
        { view:"button"}
    ]}
]}

Добавить удобства и привлекательности внешнему виду формы можно с помощью:

  • разделения полей формы на группы;
  • добавления хедеров для групп контролов.

Разделы

Элементы формы помещены в разные массивы row, где первая строка - это хедер. Текст для хедера задается как значение свойства template:

{view:"form", elements: [
    { rows:[ 
        { template:"Alpha fields", type:"section"},
        { view:"text", label:"Alpha 1", value:"" },
        { view:"text", label:"Alpha 2", value:"" }
    ]},
    { rows:[ 
        { template:"Beta fields", type:"section"},
        { view:"text", label:"Beta 1", value:"" }
    ]}
]}



Related sample:  Splitting Form into Sections

Наборы полей

Наборы полей, или fieldset - это разделы с границами, врутри которых могут быть помещены контролы. Webix Fieldset содержит текстовый заголовок (label) и тело (body) где хранятся массивы контролов, сгруппированные в rows или cols:

{view:"form", elements:[
    { view:"fieldset", label:"Field Set 1", body:{
         rows:[
            { view:"text", label:"Login"},
            { view:"text", label:"Email"}
         ]
    }}
]}



Related sample:  Fieldset

Форма с Multiview

Поля формы могут быть размещены на разных вкладках, т.о. образуя multiview. Переключение между вкладками реализуется с помощью кнопок tabbar и segmented, а также специального tabview.

Контролы для переключение размещаются в массиве elements.

{view:"form", elements:[
    { view:"tabview",
        tabbar:{ 
            options:["A","B"]
        },
        cells:[
            { id:"A", rows:[
                { view:"text", name:"value1", label:"value1" },{}
            ]},
            { id:"B", rows:[
                { view:"text", name:"value2", label:"value2" }, {}
            ]}
        ]
    }
]}

Related sample:  Form with Tabs

Получение значений формы

Получить value каждого элемента отдельно

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

var form1 = [
    { view:"text", label:"Login", name:"login", id:"log"},
    { view:"text",  label:"Email", name:"email", id:"email"},
    { view:"button",  name:"submit", value:"Submit", id:"btn"}
];
 
webix.ui({
    view:"form", 
    id:"my_form", 
    elements: form1
});
 
// доступ к объекту поля «логин»    
var login = $$("my_form").elements.login;
 
// получение значения поля «логин»
var loginValue = $$("my_form").elements.login.getValue();

Также вы можете применить метод getValue() для нужного контрола:

var loginValue = $$("log").getValue();

Получить values всех элементов формы

Чтобы получить ассоциативный массив значений всех элементов (пары name:value), вы можете использовать метод getValues. Чтобы получить необходимое значение, вы должны указать name нужного контрола.

var values = $$("my_form").getValues(); // возвращает { login:"", email:"", submit:"" }
 
values.login; // возвращает текущее значение поля "login"

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

  • getDirtyValues - возвращает хэш измененных значений;
  • getCleanValues - возвращает хэш неизмененных значений.

Отключение элементов формы

Любой элемент формы можно отключить или переключить в режим "только для чтения".

webix.ui({
    view:"form",
    elements:[
        { view:"text", readonly:true},
        { view:"text", disabled:true }
    ]
});

Related sample:  Form: Attributes

Больше информации о работе с методами формы в отдельной статье.

Реагирование на изменения в поле ввода

Если вы хотите отследить момент когда значение в поле ввода изменяется с одного на другое, задайте обработчик событию onChange.

Событие присоединяется к объекту элемента, который можно получить по его ID или name.

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

  • newv - новое значение контрола
  • oldv - предыдущее значение контрола
  • config - источник изменения. У аргумента могут быть следующие значения:
    • "user" - если изменение вызвано действием пользователя
    • "auto" - если изменение вызвано библиотекой (например, при вызове setValues). 
$$("form1").elements["login"].attachEvent("onChange", function(newv, oldv, config){
    webix.message(`Value was changed from ${oldv} to ${newv}. Source: ${config}`);
});

Related sample:  Form: "onChange" Event

Получение родительской формы для ввода

Самый простой способ получить родительскую форму из любого ее элемента, это вызвать метод getFormView:

Валидация изменений в поле ввода формы 

{ 
    view:"text", on:{
        onChange:function(){
            var form = this.getFormView();
            form.validate();        
        }
    }
}

Отправка данных формы

Данные формы можно послать на сервер одним из следующих способов:

1 . Используя Webix Ajax helper:

webix.ajax().post("some.php", form.getValues()); 
// с колбэком
webix.ajax().post("some.php", form.getValues(), function(text, data, xhr){ });

2 . Используя webix.send метод, который эмулирует отправку HTMLform:

webix.send("come.php", form.getValues());

3 . Не напрямую, через компонент bound master или DataCollection:

Метод удобен когда форма используется для редактирования данных основного компонента (DataTable, Tree, List и т.д.). В этом случае важны данные главного компонента, а не формы. Форма сохраняет данные в главном компоненте, в то время как мастер обрабатывает серверную часть.

// данные из выбранного элемента списка помещаются в форму
form.bind(list);
 
// отправляет данные обратно в элемент списка
form.save()

Принципы Data binding подробно описаны в отдельной статье.

Статьи по теме

 Наверх
© XB Software Ltd
2013-2024