Пользовательские настройки

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

Примеры подобных настроек для блока фактов (поля компонента: заголовок, подзаголовок, иконка, ссылка):

• цвет иконки // выбор из нескольких предопределенных вариантов
• свой цвет // указание RGB
• горизонтальное выравнивание
• иконка по умолчанию // если редактор не закачал иконку
• открывать ли ссылку в новой вкладке

Значения этих настроек будут доступны в шаблонах компонента в массиве $cc_settings[], а установить их сможет пользователь в диалоге настройки блока.

• Управление настройками происходит во вкладке формы редактирования компонента “Пользовательские настройки”. Добавлять и редактировать настройки можно как в диалоговом режиме, так и в виде массива. Каждая настройка имеет свойства:
• Название поля: индекс элемента массива, в котором будет храниться значение настройки. Если название настройки blank, то в шаблоне значение этой настройки будет доступно в элементе $cc_settings[“blank”].
• Описание: надпись, которая будет выведена в форме настройки блока рядом с полем формы. Например, “Открывать ссылки в новой вкладке”.
• Начальное значение при создании инфоблока.
• Значение по умолчанию (если в поле ничего не указано).
• Не показывать в форме редактирования настроек: может быть использовано, к примеру, когда значение настройки устанавливается программно.
• Тип.

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

У некоторых типов настроек есть дополнительные настройки.

Строка

Для этого типа можно указать регулярное выражение, проверяющее валидность вводимого текста, а также выводимый текст ошибки в случае несоответствия введенного текста этому регулярному выражению. Также можно указать длину строки ввода.

Текст

Дополнительные настройки: использовать wysiwyg-редактора в поле ввода, преобразовывать перенос строки в тег <br/>, высота поля ввода.

Целое число, дробное число

Дополнительные настройки: минимальное и максимальное значение.

Логическая переменная

Дополнительных настроек нет.

Дата и время

Дополнительных настроек нет.

Список

У этого типа есть подтип: вид списка. Список может быть:

• Статический. Возможные варианты значений указываются тут же, в форме редактирования настройкой. У каждого варианта есть ключ (значение, которое будет доступно в шаблонах редактирования компонента) и значение (что увидит пользователь в форме настройки блока). Например, для выбора цвета иконки из предустановленных вариантов (каждому из которых соответствует css-класс) элементы статического списка могут быть такими: 'red' => 'красный', 'green' => 'зеленый', 'black' => 'черный'. 
• Классификатор. Варианты значений списка будут браться из выбранного списка-классификатора, который есть в системе (меню “разработка - списки”).
• Динамический. Потребуется указать SQL-запрос, которым надо получить варианты.

Связь с другой сущностью

Дополнительная настройка: тип сущности: раздел, блок (компонент в разделе), пользователь, компонент. В форме настройки блока пользователю нужно будет выбрать или указать соответствующий раздел, блок, пользователя или компонент. В поле будет храниться ID данной сущности.

Файл

Дополнительная настройка: тип файла (произвольный, изображение, иконка). Для изображения также можно указать ширину и/или высоту для авторесайза. При этом, авторесайз будет применен к самому закачанному файлу. Прочитайте о том, как выполнить авторесайз с сохранением исходного файла.

Цвет

Дополнительных настроек нет.

Разделитель

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

HTML-блок

Произвольный код, который будет выведен в форме. Например, может быть использован для добавления в форму JavaScript, если нужно обрабатывать взаимные зависимости полей в форме (к пример, должно быть заполнено как минимум одно из двух полей).

Пример 

Реализуем приведенный в начале статьи пример. Предположим, изначальный шаблон вывода факта в списке выглядит так:

<!-- FormPrefix -->
<?= $f_AdminCommon; ?>
<!-- /FormPrefix -->

<!-- RecordTemplate --><?= $f_AdminButtons; ?>
<div class="fact-item">
  <?
    if($f_Link)
    {
      echo "<a href=\"".$f_Link."\">";
    }
  ?>
  <div class="fact-icon">
    <?= $f_Image->as_icon(); ?>
  </div>
  <div class="icon-name"><?= $f_Title; ?></div>
  <?= $f_Link ? "</a>": NULL; ?>  
</div><!-- /RecordTemplate -->

<!-- FormSuffix --><!-- /FormSuffix -->

Добавим пять перечисленных в начале статьи настроек. В виде массива они будут выглядеть так:

$settings_array = array (
  'iconcolor' => 
  array (
    'type' => 'select',
    'subtype' => 'static',
    'caption' => 'Цвет иконки',
    'default_value' => 'red',
    'initial_value' => 'red',
    'skip_in_form' => '0',
    'values' => 
    array (
      'red' => 'красный',
      'green' => 'зеленый',
      'black' => 'черный',
    ),
  ),
  'rgb' => 
  array (
    'type' => 'string',
    'subtype' => NULL,
    'caption' => 'Свой цвет в RGB',
    'initial_value' => '',
    'skip_in_form' => '0',
    'validate_regexp' => '',
    'validate_error' => '',
    'size' => '',
  ),
  'align' => 
  array (
    'type' => 'select',
    'subtype' => 'static',
    'caption' => 'Горизонтальное выравнивание',
    'initial_value' => 'left',
    'skip_in_form' => '0',
    'values' => 
    array (
      'left' => 'по левому краю',
      'center' => 'по центру',
      'right' => 'по правому краю',
    ),
  ),
  'icondefault' => 
  array (
    'type' => 'file',
    'subtype' => 'icon',
    'caption' => 'Иконка по умолчанию',
    'initial_value' => '',
    'skip_in_form' => '0',
  ),
  'blank' => 
  array (
    'type' => 'checkbox',
    'subtype' => NULL,
    'caption' => 'Открывать в новом окне',
    'initial_value' => '',
    'skip_in_form' => '0',
  ),
);

Теперь изменим шаблоны префикса и объекта, добавив обработку настроек:

<!-- FormPrefix --><?= $f_AdminCommon; ?>
<?
  $rgb="";
  $iconcolor="";
  if($cc_settings["rgb"])
  {
    $rgb = $cc_settings["rgb"];
  }
  else
  {
    $iconcolor=$cc_settings["iconcolor"];
  }
?><!-- /FormPrefix -->

<!-- RecordTemplate -->
<?= $f_AdminButtons; ?>
<div class="fact-item" style="text-align: <?= $cc_settings["align"]; ?>">
  <?
    if($f_Link)
    {
      echo "<a href=\"".$f_Link."\"";
      if ($cc_settings["blank"])
        {
          echo "target=\"_blank\"";
        }
      echo ">";
    }
  ?>  
  <div class="fact-icon">
    <?= (string)$f_Image ? $f_Image->as_icon(array("class" => "color-".$iconcolor, "fill" => $rgb)) : $cc_settings["icondefault"]->as_icon(array("class" => "color-".$iconcolor, "fill" => $rgb)); ?>
  </div>
  <div class="icon-name"><?= $f_Title; ?></div>
  <?= $f_Link ? "</a>": NULL; ?>  
</div><!-- /RecordTemplate -->

<!-- FormSuffix --><!-- /FormSuffix -->