WordPress как на ладони

Kama Breadcrumbs

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

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

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

Использование

Используйте следующий код в файле темы, там где нужно вывести крошки:

<?php do_action( 'echo_kama_breadcrumbs' ) ?>

Или можно вызвать так с передачей параметров:

<?php do_action( 'echo_kama_breadcrumbs', $args, $l10n ) ?>

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

$breadcrumbs = kama_breadcrumbs( $args, $l10n );
$args(массив)

Параметры крошек. Пример вызова с параметрами:

<?php
$args = [
	'sep'             => ' › ',
	'on_front_page'   => false,
	'show_post_title' => false,
	'markup'          => 'Microdata', // RDFa, Microdata, data-vocabulary.org
	'priority_tax'    => [ 'category' ],
	'number_tax'      => [ 'category' => 2 ],
	'disable_tax'     => [ 'post_tags' ],
];

do_action( 'echo_kama_breadcrumbs', $args );
?>

Все возможные параметры:

  • sep
    Разделитель. Можно указать вместе с HTML оберткой: <span> » </span>.
    По умолчанию: ' » '

  • on_front_page
    Выводить крошки на главной странице.
    По умолчанию: true

  • show_post_title
    Показывать ли название записи в конце (последний элемент). Для записей, страниц, вложений.
    По умолчанию: true

  • show_term_title
    Показывать ли название элемента таксономии в конце (последний элемент). Для меток, рубрик и других такс.
    По умолчанию: true

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

  • nofollow
    добавлять rel=nofollow к ссылкам?
    По умолчанию: false

  • priority_tax(с версии 4.7)
    Приоритетные таксономии, нужно когда запись в нескольких таксах: array( 'category', 'tax_name' ).
    Порядок имеет значение — чем раньше тем важнее.

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

    Когда запись находится в нескольких элементах одной таксы одновременно. Например:

    array(
    	'category' => [ 45, 'term_name', 'имя терма' ],
    	'tax_name' => [ 1, 2, 'name' ]
    )

    В этом коде category - это название таксономии для которой указываются приоритетные элементы.

    • 45 - ID термина
    • term_name - ярлык
    • имя терма - заголовок.

      Порядок 45, term_name и имя терма имеет значение: чем раньше тем важнее. Все указанные термины важнее неуказанных.

    По умолчанию: array()

  • disable_tax
    Таксономии которые нужно исключить из показа в крошках: array( 'post_tag', 'tax_name' )
    По умолчанию: array()

  • number_tax
    Позволяет выводить в крошках для записей сразу несколько таксономий.

    Например, если указать [ 'post' => 2 ], то для типа записи post выведет крошки для двух таксономий по умолчанию: category и post_tag.

    Поменять порядок можно в параметре priority_tax.
    По умолчанию: array()

  • markup
    Микроразметка. Может быть: Microdata, RDFa, data-vocabulary.org, '' - без микроразметки.

    Можно указать свой массив разметки, например:

    array(
    	'wrappatt'  => '<div class="kama_breadcrumbs">%s</div>',
    	'linkpatt'  => '<a href="%s">%s</a>',
    	'titlepatt' => '<span class="kb_title">%s</span>',
    	'seppatt'   => '<span class="kb_sep">%s</span>'
    )

    По умолчанию: 'Microdata'

  • wrap_class
    CSS класс для главного div.
    По умолчанию: 'kama_breadcrumbs'

  • title_class
    CSS класс заголовка элемента.
    По умолчанию: 'kb_title'

  • sep_class
    CSS класс разделителя.
    По умолчанию: 'kb_sep'

  • use_the_title_filter
    Использовать ли фильтр the_title для заголовков записей.
    По умолчанию: false
меню
$l10n(массив)

Параметры локализации. Строки переводятся на англ. если у сайта выбран англ. язык. По умолчанию:

// Локализация
$l10n = array(
	'home'       => 'Главная',
	'paged'      => 'Страница %d',
	'_404'       => 'Ошибка 404',
	'search'     => 'Результаты поиска по запросу - <b>%s</b>',
	'author'     => 'Архив автора: <b>%s</b>',
	'year'       => 'Архив за <b>%d</b> год',
	'month'      => 'Архив за: <b>%s</b>',
	'day'        => 'Архив за <b>%1$s число</b>, %2$s', // Архив за 5 число, среда
	'attachment' => 'Медиа: %s',
	'tag'        => 'Записи по метке: <b>%s</b>',
	'tax_tag'    => '%1$s из "%2$s" по тегу: <b>%3$s</b>',
	// tax_tag выведет: 'тип_записи из "название_таксы" по тегу: имя_термина'.
	// Если нужны отдельные холдеры, например только имя термина, пишем так: 'записи по тегу: %3$s'
);
меню

Фильтры (хуки)

// Позволяет отключить вывод крошек
if( apply_filters( 'disable_kama_breadcrumbs', null ) ) return;

// фильтрует строки локализации - $l10n - это массив
$l10n = apply_filters( 'kama_breadcrumbs_l10n', $l10n );

