Работа с модулем SIMAI: Универсальные свойства

Папка типов свойств определяется при установке модуля. Если пользователь выбрает не устанавливать отделдьную папку, то все типы берутся из /bitrix/modules/simai.property/property. Иначе папку задает сам пользователь. Следует учитывать, что при деинсталляции модуля папка типов свойств НЕ удаляется (в целях безопасности).

Для каждого типа свойства есть своя папка в папке типов свойств.

Папка типа свойства должны иметь имя, состоящее из англ. букв, цифр и знака подчеркивания. Например, "string_2" - корректное имя типа, "строка-2" - некорректное. Вывод свойства некорректного типа с помощью функционала модуля невозможен.

В папке типа свойства должен быть файл .description.php, содержащий массив вида:

 
$arDescription = array(
 "NAME" => GetMessage("SF_PROPERTY_TYPE_NAME"),
 "SORT" => 200,
 );

В этом массиве содержится наименование типа (обычно языкозависимое) и показатель сортировки среди типов.

Кроме этого, там должны быть:

• языковая подпапка lang (опционально);
• подпапка templates - шаблоны свойства (обязательно);
• файлы edit.php, filter.php, view.php, содержащие доп. функционал для редактирования, фильтра, просмотра свойства соответственно (наличие этих файлов опционально, т.к. в общем случае они не требуются - обычно достаточно функционала вызова + шаблон).

В шаблонах могут быть свои языковые папки lang, файлы из которых подключаются автоматически (вызывать языковой файл из шаблона не надо).

Для использования функционала модуля на странице в адм. панели или публичной части он должен быть подключен: \Bitrix\Main\Loader::includeSharewareModule('simai.property');

Вызовы методов модуля выглядят таким образом:

Вывод значений

 
 \SIMAI\Property::view(
 $type, // тип свойства (например, "string")
 $template, // шаблон (в случае false или пустой строки - шаблон .default)
 $values, // текущие значения свойства (одномерный массив или одиночное значение)
 $params, // массив параметров

 $safe // приведение значений и параметров к html-безопасному виду (можно не указывать, по умолчанию - true)
 );

Редактирование значений

 
 \SIMAI\Property::edit(
 $type, // тип свойства (например, "string")
 $template, // шаблон (в случае false или пустой строки - шаблон .default)
 $values, // текущие значения свойства (одномерный массив или одиночное значение)
 $params, // массив параметров
 $safe // приведение значений и параметров к html-безопасному виду (можно не указывать, по умолчанию - true)
 );

При вызове этого метода подключается яваскрипт, установленный модулем /bitrix/js/simai.property.js, что дает возможность, например, использовать кнопку "Добавить" для множ. свойств в шаблонах.

Фильтр по значениям

 
 \SIMAI\Property::filter(
 $type, // тип свойства (например, "string")
 $template, // шаблон (в случае false или пустой строки - шаблон .default)
 $values, // текущие значения свойства для фильтра (одномерный массив или одиночное значение)
 $params, // массив параметров

 $safe // приведение значений и параметров к html-безопасному виду (можно не указывать, по умолчанию - true)
 );

Список типов свойств

 
 $types_array = \SIMAI\Property::types_list();

Возвращает массив вида:

 
 array(
 array(
 'id' => {тип свойства (например, "string")},
 'name' => {языковое наименование свойства (например, "Строка")},
 'sort' => {показатель сортировки (если не указан, принимается за 500)}
 ),
 .....
 }

Массив будет отсортирован в соответствии с показателями сортировки типов.

Параметр $safe=true (по умолчанию) у вызовов edit, view, filter означает, что:

• к ключам и значениям массива $values будет применена функция htmlspecialcharsex, если $values - одиночная строка, то к ней также будет применена функция htmlspecialcharsex;
• к значениям (но не ключам!) массива $params будет рекурсивно применена функция htmlspecialcharsex.

Важно помнить про то, что ключи массива $params (в т.ч. его подмассивов) остаются html-небезопасными, поэтому к ним надо применять htmlspecialcharsex в шаблоне. Например, это имеет значение для типа list:

 
<select name="<?=$params["field_name"]?>[]" size="<?=$rows?>" multiple style="max-width:300px;">
<?foreach($params["variants"] as $v_key => $v_val):
$sel = in_array($v_key, $values);?>
<option value="<?=htmlspecialcharsex($v_key)?>"<?=($sel? " selected" : "")?>><?=$v_val?></option>
<?endforeach?>
</select>

Здесь видно, что в шаблоне .default для фильтра для подмассива $params["variants"], задающему варианты списка, применяется htmlspecialcharsex в шаблоне.

В случае, если вызов методов делается с $safe=false, все значения и ключи $values и $params должны обязательно приводиться к html-безопасному виду в шаблоне перед их выводом.

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

Модуль устанавливает тестовую страницу /bitrix/modules/simai.property/admin/sf_property_test.php, где показаны типовые вызовы методов view, edit, filter для разных типов свойств. На этой странице можно увидеть типовые параметры вызовов.

Пример (вызов edit для строкового типа с указанием множественности):

 
$values = array('a', 'bb', 'ccc'); // существующие значения
if ($bVarsFromForm) // если отправлена форма (нужно, например, при сохранении с ошибкой, когда выводятся только что отправленные значения для повторной отправки)
{
$values = $request->getPost('prop_2_value'); // то взять из массива $_POST (в стиле D7)
}
\SIMAI\Property::edit(
'string', // строка
'', // шаблон .default
$values, // значения
array(
'field_name' => 'prop_2_value', // имя поля
'multiple' => 'Y', // множественное поле
'cols' => 30, // длина полей ввода
'bVarsFromForm' => $bVarsFromForm, // передаем параметр "брать из отправленной формы"
) // параметры
);

В примере выше параметр $safe не указан и, соответственно, равен true.