Всем привет. Текст состоит из двух частей:

1. Небольшая шпаргалка, по параметрам настроек по умолчанию;

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

Часть 1

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

1. Создаем в корне модуля файл “default_option.php”

2. В самом файле определяем массив:

/*
 * Файл local/modules/my_module_id/default_option.php
 */
<?
$my_module_id_default_option = array(
    "option_name"    => "default_option_value"
    );
?>

Название массива должно строится как ”${id_вашего_модуля"_default_option"}

3. При использовании метода(D7):

<?
	$variable = Option::get("my_module_id", "option_name");
?>

или методов класса COption(старое ядро):

<?
  $variable  = COption::GetOptionString("my_module_id", "option_name");
  $intVariable  = COption::GetOptionInt("my_module_id", "option_name");
?>

передаем только два аргумента:

• id вашего модуля

• название параметра настроек.

   4. Названия параметра настроек должны быть идентичны, в файле option.php, default_option.php и конечно же при использовании методов класса Option или COption.

Часть 2

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

Целями разговора не являются жалобы, укоры, упреки в адрес компании или разработчиков.

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

Сразу оговорюсь, что, я так называемый “вайтишник”, базовых и фундаментальных знаний нет. Я конечно же занимаюсь заполнением этих пробелов, но могу путать и не знать разницы между аргументами функции и параметрами. Да и в целом весь этот текст, является дилетантским. Поэтому, прошу неравнодушных к азам программирования, обсуждать не только уровень навыков и интеллекта автора, но и саму тему статьи. Заранее благодарю.

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

На первом же экране начинаются странности:

Вроде бы пока все хорошо. Но смущает непонятно откуда взявшийся id модуля “support”(больше он нигде нам так и не встретиться). Также обратим внимание на имена параметров в массиве, просто отметим что они есть, и как они называются.

Смотрим дальше:

Здесь нам говорят, что для работы с параметрами используется класс COption, правда ниже(цифра 4 на скрине), в одном из примеров, нам демонстрируют использование аналога этого метода из нового ядра Option::get(); С какой целью?

Ок. Дальше два примера методов этого класса, в которых id модуля уже называется почему то не “support”, как можно было бы ожидать, а “my_module_id”(цифра 1 на скрине).

В качестве имени параметра передается “MY_PARAMETER_ID”(цифра 2 на скрине), которого почему то нет в примере выше, в том самом массиве, из файла “default_option.php”

В примере метода get(), третьим аргументом указано значение параметра по умолчанию(цифра 3 на скрине), хотя если мы используем файл default_option.php, третий аргумент передавать не нужно, чтобы он “подтянулся” из массива $ID_модуля_default_option. На всякий случай, именно об использовании этой возможности и говорится в разделе “Параметры” этой страницы документации…

Исходя из этих примеров, лично у меня, возникает несколько вопросов:

1. Какой в итоге класс лучше использовать, из нового или старого ядра, или сразу оба, как показано в примерах?;

2. Если для использования настроек по умолчанию, я создаю файл с массивом, в котором устанавливаю эти параметры, то зачем в методе класса, передавать значение параметра по умолчанию еще раз?;

   А если нужно передавать при использовании метода, то зачем тогда использовать файл “default_option.php”?;

3. Как должны называться параметры по умолчанию в файле “default_option.php” и в методах класса, одинаково или как угодно/удобно? Из примеров к сожалению это непонятно, и в тексте никаких указаний или рекомендаций на этот счет нет.

Хорошо. Давайте посмотрим на документацию по классам. Сначала по методу класса старого ядра COption::GetOptionString();

Предельно просто и понятно указано, как работать с методом.

Правда вопрос по “неймингу” для параметров остается открытым, и возникает вопрос, для чего же тогда в примере по созданию модуля, третий аргумент все таки передается, несмотря на то, что мы используем файл “default_option.php”.

Но в документации по созданию модуля, есть еще пример с классом из нового ядра Option, давайте посмотрим документацию по его методу get()

Здесь, уже более скудное описание по интересующему нас аргументу. 

Нет ни слова про файл “default_option.php”. И соответственно, если не пройти и не посмотреть аналог этого класса из старого ядра, эта информация останется недоступной. 

