Маршрут представляет собой шаблон пути, на основании которого принимается решение о том, какой ресурс — раздел, инфоблок, объект инфоблока, пользовательский скрипт — будет отображён при обращении по тому или иному пути, какое действие будет выполнено (просмотр, добавление, удаление, подписка и т. д.), в каком формате будет отдан ответ (HTML, RSS, XML).

Маршруты задаются для каждого сайта в отдельности.

В панели управления модулем маршруты перечислены в порядке убывания приоритета. Если для одного ресурса существует более одного адреса, при формировании путей и определении основного (канонического) адреса страницы будет использован путь с наивысшим приоритетом. Если какому-либо пути соответствуют несколько маршрутов, для определения параметров ресурса будет использован маршрут с наивысшим приоритетом.

Для изменения приоритета маршрута перетащите его вверх или вниз за значок перетаскивания.

Маршрут может быть отключён. Отключённые маршруты не используются при обработке запросов посетителей сайта и создании ссылок на ресурсы системы. Для включения или выключения маршрута нажмите на значок его состояния (ВКЛ или ВЫКЛ).

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

Редактирование маршрута

Шаблон адреса

Шаблон адреса может состоять из допустимых для путей символов и специальных блоков. Все шаблоны должны начинаться с символа «/» (косая черта, слеш).

Блок маршрута	С какими значениями в пути совпадает
`{folder}`	Путь к разделу (без начальной и конечной косой черты), составленный из ключевых слов родительских разделов, начиная от корня сайта, и ключевого слова раздела, разделённых косой чертой
`{subfolder:раздел}`	Путь к разделу от указанного раздела. В качестве параметра после двоеточия должен быть указан идентификатор родительского раздела. Например: стандартный путь к разделу с идентификатором `123` — `/about/portfolio/works/`, в нём существует подраздел с ключевым словом `acme`; тогда при существовании маршрута для раздела вида `/works/{subfolder:123}/` этот подраздел будет доступен по адресу `/works/acme/` вместо полного пути `/about/portfolio/works/acme/`. Доступно с версии 5.8.0.17211.
`{date}`	Дата (для инфоблоков, компоненты которых имеют поле типа event или event_date). Существует возможность задать формат даты: `{date:формат}`. В качестве символов для подстановки частей даты используются: «`Y`» — год (1900—2099), «`m`» — месяц (01—12), «`d`» — день месяца (01—31). Для задания альтернативных форматов их нужно отделить друг от друга прямой чертой («`\|`»). По умолчанию в качестве допустимых форматов принимаются «`Y/m/d`», «`Y/m`» и «`Y`», то есть блок `{date}` эквивалентен блоку «`{date:Y/m/d\|Y/m\|Y}`»
`{infoblock_keyword}`	Ключевое слово инфоблока
`{infoblock_id}`	Идентификатор инфоблока
`{infoblock_action}`	Действие над инфоблоком: «add» — добавление объекта, «search» — выборка, «subscribe» — подписка. По умолчанию (при отсутствии infoblock_action) — действие, указанное в настройках инфоблока (обычно — просмотр списка объектов)
`{object_keyword}`	Ключевое слово объекта
`{object_id}`	Идентификатор объекта
`{object_action}`	Действие над объектом: «edit» — редактирование, «delete» — удаление с подтверждением, «drop» — удаление без подтверждения, «checked» — включение или выключение, «subscribe» — подписка. По умолчанию (если значение object_action не указано) — просмотр объекта
`{format}`	Формат ответа: «html», «xml», «rss»
`{page}`	Страница списка объектов (устанавливает значение переменной `curPos` в nc_objects_list () исходя из количества записей на странице)
`{=имя_переменной}`	Устанавливает значение указанной переменной — имеет тот же эффект, что указание переменной в области параметров пути (`/путь/?имя_переменной=X`). Диапазон допустимых значений для переменной можно задать при помощи регулярного выражения: `{=имя_переменной:регулярное_выражение}`, например: `{=color:red\|green\|blue}` — устанавливает значение переменной `$color`, если в пути имеется строка «red», «green» или «blue» `{=min_price:\d+}` — устанавливает значение переменной `$min_price`, если в пути содержится число По умолчанию регулярное выражение для проверки значения переменной равно «`[^/]+`», то есть значение переменной будет равно любым символам до ближайшей косой черты («`/`»). Не используйте в регулярных выражениях для проверки значений переменных якоря начала (`^`) и конца (`$`) строки. Регулярные выражения должны быть указаны без разделителей и модификаторов.

Нужно учитывать, что разбор путей происходит слева направо, и для блоков {object_*} и {infoblock_keyword} на момент обработки нужно знать, о каком инфоблоке (или хотя бы разделе) идёт речь. Например, маршрут с шаблоном пути /{object_id}/{folder} работать не будет, если в дополнительных параметрах ресурса не указан идентификатор раздела.

