add_theme_support() WP 2.9

Позволяет темам или плагинам регистрировать поддержку новых возможностей в WordPress (поддержка миниатюр, форматов записей и т.д.).

Если функция вызывается из темы, то она должна находится в файле functions.php. Также, её можно вызвать из плагина, подключив к событию (хуку): after_setup_theme.

Хуков нет.

Возвращает

null. Функция ничего не возвращает.

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

add_theme_support( $feature, $formats );

$feature(строка) (обязательный)

Название добавляемой возможности.

Список всех новых возможностей:

• post-formats
• post-thumbnails
• custom-background
• custom-header
• automatic-feed-links
• html5
• title-tag
• custom-logo (с WP 4.5)
• customize-selective-refresh-widgets (с WP 4.5)
• starter-content (с WP 4.7)
• admin-bar

Следующие возможности нужны только для чтения и должны быть использованы в функции current_theme_supports():

• widgets - используйте register_sidebar() или register_sidebars() взамен.
• menus - используйте register_nav_menu() или register_nav_menus() взамен.
• editor-style - используйте add_editor_style() взамен.

С WP 5.0 были добавлены возможности, которые используются как опции Гутенберга (эти опции также можно изменить через фильтр block_editor_settings):

• responsive-embeds
• align-wide
• dark-editor-style
• disable-custom-colors
• disable-custom-font-sizes
• editor-color-pallete
• editor-font-sizes
• editor-styles
• wp-block-styles

По умолчанию: нет

$formats(массив)

Дополнительные параметры. Для каждой возможности свои. У форматов постов тут указываем форматы, у миниатюр типы постов, где они будут работать и т.д. (см. ниже).
По умолчанию: нет

Новые возможности

post-formats

Позволяет указывать формат посту. Функция была добавлена в версии 3.1.

Чтобы указать определенные форматы используйте второй аргумент функции:

add_theme_support( 'post-formats', array( 'aside', 'gallery' ) );

Чтобы проверить пост на формат quote, используйте такой код в файлах single.php, page.php:

if ( has_post_format( 'quote' ) ) {
	echo 'Это quote.';
}

post-thumbnails

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

add_theme_support( 'post-thumbnails' );
add_theme_support( 'post-thumbnails', array( 'post' ) );          // Только для post
add_theme_support( 'post-thumbnails', array( 'page' ) );          // Только для page
add_theme_support( 'post-thumbnails', array( 'post', 'movie' ) ); // Для post и movie типов

Эту возможность нужно добавлять до хука init. Это значит, что функция должна быть расположена в файле темы functions.php или через хук after_setup_theme. Для произвольных типов записей также можно выводить блок миниатюр смотрите register_post_type().

Чтобы вывести миниатюру в файле темы (index.php или single.php и т.д.) используем функцию the_post_thumbnail():

the_post_thumbnail();

Чтобы проверить, если ли у поста миниатюра, перед тем как её выводить, используем has_post_thumbnail():

if ( has_post_thumbnail() ) {
	the_post_thumbnail();
}

custom-background

Добавляет возможность изменять фон из админки. Доступна с версии 3.4.

add_theme_support( 'custom-background' );

Также, можно указать параметры во втором аргументе:

$defaults = array(
	'default-color'          => '',
	'default-image'          => '',
	'wp-head-callback'       => '_custom_background_cb',
	'admin-head-callback'    => '',
	'admin-preview-callback' => ''
);
add_theme_support( 'custom-background', $defaults );

Получим в head части сайта:

<style type="text/css" id="custom-background-css">
body.custom-background { background-color: #bdd96e; }
</style>

Совместимость с ранними версиями

Чтобы произвольный фон был совместим в ранними версиями (ниже 3.4), можно использовать такое условие:

global $wp_version;
if ( version_compare( $wp_version, '3.4', '>=' ) ) 
	add_theme_support( 'custom-background' ); 
else
	add_custom_background( $args );

custom-header

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

add_theme_support( 'custom-header' );

Также, можно указать дополнительные параметры:

add_theme_support( 'custom-header', array(
	'default-image'          => '',
	'random-default'         => false,
	'width'                  => 0,
	'height'                 => 0,
	'flex-height'            => false,
	'flex-width'             => false,
	'default-text-color'     => '', // вызывается функций get_header_textcolor()
	'header-text'            => true,
	'uploads'                => true,
	'wp-head-callback'       => '',
	'admin-head-callback'    => '',
	'admin-preview-callback' => '',
	'video'                  => false, // с 4.7
	'video-active-callback'  => 'is_front_page', // с 4.7
) );

Видео в заголовке (шапке WordPress)

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

Поддержка видео включается так:

add_theme_support( 'custom-header', array(
	'video' => true,
) );

При активации этой возможности в кастомайзере (настройках темы) появится блок где можно загрузить и установить.

Все функции для вывода картинки и видео заголовка:

• get_header_image - Получает УРЛ картинки шапки (заголовка). Для вывода на экран есть обертка header_image().

• get_header_image_tag() - Получает <img> тег картинки заголовка. Добавляет туда атрибуты srcset и srcset. Для вывода на экран есть обертка the_header_image_tag().

• has_header_video() – Проверяет было ли установлено видео в кастомайзере.

• is_header_video_active() – Проверяет должно ли показываться видео для текущей страницы запроса во фронте.

• get_header_video_url() – Получает URL видео для шапки. Может быть локальной или внешней ссылкой на видео.

• the_header_video_url() – Выводит URL видео для шапки.

• has_custom_header() – Проверяет установлена ли картинка для шапки темы, или установлено ли видео и доступно для показа на текущей странице запроса.

• get_custom_header_markup() – Получает HTML код для отображения картинки заголовка (не включает видео).

• the_custom_header_markup() – Выводит HTML код для отображения картинки заголовка и подключает JS код для обработки видео заголовка, если оно доступно для текущего запроса.

Примеры

Для начала в header.php где находится картинка шапки у нас должен быть такой код, чтобы нижеследующие настройки работали:

<img src="<?php header_image(); ?>" height="<?php echo get_custom_header()->height; ?>" width="<?php echo get_custom_header()->width; ?>" alt="" />

#1. Установим картинку для шапки размером: 980px на 60px:

add_theme_support( 'custom-header', array(
	'width'         => 980,
	'height'        => 60,
	'default-image' => get_template_directory_uri() . '/images/header.jpg',
) );

#2. Установим картинку по умолчанию и дадим возможность изменять её пользователям ('uploads'=> true):

add_theme_support( 'custom-header', array(
	'width'         => 980,
	'height'        => 60,
	'default-image' => get_template_directory_uri() . '/images/header.jpg',
	'uploads'       => true,
) );

#3. Дадим возможность пользователям изменять размеры картинки ('flex-width', 'flex-height'):

add_theme_support( 'custom-header', array(
	'flex-width'    => true,
	'width'         => 980,
	'flex-height'    => true,
	'height'        => 200,
	'default-image' => get_template_directory_uri() . '/images/header.jpg',
) );

#4. Установим цвет текста для header: параметр default-text-color

Этот пример показывает, как вызвать цвет изменяющийся в настройках темы. Там где нужно примерить указанный в настройках темы цвет, нужно использовать функцию: get_header_textcolor() так:

style="<?php echo sprintf( 'color: #%s;', get_header_textcolor() ); ?>"

automatic-feed-links

Эта возможность добавляет ссылки на RSS фиды постов и комментариев в head часть HTML документа. Работает с версии 3.0. Нужно использовать вместо устарелой функции automatic_feed_links().

add_theme_support( 'automatic-feed-links' );

Добавит в head часть подобные ссылки:

<link rel="alternate" type="application/rss+xml" title="Пробный сайт - Feed" href="http://wptest.ru/feed/" />
<link rel="alternate" type="application/rss+xml" title="Пробный сайт - Comments Feed" href="http://wptest.ru/comments/feed/" />

html5

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

add_theme_support( 'html5', array( 'comment-list', 'comment-form', 'search-form', 'gallery', 'caption' ) );

Если второй параметр оставить пустым, то будут использован следующий массив: array( 'comment-list', 'comment-form', 'search-form' ).

title-tag

С версии 4.1. Эта функция позволит плагинам и темам изменять метатег <title>. Эта возможность будет использоваться вместо wp_title().

add_theme_support( 'title-tag' );

Если активировать эту опцию для темы, то в теме не нужно устанавливать метатег <title><?php wp_title() ?></title> - он будет подключен автоматически через хук wp_head. Вот код, который отвечает за подключение (из файла /wp-includes/general-template.php).

function _wp_render_title_tag() {
	if ( ! current_theme_supports( 'title-tag' ) ) {
		return;
	}

	echo '<title>' . wp_get_document_title() . '</title>' . "\n";
}

Кроме того, с включением этой опции, функция wp_title будет добавлять к заголовкам название сайта в конце, а на главной странице описание сайта в конце заголовка (кусок кода функции wp_title()):

...
	if ( current_theme_supports( 'title-tag' ) && ! is_feed() ) {
		$title .= get_bloginfo( 'name', 'display' );

		$site_description = get_bloginfo( 'description', 'display' );
		if ( $site_description && ( is_home() || is_front_page() ) ) {
			$title .= " $sep $site_description";
		}

		if ( ( $paged >= 2 || $page >= 2 ) && ! is_404() ) {
			$title .= " $sep " . sprintf( __( 'Page %s' ), max( $paged, $page ) );
		}
	}
...

Отключение 'title-tag'

Чтобы отключить эту возможность, отключите фильтр:

add_action('wp_head', function(){ remove_theme_support( 'title-tag' ); }, 0);

// или 
add_action('wp_head', function(){ remove_action( 'wp_head', '_wp_render_title_tag', 1 ); }, 0);

custom-logo (с WP 4.5)

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

После установки такого лого, его можно получить и вывести в теме с помощью функции: get_custom_logo() или the_custom_logo().

Чтобы проверить наличие такого логотипа используйте has_custom_logo().

customize-selective-refresh-widgets (с WP 4.5)

Включает поддержку «Selective Refresh» (выборочное обновление) для виджетов в кастомайзере. Что такое «Selective Refresh» смотрите в этом демо ролике и читайте (англ.) тут и тут.

add_theme_support( 'customize-selective-refresh-widgets' );

starter-content (с WP 4.7)

Расширяет начальный контент (контент который устанавливается, при установке WordPress или темы).

По умолчанию в WP есть свой начальный контент, но его можно дополнить указав в этой возможности все данные контента. Какие данные можно указать и в каком формате это делать, смотрите в коде функции get_theme_starter_content()

Шаблон использования:

add_theme_support( 'starter-content', array(
	'options'     => '', // опции сайта
	'theme_mods'  => '', // опции темы
	'widgets'     => '', // данные виждетов
	'nav_menus'   => '', // данные меню
	'attachments' => '', // данные вложений
	'posts'       => '', // массив массивов: ID => array('post_type' => '', 'post_title' => '', 'post_excerpt' => '', 'post_name' => '', 'post_content' => '', 'menu_order' => '', 'comment_status' => '', 'thumbnail' => '', 'template' => '')
) );

Пример установки начального контента (взято из функции ядра):

$starter_content = array(
	'widgets' => array(
		'text_business_info' => array( 'text', array(
			'title' => _x( 'Find Us', 'Theme starter content' ),
			'text' => join( '', array(
				'<p><strong>' . _x( 'Address', 'Theme starter content' ) . '</strong><br />',
				_x( '123 Main Street', 'Theme starter content' ) . '<br />' . _x( 'New York, NY 10001', 'Theme starter content' ) . '</p>',
				'<p><strong>' . _x( 'Hours', 'Theme starter content' ) . '</strong><br />',
				_x( 'Monday—Friday: 9:00AM–5:00PM', 'Theme starter content' ) . '<br />' . _x( 'Saturday & Sunday: 11:00AM–3:00PM', 'Theme starter content' ) . '</p>'
			) ),
		) ),
		'text_about' => array( 'text', array(
			'title' => _x( 'About This Site', 'Theme starter content' ),
			'text' => _x( 'This may be a good place to introduce yourself and your site or include some credits.', 'Theme starter content' ),
		) ),
		'archives' => array( 'archives', array(
			'title' => _x( 'Archives', 'Theme starter content' ),
		) ),
		'calendar' => array( 'calendar', array(
			'title' => _x( 'Calendar', 'Theme starter content' ),
		) ),
		'categories' => array( 'categories', array(
			'title' => _x( 'Categories', 'Theme starter content' ),
		) ),
	),
	'nav_menus' => array(
		'page_home' => array(
			'type' => 'post_type',
			'object' => 'page',
			'object_id' => '{{home}}',
		),
		'page_about' => array(
			'type' => 'post_type',
			'object' => 'page',
			'object_id' => '{{about}}',
		),

		'link_email' => array(
			'title' => _x( 'Email', 'Theme starter content' ),
			'url' => 'mailto:wordpress@example.com',
		),
		'link_facebook' => array(
			'title' => _x( 'Facebook', 'Theme starter content' ),
			'url' => 'https://www.facebook.com/wordpress',
		),
	),
	'posts' => array(
		'home' => array(
			'post_type' => 'page',
			'post_title' => _x( 'Home', 'Theme starter content' ),
			'post_content' => _x( 'Welcome to your site! This is your homepage, which is what most visitors will see when they come to your site for the first time.', 'Theme starter content' ),
		),
		'about' => array(
			'post_type' => 'page',
			'post_title' => _x( 'About', 'Theme starter content' ),
			'post_content' => _x( 'You might be an artist who would like to introduce yourself and your work here or maybe you’re a business with a mission to describe.', 'Theme starter content' ),
		),
		'contact' => array(
			'post_type' => 'page',
			'post_title' => _x( 'Contact', 'Theme starter content' ),
			'post_content' => _x( 'This is a page with some basic contact information, such as an address and phone number. You might also try a plugin to add a contact form.', 'Theme starter content' ),
		),
		'blog' => array(
			'post_type' => 'page',
			'post_title' => _x( 'Blog', 'Theme starter content' ),
		),
		'news' => array(
			'post_type' => 'page',
			'post_title' => _x( 'News', 'Theme starter content' ),
		),
		'homepage-section' => array(
			'post_type' => 'page',
			'post_title' => _x( 'A homepage section', 'Theme starter content' ),
			'post_content' => _x( 'This is an example of a homepage section. Homepage sections can be any page other than the homepage itself, including the page that shows your latest blog posts.', 'Theme starter content' ),
		),
	),
);
add_theme_support( 'starter-content', $starter_content );

admin-bar

Эта возможность включена по умолчанию и отключается по-другому. Но через get_theme_support( 'admin-bar' ); WP получает название колбек функции _admin_bar_bump_cb(), она выводит css стили для отступа вверху html для админ бара.

Чтобы убрать, отключить этот отступ используйте такой код:

add_theme_support( 'admin-bar', array( 'callback'=>'__return_false' ) );

Код add_theme_support: wp-includes/theme.php ^{VER 5.0}

<?php
function add_theme_support( $feature ) {
	global $_wp_theme_features;

	if ( func_num_args() == 1 )
		$args = true;
	else
		$args = array_slice( func_get_args(), 1 );

	switch ( $feature ) {
		case 'post-thumbnails':
			// All post types are already supported.
			if ( true === get_theme_support( 'post-thumbnails' ) ) {
				return;
			}

			/*
			 * Merge post types with any that already declared their support
			 * for post thumbnails.
			 */
			if ( is_array( $args[0] ) && isset( $_wp_theme_features['post-thumbnails'] ) ) {
				$args[0] = array_unique( array_merge( $_wp_theme_features['post-thumbnails'][0], $args[0] ) );
			}

			break;

		case 'post-formats' :
			if ( is_array( $args[0] ) ) {
				$post_formats = get_post_format_slugs();
				unset( $post_formats['standard'] );

				$args[0] = array_intersect( $args[0], array_keys( $post_formats ) );
			}
			break;

		case 'html5' :
			// You can't just pass 'html5', you need to pass an array of types.
			if ( empty( $args[0] ) ) {
				// Build an array of types for back-compat.
				$args = array( 0 => array( 'comment-list', 'comment-form', 'search-form' ) );
			} elseif ( ! is_array( $args[0] ) ) {
				_doing_it_wrong( "add_theme_support( 'html5' )", __( 'You need to pass an array of types.' ), '3.6.1' );
				return false;
			}

			// Calling 'html5' again merges, rather than overwrites.
			if ( isset( $_wp_theme_features['html5'] ) )
				$args[0] = array_merge( $_wp_theme_features['html5'][0], $args[0] );
			break;

		case 'custom-logo':
			if ( ! is_array( $args ) ) {
				$args = array( 0 => array() );
			}
			$defaults = array(
				'width'       => null,
				'height'      => null,
				'flex-width'  => false,
				'flex-height' => false,
				'header-text' => '',
			);
			$args[0] = wp_parse_args( array_intersect_key( $args[0], $defaults ), $defaults );

			// Allow full flexibility if no size is specified.
			if ( is_null( $args[0]['width'] ) && is_null( $args[0]['height'] ) ) {
				$args[0]['flex-width']  = true;
				$args[0]['flex-height'] = true;
			}
			break;

		case 'custom-header-uploads' :
			return add_theme_support( 'custom-header', array( 'uploads' => true ) );

		case 'custom-header' :
			if ( ! is_array( $args ) )
				$args = array( 0 => array() );

			$defaults = array(
				'default-image' => '',
				'random-default' => false,
				'width' => 0,
				'height' => 0,
				'flex-height' => false,
				'flex-width' => false,
				'default-text-color' => '',
				'header-text' => true,
				'uploads' => true,
				'wp-head-callback' => '',
				'admin-head-callback' => '',
				'admin-preview-callback' => '',
				'video' => false,
				'video-active-callback' => 'is_front_page',
			);

			$jit = isset( $args[0]['__jit'] );
			unset( $args[0]['__jit'] );

			// Merge in data from previous add_theme_support() calls.
			// The first value registered wins. (A child theme is set up first.)
			if ( isset( $_wp_theme_features['custom-header'] ) )
				$args[0] = wp_parse_args( $_wp_theme_features['custom-header'][0], $args[0] );

			// Load in the defaults at the end, as we need to insure first one wins.
			// This will cause all constants to be defined, as each arg will then be set to the default.
			if ( $jit )
				$args[0] = wp_parse_args( $args[0], $defaults );

			// If a constant was defined, use that value. Otherwise, define the constant to ensure
			// the constant is always accurate (and is not defined later,  overriding our value).
			// As stated above, the first value wins.
			// Once we get to wp_loaded (just-in-time), define any constants we haven't already.
			// Constants are lame. Don't reference them. This is just for backward compatibility.

			if ( defined( 'NO_HEADER_TEXT' ) )
				$args[0]['header-text'] = ! NO_HEADER_TEXT;
			elseif ( isset( $args[0]['header-text'] ) )
				define( 'NO_HEADER_TEXT', empty( $args[0]['header-text'] ) );

			if ( defined( 'HEADER_IMAGE_WIDTH' ) )
				$args[0]['width'] = (int) HEADER_IMAGE_WIDTH;
			elseif ( isset( $args[0]['width'] ) )
				define( 'HEADER_IMAGE_WIDTH', (int) $args[0]['width'] );

			if ( defined( 'HEADER_IMAGE_HEIGHT' ) )
				$args[0]['height'] = (int) HEADER_IMAGE_HEIGHT;
			elseif ( isset( $args[0]['height'] ) )
				define( 'HEADER_IMAGE_HEIGHT', (int) $args[0]['height'] );

			if ( defined( 'HEADER_TEXTCOLOR' ) )
				$args[0]['default-text-color'] = HEADER_TEXTCOLOR;
			elseif ( isset( $args[0]['default-text-color'] ) )
				define( 'HEADER_TEXTCOLOR', $args[0]['default-text-color'] );

			if ( defined( 'HEADER_IMAGE' ) )
				$args[0]['default-image'] = HEADER_IMAGE;
			elseif ( isset( $args[0]['default-image'] ) )
				define( 'HEADER_IMAGE', $args[0]['default-image'] );

			if ( $jit && ! empty( $args[0]['default-image'] ) )
				$args[0]['random-default'] = false;

			// If headers are supported, and we still don't have a defined width or height,
			// we have implicit flex sizes.
			if ( $jit ) {
				if ( empty( $args[0]['width'] ) && empty( $args[0]['flex-width'] ) )
					$args[0]['flex-width'] = true;
				if ( empty( $args[0]['height'] ) && empty( $args[0]['flex-height'] ) )
					$args[0]['flex-height'] = true;
			}

			break;

		case 'custom-background' :
			if ( ! is_array( $args ) )
				$args = array( 0 => array() );

			$defaults = array(
				'default-image'          => '',
				'default-preset'         => 'default',
				'default-position-x'     => 'left',
				'default-position-y'     => 'top',
				'default-size'           => 'auto',
				'default-repeat'         => 'repeat',
				'default-attachment'     => 'scroll',
				'default-color'          => '',
				'wp-head-callback'       => '_custom_background_cb',
				'admin-head-callback'    => '',
				'admin-preview-callback' => '',
			);

			$jit = isset( $args[0]['__jit'] );
			unset( $args[0]['__jit'] );

			// Merge in data from previous add_theme_support() calls. The first value registered wins.
			if ( isset( $_wp_theme_features['custom-background'] ) )
				$args[0] = wp_parse_args( $_wp_theme_features['custom-background'][0], $args[0] );

			if ( $jit )
				$args[0] = wp_parse_args( $args[0], $defaults );

			if ( defined( 'BACKGROUND_COLOR' ) )
				$args[0]['default-color'] = BACKGROUND_COLOR;
			elseif ( isset( $args[0]['default-color'] ) || $jit )
				define( 'BACKGROUND_COLOR', $args[0]['default-color'] );

			if ( defined( 'BACKGROUND_IMAGE' ) )
				$args[0]['default-image'] = BACKGROUND_IMAGE;
			elseif ( isset( $args[0]['default-image'] ) || $jit )
				define( 'BACKGROUND_IMAGE', $args[0]['default-image'] );

			break;

		// Ensure that 'title-tag' is accessible in the admin.
		case 'title-tag' :
			// Can be called in functions.php but must happen before wp_loaded, i.e. not in header.php.
			if ( did_action( 'wp_loaded' ) ) {
				/* translators: 1: Theme support 2: hook name */
				_doing_it_wrong( "add_theme_support( 'title-tag' )", sprintf( __( 'Theme support for %1$s should be registered before the %2$s hook.' ),
					'<code>title-tag</code>', '<code>wp_loaded</code>' ), '4.1.0' );

				return false;
			}
	}

	$_wp_theme_features[ $feature ] = $args;
}

Cвязанные функции

Из метки: Расширения WP (доп возможности регистрация)

Еще из метки: theme_support

Еще из раздела: Другие функции темы