// фильтрует параметры - $args - это массив
$args = apply_filters( 'kama_breadcrumbs_args', $args );

// вывод: все виды записей с терминами, или термины
$term = apply_filters( 'kama_breadcrumbs_term', $term );

// возможность изменить элементы крошек
$elms = apply_filters_ref_array( 'kama_breadcrumbs_filter_elements', [ $elms, $this, $ptype ] );

// возможность изменить элементы крошек,
// после того, как все элементы были собраны в одномерный (плоский) массив
$flat_elms = apply_filters_ref_array( 'kama_breadcrumbs_filter_flat_elements', [ $flat_elms, $this, $ptype ] );

// фильтрует готовый HTML код крошек
return apply_filters( 'kama_breadcrumbs', sprintf( $arg->wrappatt, $out ), $arg->sep, $loc, $arg );
меню

Примеры

Изменение параметров по умолчанию

// установим параметры по умолчанию
add_filter( 'kama_breadcrumbs_args', function($args){
	return [
		'sep'             => ' › ', // ▸
		'on_front_page'   => 1,
		'show_post_title' => 0,
		//'show_term_title' => 0,
		//'last_sep'      => 0,
		'markup'          =>'RDFa',
		// или своя маркировка
		'markup' => [
			'wrappatt'  => '<div class="kama_breadcrumbs">%s</div>',
			'linkpatt'  => '<li><a href="%s">%s</a></li>',
			'titlepatt' => '<li class="active">%s</li>',
			'seppatt'   => '<span class="kb_sep">%s</span>',
		],
		'priority_tax' => [ 'category', 'tplcat', 'wpfunccat' ],
	]
	+ $args;
} );

Отключение крошек

Допустим нам нужно отключить вывод хлебных крошек на странице /profile. Сделать это можно через фильтр disable_kama_breadcrumbs:

add_filter( 'disable_kama_breadcrumbs', function(){
	return is_page('profile');
} );

Или если крошки у вас выводятся через хук echo_kama_breadcrumbs, то можно просто убрать все прикрепленные к нему функции:

add_action( 'wp', function(){
	if( is_page('profile') )
		remove_all_filters( 'echo_kama_breadcrumbs' );
} );

Локализация (строки перевода)

// изменим строки перевода
add_filter( 'kama_breadcrumbs_l10n', function($l10n){
	return [
		'home'    => '<i style="display:none;">Главная</i><span class="dashicons dashicons-admin-home"></span>',
		'tax_tag' => 'По метке: <b>%3$s</b>',
	]
	+ $l10n;
} );

Добавление своих элементов в крошки

Коды ниже нужно вставлять в файл темы functions.php.

Для создания элементов крошек в примерах ниже используются методы (они автоматически создают текущую микроразметку schema.org):

// для любого элемента крошек (кроме последнего)
$class->makelink( $url, $title )

// для последнего элемента крошек (ссылка будет выводится, только если нужна)
$class->maketitle( $url, $title )

#1 Добавим элементы крошек после ссылки на главную

// добавить свои ссылки в крошки
add_filter( 'kama_breadcrumbs_filter_elements', 'breadcrumbs_add_elements', 10, 3 );
function breadcrumbs_add_elements( $elms, $class, $ptype ){
	global $post;

	// смотрим какие элементы есть в массиве и добавляем куда и что нужно
	// print_r( $elms );

	// добавим 2 ссылки (2 элемента) после главной, если запись находится в рубрике mycat
	if( is_single() && has_category( 'mycat', $post ) ){

		$elms['home'][] = [
			$class->makelink( '/inventory', 'Инвентарь' ),
			$class->makelink( '/other', 'Другое' )
		];
	}

	return $elms;
}

#2 Пример для woocommerce

add_filter( 'kama_breadcrumbs_filter_elements', 'kama_breadcrumbs_add_elements', 10, 3 );
function kama_breadcrumbs_add_elements( $elms, $class, $ptype ){

	if ( is_woocommerce() ) {

		$page = get_post( wc_get_page_id( 'shop' ) );

		if ( is_shop() && ! is_paged() ) {
			$elms['home_after'] = $class->maketitle( get_the_permalink( $page ), get_the_title( $page ) );
		}
		else {
			$elms['home_after'] = $class->makelink( get_permalink( $page ), get_the_title( $page ) );
		}
	}

	return $elms;
}

#3 Варианты добавить «крошку» после главной:

add_filter( 'kama_breadcrumbs_filter_elements', 'kama_breadcrumbs_add_elements', 10, 3 );
function kama_breadcrumbs_add_elements( $elms, $class, $ptype ){

	// можно так:
	$elms['home_after'][] = $class->makelink( 'http://example.com/functions', 'Функции' );

	// или сотрем имеющиеся элементы и добавим свой:
	$elms['home_after'] = $class->makelink( 'http://example.com/functions', 'Функции' );

	// или добавим сразу несколько ссылок:
	$elms['home_after'][] = [
		$class->makelink('http://example.com/functions', 'Функции' ),
		$class->makelink('http://example.com/hooks', 'Хуки' ),
	];

	// или заменим на сразу несколько своих ссылок (удалим текущее значение home_after):
	$elms['home_after'] = [
		$class->makelink('http://example.com/functions', 'Функции' ),
		$class->makelink('http://example.com/hooks', 'Хуки' ),
	];

	return $elms;
}
меню

