1. Документация
  2. Для разработчика сайта
  3. Функции и классы
  4. Встроенные классы
  5. Класс Router

Метод Router::convert()

У метода Router::convert() два назначения.

  1. Основное назначение метода - это превращение параметрических ссылок (то есть, состоящих из набора параметров) в человекопонятные URL (ЧПУ).

  2. Второе назначение метода — регистрация псевдостраниц в структуре сайта. Без регистрации псевдостраницы вы не сможете задать ее титул (и другие данные из раздела Настройки страницы. Вы не сможете создать навигационную цепочку с помощью метода Router::getBreadcrumbs(), и вообще, не будет работать ни один метод класса Router.

Метод Router::convert() нужно применять в первую очередь ко всем первичным ссылкам, то есть, ссылкам, находящимся в навигационных блоках. При этом нужно быть внимательными, и указывать правильные ключи для регистрации параметрических ссылок. Для конвертации же вторичных ссылок, никаких доп. параметров в функцию передавать не нужно.

У метода имеются два параметра: Router::convert($phref, $infos=[])


ПараметрПримечания

$phref — относительный параметрический URL

  • То есть, URL должен начинаться со знака '?'. Примеры:
    ?page=2 (штатная страница)
    ?page=2&block=47&p[1]=1 (псевдостраница)
  • Проверяйте параметр $phref на целостность перед вставкой в метод Router::convert(). Попадание пустых параметров URL вызовет появление лишних ссылок, что негативно скажется на поисковом продвижении сайта.

$infos['name'] — название страницы.

Отображается в навигационной цепочке (хлебные крошки).

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

$infos['title'] — титул страницы.

Содержимое тега <title>.

$infos['alias'] — алиас (псевдоним) страницы.

Отображается как элемент в ЧПУ. Автоматически производится транслитерация кириллицы в латиницу, если включена транслитерация

$infos['key'] — уникальный ключ ссылки.

Рекомендуется использовать комбинацию из номера исходного блока и номера строки записи, в которой находится ссылка: $blockInfo['src-block-id'].'-'.$dat['rec'].

  • Применяется только для ссылок на псевдостраницы.
  • Для штатных ссылок, то есть, ссылок без спец.запросов, элементы $infos['key'] и $infos['parent-key'] применять не нужно!

$infos['parent-key'] — ключ родительской ссылки.

Если родительская страница является штатной страницей (не псевдостраницей) присвойте этому элементу значение: пустая строка ('').

Если родительские ключи программно вычислить не удается, существует ручной метод, а именно: в окне Настройки страницы

$infos['xhref']
Дополнительный параметрический хвост ссылки

Это часть человекопонятной ссылки, которую по каким-либо причинам нужно оставлять в параметрическом виде.

  • Обычно — это вторичные ссылки, которые используются для сортировки, поиска по блоку и т.п. Для вторичных ссылок другие элементы массива $infos не нужны. Пример: $href = Router::convert($phref, ['xhref'=>'sort[1]=desc']);
  • Кстати, сортировку по умолчанию лучше задавать не в URL, в параметрах шаблона, а "хвост" добавляйте, когда понадобится сортировка в порядке, противоположном от заданного по умолчанию.
  • Запросы, которые на первый взгляд нужно было бы поместить в параметрический хвост, иногда нужно включить в основную часть ссылки. Ниже приведен пример ссылки с поисковым запросом, которую нужно регистрировать как первичную, так как она является пунктом меню, основанного на поисковых запросах: 
    $phref = '?page='.$page.'&block='.$block.';
$phref .= '&search[2]='.$dat[1]';
$href = Router::convert($phref, ['name'=>$dat[1], ...]);
echo '<a href="'.$href.'">'.$dat[1].'</a>';

$infos['url-params']
Массив имен нештатных параметров, которые могут использоваться в $phref.

  • По умолчанию зарегистрироваться могут URL только со штатными параметрами, например: "?page=22&block=33&p[1]=3&backward=1".
  • Список всех штатных url-параметров: page, block, part, single, backward, limit, p, pick, s, search, sort, highlight, fields, what, where.
  • При наличии в URL нештатного параметра, конвертация параметрической ссылки в ЧПУ производиться не будет. Чтобы конвертация происходила, необходимо добавлять данный параметр-массив, например: ['company', 'id'].
  • Есть способ указать параметры URL, которые будут вообще игнорироваться сайтом. Это можно сделать в разделе админки: Сайт > Настройки сайта > Игнорируемые URL-параметры.

Пример кода

nav.tpl 
<?php
$infos['parent-key'] = '';
echo '<ul>';
    foreach ($tab as $dat) {
        $phref = '?page='.$page.'&block=36&p[1]='.$dat['rec'];
        $infos['name'] = $dat[1]; //['alias'] и ['title'] будут такими же
        $infos['key'] = $block.'-'.$dat['rec'];
        $href = Router::convert($phref, $infos);//human href
        echo '<li>'.$dat['edit'].'<a href="'.$href.'">'.$dat[1].'</a></li>';
    }
echo '</ul>';
?>

Вторичные ссылки

Для вторичных ссылок, например (ссылок, не находящихся в навигационных блоках), второй параметр $infos нужно опустить: $href = Router::convert($phref). Это касается как штатных ссылок, так и ссылок на псевдостраницы. В первом случае эти опции просто не нужны, во втором случае эти опции приведут к нежелательной регистрации новой псевдостраницы.

Совет

В полях varchar, предназначенных для хранения URL, желательно хранить параметрические ссылки, которые при выводе в шаблоне преобразовывать с помощью Router::convert().

.tdd
<?php
    $types[1]='varchar(255)';
?>
.tpl
<a href="<?=Router::convert($dat[1])?>">
    Подробнее
</a>

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

.tuh
<?php
    $_POST['dat'][1] = Url::convertToRelative($_POST['dat'][1]);
?>

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

Особенности обработки запроса part

Обработка ссылок с параметром part (с пагинацией) имеет особенности. Хотя запрос part и создает новый URL, однако такие ссылки не регистрируются системой, и считаются вторичными.

Поэтому массив $infos можно опустить. Однако, выводить в хвост часть URL, связанную с запросом part, не нужно, так как система должна обработать параметрический URL и сформировать человекопонятный URL (ЧПУ) с учетом запроса part.

В ЧПУ с пагинацией в конец добавится номер части и слеш: katalog/instrument/dreli/48/

Кстати, из-за такого вида ЧПУ с пагинацией, в системе запрещены чисто цифровые алиасы страниц.

Чтобы не возникали разные ссылки, приводящие на одну и туже страницу, part-запрос, открывающий страницу по умолчанию, лучше опускать. Например вместо ?page=3&block=4&part=1 нужно писать ?page=3

Примечания

  • Режим ЧПУ включается в разделе: Сайт > Настройки сайта.
  • Если режим ЧПУ не включен, то функция Router::convert() возвращает параметрическую ссылку (отформатированную в стандартном порядке).
  • При просмотре сайта в авторизованном режиме, ЧПУ не включаются, то есть все ссылки будут параметрическими.
  • Применение ЧПУ не оправдано в случаях, когда адрес не виден пользователю (например, в Ajax).

См. также