ВебмастерМетрикаВиджетыРекламная сетьДиректПоиск для сайтаAPI
ещё
кабинет разработчика виджетов
Войти
Помощь
Найти

Быстрый старт

Руководство разработчика

Справочник по API
В формате PDF
← Ctrl предыдущаяследующая Ctrl →

Настройки виджета

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

Для использования настроек нужно объявить пространство имен Яндекс.Виджетов:

xmlns:widget="http://wdgt.yandex.ru/ns/"

Пользовательские настройки содержатся в теге-контейнере <widget:preferences>, который необходимо помещать в блок <head> XHTML-файла виджета. Каждой настройке соответствует вложенный тег <preference>. Например:

<head>
    <widget:preferences>    
       <preference name="color" type="text" defaultValue="green" />
       <preference name="..." type="..." />
       ... 
    </widget:preferences>
</head>

Настройки передаются в адресной строке как GET-параметры в парах <имя настройки, значение настройки>:

?preferenceName1=value1&preferenceName2=value2...&preferenceNameN=valueN

Общий размер информации, которая может храниться в настройках, не должен превышать 1 KB.

Пользователь может менять свои настройки через форму настроек, которая автоматически генерируется на основе информации, содержащейся в теге <widget:preferences>. Форма генерируется и передается непосредственно в момент запроса пользователем настроек виджета.

Совет

Используйте метод showPreferences, чтобы пользователь мог открыть форму настроек по ссылке из виджета.

Примечание
Если виджет не содержит пользовательских настроек, тег <widget:preferences> указывать не нужно.

Атрибуты тега preference

Обязательные
Атрибут Значение
name Название пользовательской настройки. Используется для программной идентификации настройки (сравните с именем переменной). Пользователь не видит значение данного атрибута.
type Тип пользовательской настройки. Допустимые значения: text, boolean, hidden, list, geo, multi. Подробнее см. Типы настроек.
Необязательные
Атрибут Значение
label Текстовое описание пользовательской настройки, которое отображается на форме настроек. Значение данного атрибута может содержать любые знаки, доступные в кодировке UTF-8. Ограничение по длине - 256 знаков. Если параметр превышает это значение, остаток строки отбрасывается.
defaultValue Значение пользовательской настройки по умолчанию. Допустимые значения зависят от типа атрибута. Подробнее см. Типы настроек.

Типы настроек

Примечание
Типы настроек задаются в атрибуте type тега preference.

text

Текстовое поле ввода. Соответствующий HTML-код в форме настроек:

<input type="text" />

Значение по умолчанию: пустая строка (если не задано иное значение по умолчанию в атрибуте defaultValue).

boolean

Бинарный флаг. Соответствующий HTML-код в форме настроек:

<input type="checkbox" />

Допустимые значения:

  • false (по умолчанию, если не задано иное значение по умолчанию в атрибуте defaultValue);
  • true.

hidden

Переменная, которая явно НЕ отображается на форме настроек. Соответствующий HTML-код в форме настроек:

<input type="hidden" />

Переменная может быть использована для хранения значений, которые обрабатываются, например, с помощью JS API.

list

Раскрывающийся список. Элементы списка указываются во вложенных тегах option. Тег option имеет единственный атрибут value, в котором указывается значение соответствующего пункта списка (для программной обработки):

<preference name="months" type="list" defaultValue="1">
  <option value="1">Январь</option>
  <option value="2">Февраль</option>
  <option value="3">Март</option>
  ...
</preference>

Значение по умолчанию задается в атрибуте defaultValue тега preference как одно из значений, указанных в атрибутах value для элементов списка. Если атрибут defaultValue не указан или содержит несуществующее значение, значение по умолчанию считается неопределенным.

Соответствующий HTML-код в форме настроек:

<select name="months">
  <option value="1">Январь</option>
  <option value="2">Февраль</option>
  <option value="3">Март</option>
  ...
</select>

geo

Раскрывающийся список с географическими названиями из географической базы Яндекса. Например:

<preference name="allCities" type="geo" label="Регион:"/>

В форме настроек отображается в виде элемента «геосаджест»:

multi

Список с возможностью выбрать несколько значений. Элементы списка указываются во вложенных тегах option. Значения элементов, которые используются для программной обработки, указываются в атрибутах value:

<preference name="somename" type="multi" label="choose something" defaultValue="1,2">
    <option value="1">One</option>
    <option value="2">Two</option>
    <option value="3">Three</option>
</preference>

В форме настроек отображается в виде двух списков: слева ― доступные значения, справа ― выбранные значения.

Значение по умолчанию задается в атрибуте defaultValue тега preference в виде перечисленных через запятую значений атрибутов value. Если атрибут defaultValue не указан или содержит несуществующее значение, значение по умолчанию считается неопределенным.

Текст элемента списка может быть указан следующими способами:

  • значение тега option;
  • значение атрибута label тега option.

Перечисленные способы эквивалентны:

<preference name="somename" type="multi" label="choose something" defaultValue="1,2">
    <option value="1">One</option>
    <option value="2" label="Two"/>
    <option value="3">Three</option>
</preference>

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

Список поддерживает группировку с помощью тега group. В атрибуте label тега group указывается название группы элементов:

<preference name="somename" type="multi" label="choose something" defaultValue="3,6">
    <group label="FIRST">
        <option value="1">One</option>
        <option value="2">Two</option>
        <option value="3">Three</option>
    </group>
    <group label="SECOND">
        <option value="4">Four</option>
        <option value="5">Five</option>
        <option value="6">Six</option>
    </group>
</preference>

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

Примечание

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

<!--Список в форме настроек будет без группировки элементов-->
<preference name="somename" type="multi" label="choose something" defaultValue="2,4">
    <option value="1">One</option>
    <group label="FIRST">
        <option value="2">Two</option>
        <option value="3">Three</option>
    </group>
    <group label="SECOND">
        <option value="4">Four</option>
        <option value="5">Five</option>        
    </group>
</preference>

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

См. также