Массив $elms

Как выглядит массив $elms передаваемый в хук (элементы будут отличаться на разных страницах сайта):

Array(

	[home] =>   <span property="itemListElement" typeof="ListItem">
					<a href="http://example.com" property="item" typeof="WebPage"><span property="name"><i style="display:none;">Главная</i><span class="dashicons dashicons-admin-home"></span></span></a>
					<meta property="position" content="ORDERNUM" />
				</span>

	[home_after] => Array(
			[0] =>  <span property="itemListElement" typeof="ListItem">
						<a href="/functions" property="item" typeof="WebPage"><span property="name">Функции</span></a>
						<meta property="position" content="ORDERNUM" />
					</span>
			[1] =>  <span property="itemListElement" typeof="ListItem">
						<a href="/functions/template_tags" property="item" typeof="WebPage"><span property="name">Теги шаблона</span></a>
						<meta property="position" content="ORDERNUM" />
					</span>
	)

	[single] => Array(
			[wpfunccat__tax_crumbs] => Array(
					[0] =>  <span property="itemListElement" typeof="ListItem">
								<a href="http://example.com/function-cat/miscellaneous" property="item" typeof="WebPage"><span property="name">Прочие функции</span></a>
								<meta property="position" content="ORDERNUM" />
							</span>
					[1] =>  <span property="itemListElement" typeof="ListItem">
								<a href="http://example.com/function-cat/zaschita-bloga" property="item" typeof="WebPage"><span property="name">Защита</span></a>
								<meta property="position" content="ORDERNUM" />
							</span>
			)

			[title] =>  <span class="kb_title" property="itemListElement" typeof="ListItem">
								<span property="name">form_option</span>
								<meta property="position" content="ORDERNUM">
							</span>
	)

)

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

Названия ключей массива $elms. Например, home_after, нужны, чтобы проще было «сунуть» свою ссылку в нужное место, на работу кода они не влияют. Т.е. при добавлении своих элементов, ключ массива можно указать любой или вообще не указывать.

меню

Изменение классов под БЭМ верстку

## параметры по умолчанию — kama_breadcrumbs
add_filter( 'kama_breadcrumbs_args', function( $args )
{
	$base       = isset($args['bem']['base'])   ? $args['bem']['base']  : 'breadcrumbs';
	$mods       = isset($args['bem']['mods'])   ? $args['bem']['mods']  : [];

	$inner      = $base . '__inner';
	$item       = $base . '__item';
	$title      = $base . '__title';
	$link       = $base . '__link';
	$sep        = $base . '__sep';

	$base_mod   = isset($mods['base'])          ? ' ' . $base . '--' . $mods['base']    : '';
	$inner_mod  = isset($mods['inner'])         ? ' ' . $inner . '--' . $mods['inner']  : '';
	$item_mod   = isset($mods['item'])          ? ' ' . $item . '--' . $mods['item']    : '';
	$title_mod  = isset($mods['title'])         ? ' ' . $title . '--' . $mods['title']  : '';
	$link_mod   = isset($mods['link'])          ? ' ' . $link . '--' . $mods['link']    : '';
	$sep_mod    = isset($mods['sep'])           ? ' ' . $sep . '--' . $mods['sep']      : '';

	return array_merge( $args, [
		'sep'           => ' — ',
		'sep_class'     => $sep . $sep_mod,

		// своя разметка
		'markup'    =>
		[
			'wrappatt'  => '
				<div class="' . $base . $base_mod . '" itemscope itemtype="https://schema.org/BreadcrumbList">
					<div class="' . $inner . $inner_mod . '">%s</div>
				</div>',

			'linkpatt'  => '
				<span class="' . $item . $item_mod . '" itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
					<a href="%s" class="' . $link . $link_mod . '">%s</a>
					<meta itemprop="item" content="PERMALINK" />
					<meta itemprop="name" content="NAME" />
					<meta itemprop="position" content="ORDERNUM" />
				</span>',

			'titlepatt' => '
				<span class="' . $title . $title_mod . '" itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem">
					%s
					<meta itemprop="item" content="PERMALINK" />
					<meta itemprop="name" content="NAME" />
					<meta itemprop="position" content="ORDERNUM" />
				</span>
			',
		],
	] );
} );

## пример использования в шаблоне:

$bc_args = [
	'bem'   => [
		'mods'  => [
			'inner'     => 'grey_class',
			'link'      => 'red_color',
		],
	]
];

echo kama_breadcrumbs( $bc_args );

/**
 * Выведет:
 * - у враппера class="breadcrumbs__inner breadcrumbs__inner--grey_class"
 * - у ссылок class="breadcrumbs__link breadcrumbs__link--red_color"
 */
меню

Еще примеры

Смотрите в вопросе.

95 комментов
Полезные 7 Вопросы 2 Все
    Войти