1С-Битрикс. Как задавать настройки по умолчанию для собственного модуля? Загадки в документации

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

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> 

---

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

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

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

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

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

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

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

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

Всем добра!