Document title in 4.4
WordPress 4.1 introduced a way for themes to support a new way of rendering the document title, letting Core handle its generation and output. The next step followed just recently (#31078), deprecating replacing it with a more comprehensive way to generate titles.wp_title()
and
UPDATE 12 November – wp_title has been reinstated until alternative usages have been identified and a path forward for them defined.
Plugin authors can now check for theme support and have a few new filters available that will allow them to change or replace the title in a reliable way:
'pre_get_document_title'
short-circuitswp_get_document_title()
if it returns anything other than an empty value.'document_title_separator'
filters the separator between title parts.'document_title_parts'
filters the parts that make up the document title, passed in an associative array.
This latest change makes the new API (almost) feature complete and theme authors are discouraged from using wp_title()
in the future. If it was decided to add a UI to let users choose the make up of their document title, or another improvement to how title generation works, we now have a forward compatible way to handle these things.
To upgrade themes from using wp_title()
to declaring theme support for core’s title-tag without breaking backwards compatibility with WordPress 4.0 and older, theme authors can check if the callback function exists and add a shiv in case it does not:
if ( ! function_exists( '_wp_render_title_tag' ) ) : function theme_slug_render_title() { ?> <title><?php wp_title( '-', true, 'right' ); ?></title> <?php } add_action( 'wp_head', 'theme_slug_render_title' ); endif;
Pippin Williamson 6:10 pm on October 20, 2015 Permalink | Log in to Reply
As much as I love this improvement, I really don’t think a deprecated notice should be thrown here. The sheer number of themes using wp_title() is overwhelming and it will be a support / maintenance nightmare.
WebMan Design | Oliver Juhas 6:24 pm on October 20, 2015 Permalink | Log in to Reply
I completely agree! This will be huge impact.
Konstantin Obenland 6:43 pm on October 20, 2015 Permalink | Log in to Reply
At the point of release, theme support will have been introduced a year earlier, with the WPTRT adding it as recommended from the start. Two default themes will have been shipped with it, and it’s used in over 300,000 themes derived from
_s
since November ’14. And as Justin pointed out, it will have been required for the theme repo for more than a quarter of that time.While legacy themes will obviously still use it, there has been quiet a bit of theme developer education around this. The current landscape of document titles is really not as bleak as some make it sound.
Chuck Reynolds 2:15 am on October 21, 2015 Permalink | Log in to Reply
I agree there will be a lot of questions but I also agree it’s time.
Coen Jacobs 10:08 am on October 22, 2015 Permalink | Log in to Reply
If we’d go by that reasoning, there would be never any change possible. Production environments need to have debug mode switched off, so no notices there. Second, this change has been coming for so long, themes that have been actively maintained have had the chance to introduce their own way to deal with the deprecation already.
Samuel Wood (Otto) 9:32 pm on October 23, 2015 Permalink | Log in to Reply
Like it or not, many live webhosts default to having the PHP display_errors flag enabled. Every time a new deprecated notice is added, sites all across the web break. Since this is going to affect themes, right on the front-page of the site and everywhere else, then that’s a lot of breakage. We cannot hope to upgrade all sites in time for this breaking change.
Suggestion: Make the deprecated notice system not quite so stupid. Yes, users need to know things. However, if display_errors is on, and it’s the front end of the site (or the login page), and WP_DEBUG is not turned on, then we should probably shut it off if a deprecated notice is thrown. Throwing a notice out on login breaks logins (by breaking cookies), and throwing one on the main site makes for “broken” sites in the eyes of users. And all for a notice that a function, which still likely works okay, may not work in the future.
I’m fine with the title change. But “deprecated” messages should not be so strong as to actually cause people to want to rollback WordPress versions.
Yes, BTW, I do realize that _deprecated_notice only triggers when WP_DEBUG is explicitly on. Still, sometimes it is through auto-installers or something else. We should have some better way of warning people than displaying these notices right on the front end of the site.
FolioVision 3:13 am on November 3, 2015 Permalink | Log in to Reply
We strongly agree here Samuel. While improving core structure is wonderful, transition should be gradual and over time. There’s no overwhelming benefit to breaking the web in this particular case. Gently gentlemen.
Justin Sainton 6:15 pm on October 20, 2015 Permalink | Log in to Reply
+1 to not throwing a notice. this will be basically _every_ theme.
Pippin Williamson 6:15 pm on October 20, 2015 Permalink | Log in to Reply
Including themes that are superbly built.
Simon Prosser 8:45 pm on October 20, 2015 Permalink | Log in to Reply
Notices are only displayed with WP_DEBUG on, whats the issue?
Sybre Waaijer 6:29 am on October 22, 2015 Permalink | Log in to Reply
The problem is that when a user wishes to turn it on to discover a nasty bug on a live site it will absolutely destroy the SEO value of the site if a search engine spider sees it.
It would be better to enqueue the deprecation notice within the footer or any other part other than the
However, it’s suffice to say that I’ve been working for a good 40 hours to compromise the wrongly used wp_title tag within the header without using buffer rewriting.
This update will force users to switch to a better theme, and it will also force theme developers to use the standards.
From there it will also save a lot of developers heaps of time So I’m pretty much all for the deprecation notice, wherever it actually may be.
You know what, keep the deprecation notice within the title 😀 Hurray for standards!
Justin Tadlock 6:22 pm on October 20, 2015 Permalink | Log in to Reply
I just wanted to note that WordPress.org themes are no longer encouraged to have the back-compat code. Title tag support is now required.
Aaron D. Campbell 6:49 pm on October 20, 2015 Permalink | Log in to Reply
There is a fine line to be walked between backward compatibility and pushing ahead into better things. I think this is one of those cases where we’re walking that line very well. Themes are encourage (or in the case of .org, required) to push ahead into the newer/better way, and any theme that uses the older way **still works as it did before**. The notice deprecated function notice is not only just a notice (not an error or warning), but it’s only triggered by default if WP_DEBUG is on.
Drew Jaynes 7:12 pm on October 20, 2015 Permalink | Log in to Reply
I see an inevitable question popping up: “What do I use instead?”
The simple answer is nothing.
If you add
add_theme_support( ‘title-tag’ );
to yourafter_setup_theme
callback, the title will just be handled. An internal core function adds it via thewp_head
hook. No need to add anything to your theme’s header.php file, just remove the legacywp_title()
call.The ‘title-tag’ theme support was (as mentioned) added to core a year ago.
Also, as @obenland alluded, there are several filters available for customizing the output:
Jose Castaneda 8:47 pm on October 20, 2015 Permalink | Log in to Reply
Sweet! One less thing for theme authors to maintain!
Ross Wintle 2:48 pm on October 22, 2015 Permalink | Log in to Reply
So the simple answer is actually: “add `add_theme_support(‘title-tag’);` to your `after_setup_theme` callback! 😉
Ross Wintle 2:49 pm on October 22, 2015 Permalink | Log in to Reply
Oh bother – that was a reply to @drewapicture above. Why is the reply button at the top of comments here?! You can tell I don’t comment on make blog very often.
catchmyfame 9:14 pm on October 20, 2015 Permalink | Log in to Reply
Should https://codex.wordpress.org/Theme_Development#Template_File_Checklist be updated to *not* encourage the use of wp_title()? I didn’t see the equivalent checklist at https://developer.wordpress.org/themes/
simonrcodrington 9:51 pm on October 20, 2015 Permalink | Log in to Reply
I’m all for moving forward with better things. As long as this is a developers notice when debugging is turned on and not an admin level notice that bothers users, I’m all for it.
Ahmad Awais 8:44 am on October 22, 2015 Permalink | Log in to Reply
Fantastic! I just hope that theme authors will adopt this thing as quickly as possible.
Ross Wintle 2:47 pm on October 22, 2015 Permalink | Log in to Reply
Confession: I’ve not been keeping up with developments in wp_title() in the last few releases. And I’m a developer who reads the make blog!! It’s only just now become clear that there is a new best practice from the one I started using several years ago. I suspect that there are many other developer like me, and many who don’t read the make blog!!!
As a developer that creates custom themes for clients, I’m happy for a notice to be issued (to remind me to do it in future work!). I accept the need for (well documented and communicated) deprecation, but I’d really appreciate some guarantee on removal from core. I have a LOT of custom themes out there that I’ve built over the last four or five years. They all use wp_title somewhere. I’m hoping that I won’t be needing to update all that legacy code.
Should the codex for wp_title be updated at this point to reflect the new best practice?
Drew Jaynes 3:04 pm on October 22, 2015 Permalink | Log in to Reply
The code reference page for
wp_title()
will be updated with the deprecation notice when 4.4 is released. By that point, thewp_title()
Codex article will already be redirecting to the code reference, as well.BackuPsNL 4:05 pm on October 22, 2015 Permalink | Log in to Reply
Hi
How to call the new title function with the separator of choice?
How to get just the title without the wpsite name?
I liked the way wp_title() worked.
I am not happy with this code change…
Konstantin Obenland 3:32 pm on October 23, 2015 Permalink | Log in to Reply
You can use the
document_title_separator
filter to change the separator to whatever you like. You can now even customize it to change based on what kind of page is being viewed!When you filter
document_title_parts
you can just change or unset the part that you don’t want to show up.BackuPsNL 8:54 am on October 24, 2015 Permalink | Log in to Reply
How does this work with the Yoast Seo plugin. As in the previous version i could just call wp_title and i got the correct yoast seo title when the plugin was activated.
Now i have to enable force rewrite titles in that plugin settings to get the correct title in my page.
With the Yoast plugin enabled and with force rewrite titles off i do not get the correct title as entered in the yoast seo title field in the page.
I want to use my own title function as i dont like how wp presents it now.
From wordpress you get Title – Page – Blog But i want Title – Blog – Paged
There is no way to change the order or how wordpress presents the title. is there? If so please provide a example how todo so.
Konstantin Obenland 7:59 pm on October 24, 2015 Permalink | Log in to Reply
The API was not usable for plugins until now. I’m sure SEO plugins will provide a way to interact with it by the time 4.4 ships.
johnstonphilip 4:57 pm on October 22, 2015 Permalink | Log in to Reply
I had used wp_title to generate facebook open graph meta tags. What would one want to use for that instead moving forward?
<meta property="og:title" content="” />
johnstonphilip 4:58 pm on October 22, 2015 Permalink | Log in to Reply
ok so the php was stripped out of that comment. Here it is again without the php tags
johnstonphilip 5:01 pm on October 22, 2015 Permalink | Log in to Reply
This struggle is real. Not sure how to properly share code on this forum. Anyway, the wp_title was used in the content attribute in the meta tag code above. What should it be replaced with?
Samuel Wood (Otto) 4:22 pm on November 11, 2015 Permalink | Log in to Reply
Use shortcodes. [ php ] and [ /php ] work here for php code.
Konstantin Obenland 3:34 pm on October 23, 2015 Permalink | Log in to Reply
Using
wp_title()
to display anything other than the document title is not really ideal. In your case you’d want to use thewp_head
action to attach a callback that would output that html.Nathan Shubert-Harbison 10:37 pm on November 5, 2015 Permalink | Log in to Reply
What would you use to print the page title inside the `wp_head` action though?
Samuel Wood (Otto) 4:27 pm on November 11, 2015 Permalink | Log in to Reply
Ideally, you would not be rolling your own code to do this in the first place. Many plugins can do this for you, such as SEO plugins, Facebook specific plugins, Sharing plugins, Jetpack, etc. Themes would not have this sort of code in them.
That said, the OpenGraph title for, say, a Page, would ideally be the title of the Page, not the wp_title(). OpenGraph is for sharing content, after all. So get_the_title() would be what you want to use, although you would probably need to preload the_post() and do a rewind_posts() to get that in the normal manner. It’s not an ideal situation to pre-load posts, but it is doable by plugins. It is poorly doable by themes, they’re doing it in the wrong order, basically.
Shah Alom 2:43 pm on November 12, 2015 Permalink | Log in to Reply
Have basic confusion!
What is the difference between
add add_theme_support( ‘title-tag’ ) to function file directly
and
in the after_setup_theme callback hook
Konstantin Obenland 3:58 pm on November 12, 2015 Permalink | Log in to Reply
It provides an easy way for child themes or plugins to remove the callback and change the setup process.
Konstantin Obenland 6:37 pm on November 12, 2015 Permalink | Log in to Reply
I updated the post to reflect that
wp_title()
has been reinstated until alternative usages have been identified and a path forward for them defined.Darko A7 4:41 am on November 17, 2015 Permalink | Log in to Reply
This feels like a downgrade to me, what I had in few lines of code just the way I like it in one visible place, now have to do with filters and what not. Why?
Anyway, I was doing a quick beta testing (4.4-beta4-35649) and there are absolutely no options to customize titles (separators, handling empty search strings…). This is a big omission, since they are supposedly now generated and handled by core.
Konstantin Obenland 4:33 pm on November 17, 2015 Permalink | Log in to Reply
Separators can be changed with the document_title_separator filter, adjustments for special cases can be done by filtering document_title_parts .