Обратите внимание, что все блоки захватывают части путей максимально возможной для них длины. Это нужно учитывать при создании потенциально конфликтующих путей. Например, когда одновременно существуют маршруты для разделов /{folder}/ и для объектов /{folder}/{object_keyword}/, при наличии в одном разделе объектов и подразделов с одинаковыми ключевыми словами эти объекты не будут доступны по таким маршрутам.

Пример: допустим, в разделе /about/ есть подраздел и объект, оба с ключевым словом mission; для такого объекта маршрут с шаблоном /{folder}/{object_keyword}/ никогда не сработает, даже если этот маршрут имеет наивысший приоритет, так как элемент шаблона пути /{folder}/ совпадёт с частью адреса /about/mission/ и будет выбран соответствующий раздел сайта, а оставшаяся часть шаблона — {object_keyword}/ — не сможет совпасть с оставшейся частью запрошенного пути (во-первых, в данном примере оставшаяся неразобранная часть пути — это пустая строка, а во-вторых выбран раздел /about/mission/, а не /about/, в котором находится нужный нам объект).

Следует избегать создания конфликтующих путей для ресурсов различного типа.

Комментарий

Текстовое описание маршрута (выводится в списке маршрутов).

Тип ресурса

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

Параметры ресурса

В зависимости от выбранного типа ресурса существует возможность задать его параметры: идентификатор раздела, идентификатор инфоблока, идентификатор объекта, выполняемое действие и формат ответа; для скриптов — путь к скрипту (от папки, в которой установлен NetCat).

Параметры ресурса имеют приоритет над блоками адреса маршрута ({folder}, {infoblock_...}, {object_...}, {format}), поэтому при наличии в шаблоне адреса таких блоков не нужно указывать соответствующие параметры. Иными словами, задавать параметры ресурса нужно, если в пути не содержится необходимых для определения конкретного ресурса значений, или если вы хотите, чтобы маршрут работал только для указанного раздела или инфоблока.

Дополнительные переменные

Указанные в данном поле переменные будут эквивалентны указанию данных переменных в области параметров пути, например значение «sort=price&srchPat[0]=0&srchPat[1]=5000» в поле «Дополнительные переменные» даёт тот же эффект, что запрос с параметрами «?sort=price&srchPat[0]=0&srchPat[1]=5000».

Если у маршрута установлен параметр «основной маршрут для подходящих адресов должен содержать дополнительные переменные с теми же значениями» (доступен в версии 5.5.0.15074 и выше), то при определении основного (канонического) адреса будут использованы только те адреса, у которых имеются все дополнительные переменные, указанные у совпавшего маршрута, и имеющие те же значения.

Допустим, заданы следующие маршруты для объектов (в порядке уменьшения приоритета):

Шаблон адреса	Дополнительные переменные	Примечание
`/catalogue/{object_keyword}`	нет	Страница объекта в разделе `/catalogue/`
`/catalogue/{object_keyword}/print`	`nc_ctpl=100`	Версия для печати (шаблон компонента 100)
`/catalogue/{object_keyword}/print/`	`nc_ctpl=100`	Версия для печати (шаблон компонента 100)

Такой набор маршрутов будет обрабатываться следующим образом:

Если заданы перечисленные маршруты и у каждого из них установлен параметр «основной маршрут для подходящих адресов должен содержать дополнительные переменные с теми же значениями», и в настройках модуля маршрутизации установлен параметр «выполнить переадресацию на основной адрес», то при запросе страницы по адресу /catalogue/item/print/ будет выполнена переадресация на адрес /catalogue/item/print в соответствии с приоритетом маршрутов.
Если же у маршрута /catalogue/{object_keyword}/print/ не установлен параметр «основной маршрут для подходящих адресов должен содержать дополнительные переменные с теми же значениями», то основным будет считаться первый маршрут и будет выполнена переадресация на адрес /catalogue/item?nc_ctpl=100.

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

Пути к объектам без .html

Примеры шаблонов адресов:

/{folder}/{object_keyword} — содержит путь к объекту и ключевое слово
/{folder}/{object_keyword}/ — содержит путь к объекту, ключевое слово и символ «/» на конце
/{folder}/{object_id} — содержит путь к объекту и его идентификатор
/{folder}/{date:Y/m/d}/{object_keyword}/ — содержит путь к объекту, дату и ключевое слово объекта

Помните, что блок {folder} захватывает максимально возможный путь. Например, если у вас есть раздел, имеющий путь /about/company/, и объект с ключевым словом «company», при запросе страницы по адресу /about/company/ маршрут с шаблоном пути /{folder}/{object_keyword}/ не сможет быть использован для объекта «company», даже если он имеет приоритет выше, чем у маршрута для соответствующего раздела.

Предположим, в разделе есть объекты, у которых не заполнено поле с ключевым словом. В этом случае вы можете создать два правила: с помощью первого формировать пути для объекто с ключевым словом, с помощью второго используя id объекта.

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

