WordPress.org

Make WordPress Core

Opened 19 months ago

Last modified 3 months ago

#21995 new feature request

(get/the)_archive_title and (get/the)_archive_description functions

Reported by: thomask Owned by:
Milestone: Future Release Priority: normal
Severity: normal Version:
Component: Themes Keywords: has-patch dev-feedback
Focuses: template Cc:

Description

Current theme archive got problem with complexity - archive template is used for taxonomy, category, tag, author, date and custom post types archives and every type of archive got special function for showing title and special function for showing description.

So now theme developers fight with two evils - one very big archive.php file with a lot of conditions, or tons of separate simple .php files for each archive type. See #21951 for example.

Other problem of current solution is that templates are not future-proof - when new archive types are added, archive.php must be rewritten.

My idea is to create 2 simple functions (+ 2 echoing)
get_archive_title + the_archive_title
get_archive_description + the_archive_description

in those function would be all the complexity, which is now in the template, plus the filter, so something like

function get_archive_title() {
if ( is_day() ) {
	$title = sprintf( __( 'Daily Archives: %s' ), '<span>' . get_the_date() . '</span>' );
} elseif ( is_month() ) {
	$title = sprintf( __( 'Monthly Archives: %s' ), '<span>' . get_the_date( _x( 'F Y', 'monthly archives date format' ) ) . '</span>' );
} elseif ( is_year() ) {
	$title = sprintf( __( 'Yearly Archives: %s' ), '<span>' . get_the_date( _x( 'Y', 'yearly archives date format' ) ) . '</span>' );
} elseif ( is_tag() ) {
	$title = sprintf( __( 'Tag Archives: %s' ), '<span>' . single_tag_title( '', false ) . '</span>' );
} elseif ( is_category() ) {
	$title = sprintf( __( 'Category Archives: %s' ), '<span>' . single_cat_title( '', false ) . '</span>' );
} elseif ( is_post_type_archive() ) {
	$title =  sprintf( __( 'Archives: %s' ), '<span>' . post_type_archive_title( '', false ) . '</span>' );
} else {
	$title = _e( 'Blog Archives' );
}
return ( add_filter ( 'get_archive_title', $title ) );
}

(imo it could be a bit more complex, so that we could add a param to this function for simple rewritting the title for some particular type without filtering whole output)

Finally the archive template would be as simple as

<header class="archive-header">
<h1 class="archive-title"><?php the_archive_title() ?></h1>

<div class="archive-meta"><?php the_archive_description ?></div>

</header><!-- .archive-header -->

this way we will get all we need

  1. one archive file
  2. very short file without any conditions
  3. easy to filter the output
  4. future-proof as when adding new wp archive type, the function would be updated

Of course, for backwards compatibility of current themes, this function can be copied to the theme functions.php as well with !if (function_exist(
'get_archive_title'))

Attachments (6)

21995.diff (2.4 KB) - added by DrewAPicture 19 months ago.
Suggested first-run
21995.2.diff (2.8 KB) - added by DrewAPicture 14 months ago.
Adds $container param, improved phpdocs
21995.3.diff (2.9 KB) - added by DrewAPicture 14 months ago.
Fix specifier typo in $after, allow bypassing $container
21995.4.diff (3.0 KB) - added by DrewAPicture 14 months ago.
Taxonomy singular label w/ translator note
21995.5.diff (3.1 KB) - added by DrewAPicture 14 months ago.
21995.6.diff (3.1 KB) - added by DrewAPicture 14 months ago.

Download all attachments as: .zip

Change History (32)

comment:1 SergeyBiryukov19 months ago

  • Component changed from General to Template

comment:2 knutsp19 months ago

  • Cc knut@… added

+1 (adds two new functions that are really missing)

DrewAPicture19 months ago

Suggested first-run

comment:3 DrewAPicture19 months ago

  • Cc xoodrew@… added
  • Keywords has-patch dev-feedback added

I'm kind of on the fence about this. You'd write almost as much code filtering the thing to suit your taste as you would just using the conditionals. On the other hand, having them all wrapped up like this would make for a neater archive.php.

Attached a first-run patch.

comment:4 greenshady19 months ago

+1 for this. This is one of the things I hate most about making themes.

One thing I'd like to see done in addition to this is single_author_title() and author_description() functions.

comment:5 greenshady19 months ago

  • Cc justin@… added

comment:6 thee1719 months ago

I like the idea of this in core. 90% of the Themes in the repository seem to have a version of the conditionals copy/pasted in the archive.php unmodified from "Default/Kubrick", "Twenty Ten", or "Twenty Eleven". It is also the type of function that does not hinder a theme from using the old method either if it chooses.

comment:7 thee1718 months ago

  • Cc charles@… added

comment:8 emzo17 months ago

  • Cc wordpress@… added

comment:9 lightningspirit17 months ago

  • Cc lightningspirit@… added

comment:10 toscho17 months ago

  • Cc info@… added

comment:11 nacin16 months ago

  • Milestone changed from Awaiting Review to 3.6

comment:12 BandonRandon16 months ago

  • Cc BandonRandon added

+1, Yes please!

comment:13 follow-up: mdgl14 months ago

I like the idea of this and believe we should in general be doing more to address the needs of theme/plugin developers. I would like however to make a few comments on the first-cut patch from DrewAPicture:

1) The code probably intends to make use of sprintf() rather than printf().

2) Function the_archive_title() is starting to look very similar to wp_title() and I wonder whether there is an opportunity to generalise and/or share more code between these functions (e.g. create the_page_title() applying to any form of page not just archives and merge code with wp_title()). See also comment:4.

