Всем привет. Текст состоит из двух частей:
Небольшая шпаргалка, по параметрам настроек по умолчанию;
Текст о том, почему вообще существование такой шпаргалки может кому то понадобиться.
Часть 1
Если при создании собственного модуля, у вас есть необходимость использовать настройки по умолчанию, то для корректной работы этого функционала, нужно сделать следующее:
Создаем в корне модуля файл “default_option.php”
В самом файле определяем массив:
/*
* Файл local/modules/my_module_id/default_option.php
*/
<?
$my_module_id_default_option = array(
"option_name" => "default_option_value"
);
?>
Название массива должно строится как ”${id_вашего_модуля"_default_option"}
При использовании метода(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. На всякий случай, именно об использовании этой возможности и говорится в разделе “Параметры” этой страницы документации…
Исходя из этих примеров, лично у меня, возникает несколько вопросов:
Какой в итоге класс лучше использовать, из нового или старого ядра, или сразу оба, как показано в примерах?;
Если для использования настроек по умолчанию, я создаю файл с массивом, в котором устанавливаю эти параметры, то зачем в методе класса, передавать значение параметра по умолчанию еще раз?;
А если нужно передавать при использовании метода, то зачем тогда использовать файл “default_option.php”?;
Как должны называться параметры по умолчанию в файле “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>
Что было изменено
Я добавил два предложения в качестве примечания, и постарался сделать пример одним целым, с одними и теми же названиями переменных, аргументов и параметров.
Во всем примере используется класс из старого ядра. При желании разработчик может использовать в своей реализации класс любого ядра, но при этом в нашем примере нет путаницы.
Вот собственно и все. И не нужны одни и те же дополнительные разъяснения в чатах и форумах.
Пара разъясняющих предложений, целостный пример. И как минимум у одного человека, по конкретной задаче - не было бы абсолютно никаких вопросов.
Вот такой текст. Это первая моя статья на Хабре.
Надеюсь, что получилось неплохо, содержательно, интересно и главное полезно.
Надеюсь, что из этого сможет получится продуктивный разговор.
Всем добра!