Add span element to get_the_archive_title()

[Kaira]

As a theme developer (@Kaira) I'd like to request this small feature of adding a <span> element to get_the_archive_title() function.

This is to allow theme developers to target and style the archive title with CSS to be able to add styling to it.

I've experienced the need for this when developing themes for WordPress.org and for when I'm building client websites.

Thanks

[Kaira]

This is get_the_archive_title() with my added feature request

[Kaira]

The original get_the_archive_title() in /wp-includes/general-template.php

[jcastaneda]

Is that not what the_archive_title() does already?

The function accepts two arguments, the first one being what will be printed before the title and the second what will be printed after.

The only one that adds any extra markup would be the author.

[Kaira]

Hi @jcastaneda

Thanks for the response... I've uploaded 2 images to explain more on what I mean.

Thanks

[swissspidy]

#39646 was marked as a duplicate.

[SergeyBiryukov]

ADDED FEATURE REQUEST - Example - get_the_archive_title.php should be converted to a proper patch, see ​https://make.wordpress.org/core/handbook/tutorials/trac/submitting-a-patch/.

[milindmore22]

proper patch

[Kaira]

Hi @sergeyBiryukov / @milindmore22 .. does this mean the feature request has been submitted?

[milindmore22]

Hello @Kaira,
I have attached a proper patch for you request, soon someone from WordPress core team will review the patch and merge it in future release let's wait for them to review and hope for the best,

Regards,
Milind

[Kaira]

Hi @milindmore22

Thanks very much... hoping they do :)

Thanks

[shireling]

Do we want a span on both halves of the title? That might make it easier for users/themers to target the desired section.

It looks like an extra xml file snuck into the patch I just uploaded, but this diff should be better:

​https://patch-diff.githubusercontent.com/raw/chad1008/wordpress-develop/pull/1.diff

[theMikeD]

I think the first patch is a better solution although I don't understand why Author was ignored.

In @shireling patch I would suggest against the second span (the one around the content, what you call archive-title). The single span should be enough of a target. Or change it to

$format ='<span class="archive-label"><span>%s</span>%s</span>';

The other way to handle this would be to expand the filter to take (using @shireling patch for the var names) $title, $format, $type, $title_classes, $name or something along those lines. This way theme authors could wrap them as they see fit. This also dodges the what-would-certainly-be-an-endless discussion on what the class name should be called.

As another observation, the : is problematic for me. Perhaps we can get rid of that altogether and add a CSS rule to add it back in? This way authors can determine if they want a : or - or whatever.

[milindmore22]

The author was already in the span that's why I ignored it.

<span class="vcard">' . get_the_author() . '</span>

[Kaira]

I would agree to having the span on only the label... For example I've had a few times where users want to hide the word "Category:"... and with the one span on the label, that is enough to style the label different to the name/title with CSS.

[shireling]

Cool, if it's going to be on the label I think the single span solution can work nicely. I'm uploading a new patch - this one applies a single span to just the label (first) half of the title. The vcard title on author archives title remains in place.

It also modifies the_archive_title(); and get_the_archive_title(); to accept an argument defining the class name - if left blank, you get a span without any class assigned.

[shireling]

single span, with user defined class name

[shireling]

Previous patch was inverted - this replaces 38545.2.patch

[Kaira]

Great... thanks :)

[swissspidy]

38545.3.patch​.

• needs to update the inline docs for the function
• the class names should be escaped
• this is not good for i18n. For example, right now we have __( 'Tag: %s' ), suggested ist: __( 'Tag: ' ). And the translator comment isn't adjusted.

See also #31237.

[Kaira]

Hey @shireling

Can you help with this?
Or how can I make the changes?

Sorry I'm not too clued up on submitting changes :D

[shireling]

Updated inline docs, updated translator notes, escaped new class name

[shireling]

More than happy to try, thanks for looking that over @swissspidy :)

I wasn't sure if it would be best practice to remove the entire translator note on strings where there were no variables, or just the reference to the variable. For now (to use @swissspidy's example)

/* translators: Tag archive title. 1: Tag name */
has been changed to
/* translators: Tag archive title. */

Please let me know if it would be better to remove the entire note on the lines that have no variables in them.

@Kaira - I'm new to submitting changes as well - ​this has been my bible :)

[Kaira]

@shireling Thanks for the link... I'll go through that.

[melchoyce]

@swissspidy How do you think this is looking now? Ready for merge?

[swissspidy]

