WordPress.org

Make WordPress Core

Opened 3 years ago

Last modified 3 weeks ago

#38545 reviewing enhancement

Add span element to get_the_archive_title()

Reported by: Kaira Owned by: audrasjb
Milestone: 5.4 Priority: normal
Severity: normal Version: 4.6.1
Component: Taxonomy Keywords: has-patch 2nd-opinion early
Focuses: Cc:
PR Number:

Description

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

Attachments (19)

ADDED FEATURE REQUEST - Example - get_the_archive_title.php (2.9 KB) - added by Kaira 3 years ago.
This is get_the_archive_title() with my added feature request
get_the_archive_title().php (2.9 KB) - added by Kaira 3 years ago.
The original get_the_archive_title() in /wp-includes/general-template.php
01.png (779.9 KB) - added by Kaira 3 years ago.
02.png (168.6 KB) - added by Kaira 3 years ago.
38545.diff (2.8 KB) - added by milindmore22 3 years ago.
proper patch
38545.patch (22.3 KB) - added by shireling 3 years ago.
38545.2.patch (4.7 KB) - added by shireling 3 years ago.
single span, with user defined class name
38545.3.patch (4.7 KB) - added by shireling 3 years ago.
Previous patch was inverted - this replaces 38545.2.patch
38545.4.patch (5.2 KB) - added by shireling 3 years ago.
Updated inline docs, updated translator notes, escaped new class name
38545.5.patch (4.5 KB) - added by grapplerulrich 2 years ago.
38545.6.patch (4.6 KB) - added by grapplerulrich 2 years ago.
38545.7.diff (4.7 KB) - added by audrasjb 19 months ago.
refreshed patch
38545.8.diff (5.5 KB) - added by audrasjb 19 months ago.
Some fixes - see @desrosj review
38545.9.diff (5.6 KB) - added by audrasjb 17 months ago.
Patch refreshed for 4.9.7 milestone
38545.10.diff (5.6 KB) - added by audrasjb 16 months ago.
In 38545.10.diff: update the patch since we are in 4.9.8 now.
38545.11.diff (5.6 KB) - added by audrasjb 15 months ago.
Patch refreshed so hopefully it can land in 4.9.9
38545.12.diff (5.6 KB) - added by audrasjb 11 months ago.
@since refreshed for 5.0.3
38545.2.diff (5.5 KB) - added by desrosj 8 months ago.
patch.2.diff (3.6 KB) - added by Confridin 8 months ago.
Add another filter to get_the_archive_title()

Download all attachments as: .zip

Change History (96)

@Kaira
3 years ago

This is get_the_archive_title() with my added feature request

@Kaira
3 years ago

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

#1 @jcastaneda
3 years ago

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
3 years ago

@Kaira
3 years ago

#2 @Kaira
3 years ago

Hi @jcastaneda

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

Thanks

#3 @swissspidy
3 years ago

#39646 was marked as a duplicate.

#4 @SergeyBiryukov
3 years ago

  • Keywords needs-patch added

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
3 years ago

proper patch

#5 @milindmore22
3 years ago

  • Keywords has-patch added; needs-patch removed

#6 @Kaira
3 years ago

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

Last edited 3 years ago by Kaira (previous) (diff)

#7 @milindmore22
3 years ago

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

#8 @Kaira
3 years ago

Hi @milindmore22

Thanks very much... hoping they do :)

Thanks

@shireling
3 years ago

#9 @shireling
3 years ago

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

#10 @theMikeD
3 years ago

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.

#11 @milindmore22
3 years ago

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

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

#12 @Kaira
3 years ago

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.

#13 @shireling
3 years ago

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
3 years ago

single span, with user defined class name

@shireling
3 years ago

Previous patch was inverted - this replaces 38545.2.patch

#14 @Kaira
3 years ago

Great... thanks :)

#15 @swissspidy
3 years ago

  • Keywords needs-refresh added

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.

#16 @Kaira
3 years ago

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
3 years ago

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

#17 @shireling
3 years ago

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 :)

Last edited 3 years ago by shireling (previous) (diff)

#18 @Kaira
3 years ago

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

#19 @melchoyce
2 years ago

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

#20 follow-up: @swissspidy
2 years ago

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?

#21 in reply to: ↑ 20 @SergeyBiryukov
2 years ago

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?

#22 follow-up: @melchoyce
2 years ago

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

#23 in reply to: ↑ 22 @shireling
2 years ago

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 :)

#24 @javorszky
2 years ago

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.

#25 follow-up: @BinaryMoon
2 years ago

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 😀

Last edited 2 years ago by BinaryMoon (previous) (diff)

#26 in reply to: ↑ 25 @javorszky
2 years ago

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 😀

#27 follow-up: @grapplerulrich
2 years ago

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.

#28 in reply to: ↑ 27 @javorszky
2 years ago

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.