Постраничная навигация

Создайте путь к ресурсам типа «Раздел» с шаблоном адреса, содержащим {page}, например:

/{folder}/{page}
/{folder}/page-{page}
/constant-path/page{page}

Маршрут должен иметь приоритет выше, чем путь к инфоблоку (или разделу) без указания номера страницы.

Короткий путь к определённому разделу

Создайте пути к ресурсам типа «Раздел», «Объект» (в случае наличия в разделе более одного инфоблока — также к ресурсам типа «Инфоблок»), указав идентификатор раздела, например:

Тип ресурса: раздел, шаблон адреса: /short/, раздел: 543
Тип ресурса: объект, шаблон адреса: /short/{object_id}, раздел: 543

Нестандартный формат даты

Пример: маршрут с шаблоном /{folder}/{date:Y-m-d}-{object_keyword} будет соответствовать путям вида /news/2014-06-30-date-formats-in-routes

Передача значений переменных в основной части пути

Например, переменная $size отвечает за фильтрацию списка объектов по свойству «Размер»; тогда при наличии маршрута с шаблоном /{folder}/{=size:S|M|L|XL|XXL|XXXL} можно создать «красивые» пути вида /t-shirts/M, /dresses/L к страницам с такими списками объектов.

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

О генерации путей с подстановкой переменных можно прочитать в разделе «Получение адресов страниц».

Пути с параметрами для srchPat

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

Например, в разделе с каталогом товаров srchPat[0] отвечает за фильтрацию по текстовому «Производитель». Создайте маршрут: шаблон пути — /watches/{=manufacturer}/ (где /watches/ — путь к конкретному разделу каталога), тип ресурса — раздел или инфоблок; укажите идентификаторы раздела и инфоблока. В системных настройках соответствующего компонента присвойте переданное значение нужному элементу srchPat:

if (isset($manufacturer)) { 
    $srchPat[0] = $manufacturer; 
}

В результате запрос по адресу /watches/Seiko/ будет соответствовать запросу по адресам /watches/?srchPat[0]=Seiko или /watches/?manufacturer=Seiko.

Для полей типа «список» значение соответствующего элемента массива srchPat равно идентификатору элемента списка (то есть является числовым). Если вы хотите использовать в путях вместо идентификаторов строковые значения, вы можете использовать в качестве такого строкового значения название элемента списка или поле «Дополнительное значение»; в системных настройках будет необходимо выполнять дополнительное преобразование из строкового значения в пути в идентификатор элемента списка.

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

if (isset($manufacturer)) { 
    $srchPat[0] = $db->get_var("SELECT `Manufacturer_ID` FROM `Classificator_Manufacturer` WHERE `Manufacturer_Name` = '" . $db->escape($manufacturer) . "' LIMIT 1");
}

Пример с использованием дополнительного значения элемента списка:

if (isset($manufacturer)) { 
    $srchPat[0] = $db->get_var("SELECT `Manufacturer_ID` FROM `Classificator_Manufacturer` WHERE `Value` = '" . $db->escape($manufacturer) . "' LIMIT 1");
}

«html-страницы» в корневом разделе сайта

Если вам нужны адреса для страниц объектов вида /page.html (без пути к разделу), создайте маршрут со следующими параметрами:

тип ресурса: объект
шаблон адреса: /{object_keyword}.html
раздел: идентификатор раздела, из которого будут взяты объекты;
инфоблок: идентификатор инфоблока, из которого будут взяты объекты.

Короткий путь к подразделам определённого раздела

Для вывода содержимого раздела по путям, не соответствующим положению соответствующих подразделов или объектов в структуре сайта, можно использовать шаблон адреса {subfolder}.

Например, чтобы пути подразделов /shop/products/ (раздела, имеющего идентификатор 123) выглядели как если бы эти подразделы находились в корне сайта, нужно создать маршруты:

Путь к подразделам /shop/products/:
- Тип ресурса: раздел, шаблон адреса: /{subfolder:123}/
  Например, раздел со стандартным путём /shop/products/dresses/casual/ будет доступен по адресу
  /dresses/casual/.
Пути к инфоблокам в подразделах /shop/products/:
- Тип ресурса: инфоблок, шаблон адреса: /{subfolder:123}/{infoblock_keyword}.{format}
Пути к объектам в подразделах /shop/products/:
- Тип ресурса: объект, шаблон адреса: /{subfolder:123}/{object_keyword}.{format}
- Тип ресурса: объект, шаблон адреса: /{subfolder:123}/{infoblock_keyword}_{object_id}.{format}

Ссылка на внешний скрипт

Вы можете создать маршрут на внешний скрипт. Предположим, у вас в корне сайта находится файл myscript.php, который содержит определённую функцию. Пример формирования маршрута:

тип ресурса: скрипт
шаблон адреса: /somesub/link/
путь к скрипту: myscript.php

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

12.17.2 Получение адресов страниц Далее →

Наверх