В итоге, документация - не снимает вопросы, а генерирует их. Я конечно отдаю себе отчет, что я неминуемо что то упустил, и/или из-за отсутствия навыков и опыта, неправильно понял что-то. И возможно, будь я более опытным разработчиком, этих вопросов бы просто не возникло.

Также я понимаю, что решение подобных “проблем”, исследование документации, хорошо прокачивают меня. Чтобы поддерживать хорошее настроение, можно даже представлять себя Индианой Джонсом, в очередном приключении…старое ядро…новое ядро…форум битрикс и его хранители. 

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

Повторюсь, этот текст не про упреки. А про то, что возможно, множество вопросов можно снять, просто немного подправив документацию?

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

Позволю себе некоторую наглость, и приведу пример того, как на мой взгляд, мог бы выглядеть раздел “Параметры”, страницы с описанием создания модуля:

Параметры

Параметры модуля доступны для изменения в административном интерфейсе на странице Настройки модулей (Настройки > Настройки продукта > Настройки модулей). При выборе модуля на данной странице, система подключает файл /bitrix/modules/my_module_id/options.php, предназначенный для управления параметрами модуля, назначения прав на модуль и т.п.

Параметры модуля хранятся в базе данных.

При получении параметров модуля, может использоваться значение по умолчанию, задаваемое в файле /bitrix/modules/my_module_id/default_option.php. В данном файле определяется массив $my_module_id_default_option, хранящий значения по умолчанию.

Пример файла /bitrix/modules/my_module_id/default_option.php:

<?
/*
 * Файл local/modules/my_module_id/default_option.php
 */
$my_module_id_default_option = array(
    "MY_PARAMETER_ID"  =>  "DEFAULT_VALUE"
    );
?>

Для работы с параметрами модуля предназначен класс COption. Методы класса:

• SetOptionString - установка строковых параметров

• SetOptionInt - установка числовых параметров

• GetOptionString - получение строковых параметров

• GetOptionInt - получение числовых параметров

• RemoveOption - удаление параметра 

Примеры использования:

Строковый параметр

<?
// установим строковый параметр
COption::SetOptionString("my_module_id", "MY_PARAMETER_ID", "VALUE");
// получим строковый параметр
$value = COption::GetOptionString("my_module_id", "MY_PARAMETER_ID", "DEFAULT_VALUE");
?>

Прим. При использовании файла default_option.php, заданные в нем значения параметров по умолчанию, не нужно передавать третьим аргументом “def” при вызове метода COption::GetOptionString();

Названия параметров, должны быть идентичными в файле default_option.php и в методах класса COption.

Параметр типа файл. (Загрузка файла в модуле)

<table>
  <tr> <td width="40%">
       <?
       $path_file = COption::GetOptionString("my_module_id", 'CLEVERSCRIPT_IMG_DESCTOP_BTN');
       CAdminFileDialog::ShowScript
       (
           Array(
               "event" => "BtnClick_0",
               "arResultDest" => array("FORM_NAME" => "cleverscriptwantcheaper", "FORM_ELEMENT_NAME" => "CLEVERSCRIPT_IMG_DESCTOP_BTN"),
               "arPath" => array("PATH" => GetDirPath($path_file)),
               "select" => 'F',// F - file only, D - folder only
               "operation" => 'S',// O - open, S - save
               "showUploadTab" => true,
               "showAddToMenuTab" => false,
               "fileFilter" => 'jpg,jpeg,gif,png',
               "allowAllFiles" => true,
               "SaveConfig" => true,
           )
       );
       ?>
       <?echo Loc::getMessage("T_CLEVERSCRIPT_IMG_DESCTOP_BTN")?>
   </td>
   <td width="60%">
       <input type="text" name="CLEVERSCRIPT_IMG_DESCTOP_BTN" size="50" maxlength="255" value="<?echo $path_file?>"> <input type="button" name="browse_0" value="..." onClick="BtnClick_0()">
   </td>
</tr>
</table>

Что было изменено

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

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

Вот собственно и все. И не нужны одни и те же дополнительные разъяснения в чатах и форумах.

Пара разъясняющих предложений, целостный пример. И как минимум у одного человека, по конкретной задаче - не было бы абсолютно никаких вопросов.

Вот такой текст. Это первая моя статья на Хабре.

Надеюсь, что получилось неплохо, содержательно, интересно и главное полезно.

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

Всем добра!