#29 @grapplerulrich
2 years ago

@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

#30 @javorszky
2 years ago

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

#31 @zoonini
22 months ago

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!

This ticket was mentioned in Slack in #core by jeffpaul. View the logs.


22 months ago

#33 follow-up: @SergeyBiryukov
21 months ago

  • Milestone changed from Awaiting Review to 5.0

#34 in reply to: ↑ 33 @Kaira
20 months ago

Awesome :)

#35 @melchoyce
20 months ago

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

#36 @danieltj
20 months ago

  • Milestone changed from 5.0 to 4.9.5

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.

#37 follow-up: @ocean90
20 months ago

  • Milestone changed from 4.9.5 to 4.9.6

#38 in reply to: ↑ 37 @danieltj
20 months ago

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.

This ticket was mentioned in Slack in #core by danieltj. View the logs.


20 months ago

This ticket was mentioned in Slack in #core by desrosj. View the logs.


19 months ago

#41 @Clorith
19 months ago

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.

#42 @desrosj
19 months ago

@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
19 months ago

refreshed patch

#43 @audrasjb
19 months ago

  • Keywords needs-refresh removed

@desrosj I refreshed the patch.

Cheers,
Jb

#44 follow-up: @desrosj
19 months ago

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.

This ticket was mentioned in Slack in #core by desrosj. View the logs.


19 months ago

#46 @desrosj
19 months ago

  • Milestone changed from 4.9.6 to 4.9.7

Punting to 4.9.7 as this still needs an updated patch.

#47 in reply to: ↑ 44 @audrasjb
19 months ago

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
19 months ago

Some fixes - see @desrosj review

#48 @desrosj
18 months ago

  • Milestone changed from 4.9.7 to 4.9.8

Moving all tickets in 4.9.7 to 4.9.8.

#49 @audrasjb
17 months ago

  • Milestone changed from 4.9.8 to 4.9.7

Hi,

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

Cheers,

Jb

@audrasjb
17 months ago

Patch refreshed for 4.9.7 milestone

#50 @BinaryMoon
17 months ago

Looks good to me. Thanks for updating it!

#51 @ocean90
17 months ago

  • Milestone changed from 4.9.7 to 4.9.8

4.9.7 has been released, moving to next milestone.

@audrasjb
16 months ago

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

#52 @audrasjb
16 months ago

  • Keywords needs-refresh added

#53 @audrasjb
16 months ago

  • Keywords needs-refresh removed

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

This ticket was mentioned in Slack in #core by joshuawold. View the logs.


16 months ago

This ticket was mentioned in Slack in #core by pbiron. View the logs.


16 months ago

#56 @pento
16 months ago

  • Milestone changed from 4.9.8 to 4.9.9

4.9.8 has hit RC, moving to 4.9.9.

#57 @audrasjb
15 months ago

  • Keywords needs-refresh added

@audrasjb
15 months ago

Patch refreshed so hopefully it can land in 4.9.9

#58 @audrasjb
15 months ago

  • Keywords needs-refresh removed

#59 @pento
13 months ago

  • Milestone changed from 4.9.9 to 5.0.1

#60 @pento
11 months ago

  • Milestone changed from 5.0.1 to 5.0.2

#61 @pento
11 months ago

  • Milestone changed from 5.0.2 to 5.0.3

@audrasjb
11 months ago

@since refreshed for 5.0.3

#62 @desrosj
11 months ago

  • Milestone changed from 5.0.3 to 5.1
  • Owner set to desrosj
  • Status changed from new to reviewing

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

#63 @pento
10 months ago

  • Milestone changed from 5.1 to 5.2

#64 @Confridin
10 months ago

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

#65 follow-up: @BinaryMoon
10 months ago

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/

#66 in reply to: ↑ 65 @Confridin
10 months ago

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
8 months ago

#67 @desrosj
8 months ago

  • Keywords 2nd-opinion added

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.

#68 @desrosj
8 months ago

  • Milestone changed from 5.2 to 5.3

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

#69 @BinaryMoon
8 months ago

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

#70 @Confridin
8 months ago

Hello

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

@Confridin
8 months ago

Add another filter to get_the_archive_title()

#71 @Confridin
8 months ago

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>';
    }
    

This ticket was mentioned in Slack in #polyglots by tellyworth. View the logs.


4 months ago

#73 @ramiy
4 months ago

Related: #31237 (much older ticket)

#74 @JeffPaul
8 weeks ago

  • Milestone changed from 5.3 to Future Release

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!

#75 @audrasjb
7 weeks ago

  • Keywords early added
  • Milestone changed from Future Release to 5.4

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.

#76 @desrosj
3 weeks ago

  • Owner desrosj deleted

#77 @audrasjb
3 weeks ago

  • Owner set to audrasjb
Note: See TracTickets for help on using tickets.