3) For custom taxonomies, rather than just printing "Taxonomy Archives" we should probably refer to the name of the particular taxonomy as already happens with category and post_tag, so for example:

} elseif ( is_tax() ) {
      $term = get_queried_object();
      $tax = get_taxonomy( $term->taxonomy );
      $title = sprintf( __( '%1$s Archives: %2$s' ), '<span>' . $tax->labels->singular_name . '</span>', '<span>' . single_term_title( '', false ) . '</span>' ); 
}

A moot point is then whether the <span> elements would need to be distinguished for styling.

comment:14 thee1714 months ago

Or replace the <span> and </span> with a parameter that defaults to <span> and </span> but easily overridable to other HTML5 tags or styling.

DrewAPicture14 months ago

Adds $container param, improved phpdocs

comment:15 in reply to: ↑ 13 ; follow-up: DrewAPicture14 months ago

21995.2.diff adds a $container param defaulting to span. Also improved the phpdocs and changed the printfs to sprintfs in light of the $display bool.

Replying to mdgl:

3) For custom taxonomies, rather than just printing "Taxonomy Archives" we should probably refer to the name of the particular taxonomy as already happens with category and post_tag.

I'm going to hold off on customizing the Taxonomy Archives text until we have some feedback from folks like @pavelevap, @SergeyBiryukov or @dd32. Of late there's been reticence to leverage the taxonomy labels because of lack of control over the context.

I can see adding a new label for taxonomy archives but that also may be off the table.

comment:16 follow-up: thee1714 months ago

There is something wrong, I am returning

Category Archives: <span>General</0>

with the_archive_title() perhaps it would be nice to have the option to disable the tags or do something similar.

comment:17 in reply to: ↑ 16 mdgl14 months ago

Replying to thee17:

There is something wrong, I am returning

Category Archives: <span>General</0>

with the_archive_title() perhaps it would be nice to have the option to disable the tags or do something similar.

There is just a small typo in the latest patch:

$after = sprintf( '</%x>', $container );

which should of course use the %s type specifier rather than %x. In fact, I suspect that if $container is empty the code should leave both $before and $after completely empty as well.

comment:18 DrewAPicture14 months ago

Replying to mdgl:

There is just a small typo in the latest patch:

$after = sprintf( '</%x>', $container );

which should of course use the %s type specifier rather than %x.

Done in 21995.3.diff

In fact, I suspect that if $container is empty the code should leave both $before and $after completely empty as well.

It is now. Defaults to span, but if you specify $container as empty it'll output nothing.

DrewAPicture14 months ago

Fix specifier typo in $after, allow bypassing $container

comment:19 thee1714 months ago

it works great now, sure reduces a lot of code in my theme.

comment:20 in reply to: ↑ 15 SergeyBiryukov14 months ago

Replying to DrewAPicture:

Replying to mdgl:

3) For custom taxonomies, rather than just printing "Taxonomy Archives" we should probably refer to the name of the particular taxonomy as already happens with category and post_tag.

I'm going to hold off on customizing the Taxonomy Archives text until we have some feedback from folks like @pavelevap, @SergeyBiryukov or @dd32. Of late there's been reticence to leverage the taxonomy labels because of lack of control over the context.

The closest thing that comes to mind is cattitle argument in feed_links_extra():
http://core.trac.wordpress.org/browser/tags/3.5.1/wp-includes/general-template.php#L1626

It's '%1$s %2$s %3$s Category Feed', which seems to work. posttypetitle, on the other hand, is just '%1$s %2$s %3$s Feed', which maybe not be ideal for i18n, but there's a comment above it where all the placeholders are explained, so that translators could figure it out and translate accordingly.

So I guess '%1$s Archives: %2$s' might work too for a custom taxonomy archive title, as long as there's an explanation for the placeholders.

DrewAPicture14 months ago

Taxonomy singular label w/ translator note

comment:21 DrewAPicture14 months ago

21995.4.diff adds the taxonomy singular name label when is_tax().

I'm not a huge fan of having to add curly braces just for that one multi-line condition. On the other hand, I felt like doing this:

$title = sprintf( __( '%1$s Archives: %2$s' ), get_taxonomy( get_queried_object()->taxonomy )->labels->singular_name, $before . single_term_title( '', false ) . $after );

was a bit too clever just to keep it on one line.

DrewAPicture14 months ago

comment:22 DrewAPicture14 months ago

After a conversation with @helen this morning, opted to test if $term->taxonomy isset before proceeding in 21995.5.diff

DrewAPicture14 months ago

comment:23 follow-up: DrewAPicture14 months ago

Based on further review of other uses of get_queried_object(), I'm going to go without the check in 21995.6.diff

comment:24 in reply to: ↑ 23 mdgl14 months ago

Replying to DrewAPicture:

Based on further review of other uses of get_queried_object(), I'm going to go without the check in 21995.6.diff

Ah, yes the "what exactly is the queried object" problem!! I believe this can be a bit hairy in the presence of "complex" queries, and I am sure there are other tickets on this very topic, but somehow, if is_tax() returns true you need to be able to rely on the object being a (custom) taxonomy. Similarly for the other is_xxx() functions. Anything else results in too much madness!!

comment:25 DrewAPicture11 months ago

  • Milestone changed from 3.6 to Future Release

comment:26 nacin3 months ago

  • Component changed from Template to Themes
  • Focuses template added
Note: See TracTickets for help on using tickets.