Things like __( 'Archives: ' ); aren't really great fro translators though. Then I'd rather prefer <span> elements inside the strings.

@SergeyBiryukov @ocean90 What do you guys think about that?

[SergeyBiryukov]

Replying to swissspidy:

Things like __( 'Archives: ' ); aren't really great fro translators though. Then I'd rather prefer <span> elements inside the strings.

The trailing space should be moved out of the strings, otherwise I think it's fine. Maybe @ocean90 can take a look if any locales do something with these strings that would no longer be possible with the patch?

[melchoyce]

@ocean90 Would you have time to take a look at this during 4.9?

[shireling]

I'm happy to put together another patch moving those spaces out of the strings, but I'll hold off to see if any other changes are needed as well :)

[javorszky]

Hello,

Great idea for improving it! :)

Few observations:

if span_class is empty, the output will have a trailing space before the closing > of the opening <span>. So it's be <span >Category:</span> foo. That could be solved by adding the space here (notice the space before "class"):

if ( ! '' == $span_class ) { 
	$span_class = sprintf( ' class="%s"', sanitize_html_class( $span_class ) ); 
}

This currently doesn't work with RTL languages. For that to work, you'd have to do

/* translators: Archive title format. 1: span classes, 2: archive type name, 3: archive term */
$format = _x( '<span%1$s>%2$s</span>%3$s', 'archive title format' );`
$title = sprintf( $format, $span_class, $type, $name );

That way any RTL language could have a translation that would essentially be

$format = '%3$s<span%1$s>%2$s</span>

after translation and the sprintf would still work.

From a technical point of view, if you accept span class as an array, or break it up by spaces, then you can add the author's vcard classname to the array. So it'd be

if ( ! '' == $span_class && is_string( $span_class ) ) { 
	$span_class = explode( ' ', $span_class );
	$span_class = sprintf( 'class="%s"', sanitize_html_class( $span_class ) ); 
}

// then later
} elseif ( is_author() ) { 
    /* translators: Author archive title. %s: Author name */ 
    $type = __( 'Author: ' ); 
    $span_class[] = 'vcard';
    $name = get_the_author(); 
} elseif ( is_year() ) {

// and finally

$title = sprintf( $format,' classes="' . implode( ' ', $span_class ) . '"', $type, $name ); 

And that's about it from me for now. Let me know what you think.

[BinaryMoon]

Since I am keen to see this added in 4.9 I asked on Twitter if anyone could review it and @glueckpress replied with:

On my phone til next week, so replying here. 2 things come to mind:
1/ string should not end with space.
2/ Using _x() for context could be useful to make string unique for localisers.

The thread is here:
​https://twitter.com/glueckpress/status/906235746549420032

Thanks also to @javorsky for the feedback.

Hope this helps 😀

[javorszky]

You're welcome :)

P.S.: There's a "z" in my name too ;)

Replying to BinaryMoon:

Since I am keen to see this added in 4.9 I asked on Twitter if anyone could review it and @glueckpress replied with:

On my phone til next week, so replying here. 2 things come to mind:
1/ string should not end with space.
2/ Using _x() for context could be useful to make string unique for localisers.

The thread is here:
​https://twitter.com/glueckpress/status/906235746549420032

Thanks also to @javorsky for the feedback.

Hope this helps 😀

[grapplerulrich]

Here are some of the changes that I made:

• changes with the spacing
• fixed a few alignment issues
• improved part of the documentation
• Replaced the large if statement with a smaller one

@javorszky The order does not need to be able to be changed for RTL. That is automatically done by the browser. Though there maybe some other languages where that may be necessary but I am not sure which ones.

[javorszky]

Bear in mind that some LTR languages might have different word orders. English language has a hierarchy of thing: member things, ie "Category: cats"

Hungarian on the other hand (my mothertongue) would potentially display the same as "'macskák' kategória", which translated would be "(the) cats category".

Control over word / concept order is important.

[grapplerulrich]

@javorszky Yea, Japanese do that to sometimes but it seems like the translations that I checked did not change the order of the term and taxonomy. ​https://translate.wordpress.org/projects/wp/dev/hu/default?filters%5Bstatus%5D=either&filters%5Boriginal_id%5D=202084&filters%5Btranslation_id%5D=9661611

[javorszky]

@grapplerulrich the fact that one language did not do it in this case is not grounds for not including the ability to change word order. Remember, with translations, you're preparing the code so it can be translated into ANY of the languages, even ones you don't even know about.

I'd highly recommend you include numbered placeholders so the order can be moved around.

[zoonini]

It would be SO great to get this ticket moving again. Removing the word "Category:" on the category archive title is something that I, and many of my colleagues at WordPress.com, get requests for every single day -- the current solutions are hacky and cumbersome.

Thank you for taking another look if possible!

[Kaira]

Awesome :)

[melchoyce]

Can we get this into the next point release instead of 5.0?

[danieltj]

Yes, but will need a refresh to get it inline with where the current codebase is at now as the last patch was submitted 6 months ago. I'll take a look at this later unless someone has time before me to check things over.

[ocean90]

​4.9.5 beta was released yesterday, moving to 4.9.6.

[danieltj]

Replying to ocean90:

​4.9.5 beta was released yesterday, moving to 4.9.6.

We can have this moved into the 4.9.5 release as we still have time before the release candidate is out.

[Clorith]

I'm not a fan of pushing this into a minor release, especially not without a good period of time to spread information ahead of time. I'll drag a parallel to #42578 here, the revert of markup introduced to get_the_author_description(), sudden markup changes should not be introduced without a proper timeline for informing users as we don't know what themes might be doing styling wise that creates visual breakage.

[desrosj]

@Clorith I think I would normally agree, but the changes in 38545.6.patch​ from @grapplerulrich would only result in additional markup if the theme adds the third parameter to the function call. This makes it an opt-in change for theme developers. The change to get_the_author_description() happened without the theme developer enabling the markup change.

38545.6.patch​ also still needs a refresh to apply cleanly.

[audrasjb]

refreshed patch

[audrasjb]

@desrosj I refreshed the patch.

Cheers,
Jb

[desrosj]

Thanks, @audrasjb.

Reviewed and have a few notes:

• The parameter descriptions for the_archive_title() should all be aligned.
• the_archive_title() should have a @since tag stating when that the new parameter was added.
• The version on the new @since tag on get_the_archive_title() is wrong.
• If the placeholders are removed from the translatable strings, the /* translators: */ comments are no longer needed.
• The $span_class should also be passed to the get_the_archive_title filter (remember to add a @since tag).

After taking a deeper look at this one, I agree with @Clorith about this not going into a minor. In the currently proposed approach, a <span> is always added even if the class parameter is empty. This would definitely have the potential for causing issues in themes.

If the <span> was 'output only if there was a class provided to the function, then this could be considered for a minor release. But, I am not sure that would be best.

[desrosj]

Punting to 4.9.7 as this still needs an updated patch.

[audrasjb]

In 38545.8.diff:

• The parameter descriptions for the_archive_title() should all be aligned.

Fixed.

• the_archive_title() should have a @since tag stating when that the new parameter was added.

Fixed and set to 4.9.6.

• The version on the new @since tag on get_the_archive_title() is wrong.

Fixed and set to 4.9.6.

• If the placeholders are removed from the translatable strings, the /* translators: */ comments are no longer needed.

Placeholders removed from translators comments.

• The $span_class should also be passed to the get_the_archive_title filter (remember to add a @since tag).

Added $span_class to the filter, and related @since documentation.

After taking a deeper look at this one, I agree with @Clorith about this not going into a minor. In the currently proposed approach, a <span> is always added even if the class parameter is empty. This would definitely have the potential for causing issues in themes.
If the <span> was 'output only if there was a class provided to the function, then this could be considered for a minor release. But, I am not sure that would be best.

In my latest patch, span element is only generated if $span_class parameter is used by the theme author.

Hopefully, this one will land in 4.9.6… otherwise, it will wait for 4.9.7 :)

Cheers,
Jb

[audrasjb]

Some fixes - see @desrosj review

[desrosj]

Moving all tickets in 4.9.7 to 4.9.8.

[audrasjb]

Hi,

In 38545.9.diff I refreshed the patch and moved the ticket back to 4.9.7 milestone.

Cheers,

Jb

[audrasjb]

Patch refreshed for 4.9.7 milestone

[BinaryMoon]

Looks good to me. Thanks for updating it!

[ocean90]

4.9.7 has been released, moving to next milestone.

[audrasjb]

In 38545.10.diff: update the patch since we are in 4.9.8 now.

[audrasjb]

In 38545.10.diff: update the patch since we are in 4.9.8 now.

[pento]

4.9.8 has hit RC, moving to 4.9.9.

[audrasjb]

Patch refreshed so hopefully it can land in 4.9.9

[audrasjb]

@since refreshed for 5.0.3

[desrosj]

This falls outside of the 5.0.3 priorities, so moving to 5.1.

[Confridin]

I've just created a patch that might solve this issue in #42768

[BinaryMoon]

Thanks for the patch @Confridin

That's a nice idea, but I would rather add the spans (or do both). The spans gives the users the freedom to hide them with css, or keep them if they prefer.

In addition adding spans gives the opportunity for some more creative design. For example in the theme Carmack I wrapped the prefix using a filter myself, and then styled it as a subheading.
eg ​https://carmackdemo.wordpress.com/category/books/

[Confridin]

Replying to BinaryMoon:

That's a nice idea, but I would rather add the spans (or do both). The spans gives the users the freedom to hide them with css, or keep them if they prefer.

I did when I was working on my patch. But I changed my mind : I thought enabling automatic <span> addition might break some themes or plugins. For example, some theme may already add CSS to existing spans, and adding more spans might break their websites.

[desrosj]

In 38545.2.diff​:

• Update since annotations to 5.2.0.
• Instead of turning $span_class into class="class-name" before passing to the filter, add the attribute definition when building $title. This way someone using the filter does not need to parse out the class if they want to change it.

Before this is committed, I'd also like to get confirmation that the string changes are not problematic. For an example of the changes in the current patch, look at the tag title:

Before:

/* translators: Tag archive title. %s: Tag name */
$title = sprintf( __( 'Tag: %s' ), single_tag_title( '', false ) );

After:

/* translators: Tag archive title. */
$type = __( 'Tag:' );

I am concerned that removing that placeholder and contextual information from the translation comment will make these strings more difficult to translate.

[desrosj]

This still needs a second opinion on the string changes. Going to punt this to 5.3 since 5.2 beta period starts tomorrow.

[BinaryMoon]

@desrosj - is there anyone we can ask to help? I can't see this being a complex thing to check so I'd be happy to ping something and ask for confirmation.

[Confridin]

Hello

I think that the last solution is a bit tricky for various reasons:

• many wordress users and developers will never need a span here.
• some themes may already have CSS for <span> tags. Adding another <span> to this function may break their webdesign
• it will be more complex to fix tickets https://core.trac.wordpress.org/ticket/42768 & https://core.trac.wordpress.org/ticket/31237

[Confridin]

Add another filter to get_the_archive_title()

[Confridin]

I tried another solution.

It does not add a span tag by itself, but it adds another filter. People will be able to easily add a span, for example:

<?php
add_filter( 'get_the_archive_title_prefix', 'sx_archive_prefix' );
function sx_archive_prefix( $prefix ){
    return '<span class=”helloworld”>' . $prefix . '</span>';
}

They will also be able to remove or alter the begining of the function (ex. "Category: %s"). Here are some examples:

• An easy way to remove it:

  <?php
  add_filter( 'get_the_archive_title_prefix', __return_empty_string() );
  

• An easy way to change it:

  <?php
  add_filter( 'get_the_archive_title_prefix', 'sx_archive_prefix' );
  function sx_archive_prefix( $prefix ){
      $prefix = str_replace( "Category", "Awesome Category", $prefix ); 
      return $prefix;
  }
  

• An easy way to add other HTML tag:

  <?php
  add_filter( 'get_the_archive_title_prefix', 'sx_archive_prefix' );
  function sx_archive_prefix( $prefix ){
      return '<strong>' . $prefix . '</strong>';
  }
  

[ramiy]

Related: #31237 (much older ticket)

[JeffPaul]

With 5.3 Beta 1 shipping today, I'm punting this to Future Release so as not to clog up the 5.4 milestone. However, @desrosj as the ticket owner feel free to move to 5.4 if you feel comfortable committing to resolving this fully then... thanks!

[audrasjb]

Moving to 5.4 as we were close to find a solution for this one :)

Adding early keyword to handle that at the beginning of the release cycle if possible.

[davidbaumwald]

This ticket was discussed during today's 5.4 bug scrub. With Beta 1 in less than two weeks, this is being moved to Future Release. If any committer feels this can be included in 5.4 in time or wants to assume ownership during a specific cycle, feel free to update the milestone.

[audrasjb]

Given this ticket was mentioned two times in the call for tickets, it's worth to try to ship it in WP 5.5.
Adding needs-testing and needs-refresh for a complete review of the existing patch.

[Confridin]

In 38545.13.diff :

• refresh patch with latest core file
• did some tests with new filter, all work fine for me

Can someone else test my patch ?

<?php
// Change prefix value
add_filter( 'get_the_archive_title_prefix', 'sx_archive_prefix' );
function sx_archive_prefix( $prefix ){
    $prefix = str_replace( "Category", "Awesome Category", $prefix ); 
    return $prefix;
}

<?php
// Add custom html to prefix
add_filter( 'get_the_archive_title_prefix', 'sx_archive_prefix' );
function sx_archive_prefix( $prefix ){
    return '<span>' . $prefix . '</span>';
}

<?php

// remove prefix
add_filter( 'get_the_archive_title_prefix', '__return_empty_string' );

It solves :

• this ticket
• #42768
• #31237

[audrasjb]

I'll have a look later today.

PS: Adding back early workflow keyword :-)

[joyously]

I think this entire ticket ignores the basic problem of the function, which is that it will only output a single title, even if the query is more complicated, misrepresenting what the page is about. But that is probably a different ticket. If it were to output multiple parts to represent a more complicated query, I would expect each part to have its own span.
Also, there is no way to remove the vcard span on the author, which does not belong as the definition of vcard is more than just the name.

[Confridin]

Replying to joyously:

I think this entire ticket ignores the basic problem of the function, which is that it will only output a single title, even if the query is more complicated, misrepresenting what the page is about. But that is probably a different ticket. If it were to output multiple parts to represent a more complicated query, I would expect each part to have its own span.
Also, there is no way to remove the vcard span on the author, which does not belong as the definition of vcard is more than just the name.

The initial ticket actually corresponds to a very specific need (adding a span), but other tickets are linked to this function.

The last patch (38545.13.diff) allows to improve it in order to correct its flaws : being able to get the archive title with or without prefix, and with the ability to filter all data before returning it.

Related tickets are :

• 42768
• 31237

[Confridin]

Fix 38545.13.diff file path

[davidbaumwald]

@ocean90 Is this still on your list to handle for 5.5? Beta 1 is in less than a week. ;)

[audrasjb]

Patch refresh for WP 5.5

[audrasjb]

Testing 38545.15.diff

[audrasjb]

In 38545.15.diff, I refreshed the previous patch:

• Patch refreshed against trunk
• @since tag updated to 5.5.0
• Remove ending spaces in translations and move them to the final translatable string
• few small coding standards fixes

The patch is tested and works fine, see the above screenshot.
For my test, I added the following hook to twenty twenty functions.php file:

<?php
function wporg_get_the_archive_title_prefix( $prefix ) {
        return '<em>' . $prefix . '</em>';
}
add_filter( 'get_the_archive_title_prefix', 'wporg_get_the_archive_title_prefix' );

@ocean90, as ticket owner, are you still available to review this for potential 5.5 inclusion, please? Thanks :)

Trac ticket: https://core.trac.wordpress.org/ticket/38545

[ocean90]

Moved 38545.15.diff​ into a PR in ​https://github.com/WordPress/wordpress-develop/pull/387 with the following changes:

• Fix PHPCS issues.
• Add context to all new strings.
• Combine title and prefix only when prefix is set.
• Add the span tag around $title.
• Pass the $prefix parameter to get_the_archive_title filter.

[audrasjb]

Many thanks @ocean90 !
PR387 looks great to me :)
I added a quick note in your PR. I think an @param note is missing in inline docs.

Trac tickets:

• https://core.trac.wordpress.org/ticket/31237
• https://core.trac.wordpress.org/ticket/38545
• https://core.trac.wordpress.org/ticket/42768

[ocean90]

In 48294:

Themes: Introduce get_the_archive_title_prefix filter for changing the prefix used for archive titles.

In get_the_archive_title() split the internal $title variable into $title and $prefix. By using the new get_the_archive_title_prefix filter the prefix can now wrapped with custom elements or removed completely by using

add_filter( 'get_the_archive_title_prefix', '__return_empty_string' );

Also, wrap the title part with a span element and pass the original title and prefix to the existing get_the_archive_title filter, allowing further customization to the archive titles.

Props Kaira, milindmore22, shireling, grapplerulrich, audrasjb, desrosj, Confridin, ramiy, ocean90.
Fixes #31237.
Fixes #38545.

[audrasjb]

Dev note published: ​https://make.wordpress.org/core/2020/07/30/filtering-archive-pages-headings-in-wordpress-5-5/