WordPress как на ладони
Kama и Jackky4.4 года назад81

Kama Breadcrumbs

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

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

Оглавление:

Вывод крошек в теме (Использование)

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

<?php do_action( 'echo_kama_breadcrumbs' ) ?>

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

<?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' ],
];

$l10n = [
	'tag' => 'Метка: <b>%s</b>',
];

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

Когда нужно получить HTML крошек (не выводить на экран), используйте код:

$breadcrumbs = kama_breadcrumbs( $args, $l10n );

// теперь выводим там где нужно
echo $breadcrumbs;

Параметры $args

Настройки вывода крошек указываются в виде массива, в параметре $args. Возможные элементы массива:

sep(строка)
Разделитель. Можно указать вместе с HTML оберткой: <span> » </span>.
По умолчанию: ' » '
on_front_page(true/false)
Выводить крошки на главной странице.
По умолчанию: true
show_post_title(true/false)
Показывать ли название записи в конце (последний элемент). Для записей, страниц, вложений.
По умолчанию: true
show_term_title(true/false)
Показывать ли название элемента таксономии в конце (последний элемент). Для меток, рубрик и других такс.
По умолчанию: true
last_sep(true/false)
показывать последний разделитель, когда заголовок в конце не отображается.
По умолчанию: true
nofollow(true/false)
Добавлять rel=nofollow к ссылкам?
По умолчанию: false
wrap_class(строка)
CSS класс для главного div.
По умолчанию: 'kama_breadcrumbs'
link_class(строка)
CSS класс для элемента крошек a.
По умолчанию: 'kb_link'
title_class(строка)
CSS класс заголовка элемента.
По умолчанию: 'kb_title'
sep_class(строка)
CSS класс разделителя.
По умолчанию: 'kb_sep'
priority_tax(массив)

Приоритетные таксономии, нужно когда запись находится в нескольких таксономиях: 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(string/array)

Микроразметка. Может быть:

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

'markup' => [
	'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'

JSON_LD(true/false)
Следует ли добавлять микроразметку JSON-LD в HTML.
По умолчанию: true
use_the_title_filter(true/false)
Использовать ли фильтр the_title для заголовков записей.
По умолчанию: false

Параметры $l10n

Параметры строк (локализации) указываются в параметре $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', 'my_kama_breadcrumbs_args' );

function my_kama_breadcrumbs_args( $args ){

	$my_args = [
		'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' ],
	];

	return $my_args + $args;
}

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

// изменим строки перевода
add_filter( 'kama_breadcrumbs_l10n', 'my_kama_breadcrumbs_l10n' );

function my_kama_breadcrumbs_l10n( $l10n ){

	$my_l10n = [
		'home'    => '<i style="display:none;">Главная</i><span class="dashicons dashicons-admin-home"></span>',
		'tax_tag' => 'По метке: <b>%3$s</b>',
	];

	return $my_l10n + $l10n;
}

Чтобы изменить имеющие УРЛ в крошках или добавить свои крошки нужно использовать фильтр kama_breadcrumbs_filter_elements.

Функция прикрепленная к этому фильтру получает массив и должна вернуть измененный массив. Этот массив - это и есть крошки, только в виде многомерного массива, он потом превратиться в HTML код крошек.

Для изменения или создания элементов крошек используются два метода (они автоматически создают указанную в параметре markup микроразметку):

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

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

Код нужно вставлять в файл темы functions.php или куда-либо еще, главное до того как будут выведены крошки.

#1 Пример изменения элементов крошек

Чтобы все было понятно пройдусь по шагам.

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

add_filter( 'kama_breadcrumbs_filter_elements', 'kama_breadcrumbs_filter_elms', 11, 3 );

function kama_breadcrumbs_filter_elms( $elms, $class, $ptype ){
	die( print_r( $elms ) );
}

В результате вы увидите такой массив (если мы на странице поста):

Array
(
	[home] => Array (
		[0] => Kama_Breadcrumbs_Elem Object ( ... )
	)

	[home_after] => Array( )

	[single] => Array (
		[category__tax_crumbs] => Array (
			[0] => Kama_Breadcrumbs_Elem Object( ... )

			[1] => Kama_Breadcrumbs_Elem Object( ... )
		)

	)
)

Как видим тут 3 крошки: home > category > category (орриентируйтесь по ключам массива - они не меняются и зависят от типа данных к которым относится конкретная крошка).

Теперь, например, нам нужно изменить ссылку на главную, для этого меняем крошку которая находится в ключе home:

add_filter( 'kama_breadcrumbs_filter_elements', function( $elms, $class, $ptype ){

	$elms['home'] = $class->makelink( 'https://site.com/path', 'Title' );

	return $elms; // не забываем вернуть

}, 11, 3 );

Или можно добавить еще одну крошку после ссылки на главную, для этого закидываем еще один элемент в массив с ключом home:

add_filter( 'kama_breadcrumbs_filter_elements', function( $elms, $class, $ptype ){

	$elms['home'][] = $class->makelink( 'https://site.com/path', 'Title' );

	return $elms; // не забываем вернуть

}, 11, 3 );

По такой системе можно удалять/изменять/добавлять крошки как угодно.

Важно отметить, что массив понимает любой уровень вложенности. Например, можно написать так и все будет работать:

add_filter( 'kama_breadcrumbs_filter_elements', function( $elms, $class, $ptype ){

	$elms['home'][] = [
		'foo' => [
			$class->makelink( 'https://site.com/path', 'Title' )
		]
	];

	return $elms; // не забываем вернуть

}, 11, 3 );

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

// добавить свои ссылки в крошки
add_filter( 'kama_breadcrumbs_filter_elements', 'breadcrumbs_add_elements', 10, 3 );

function breadcrumbs_add_elements( $elms, $class, $ptype ){
	global $post;

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

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

		// добавим 2 ссылки (2 элемента) после главной
		$elms['home'][] = [
			$class->makelink( '/inventory', 'Инвентарь' ),
			$class->makelink( '/other', 'Другое' )
		];
	}

	return $elms;
}

#3 Пример для 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;
}

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

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_filter_elements.

Так, чтобы например удалить ссылку Главная, нужно удалить элемент массива, точнее очистить его:

// изменяем крошки
add_filter( 'kama_breadcrumbs_filter_elements', 'breadcrumbs_change_elements', 10, 3 );

function breadcrumbs_change_elements( $elms, $class, $ptype ){
  global $post;

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

  // удалим ссылку на главную (очистим элемент home там лежит элемент "главная")
  $elms['home'] = [];

  return $elms;
}

Отключить крошки (по условию)

Допустим нам нужно отключить вывод хлебных крошек на странице /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' );
	}
} );

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

## параметры по умолчанию — 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"
 */

Еще примеры

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

До этого из: mast have (обязательный)
81 комментарий
Полезные 7 Все
    Войти