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

[thomask]

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

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

Suggested first-run

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.

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

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.

+1, Yes please!

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.

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

Adds $container param, improved phpdocs

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.

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.

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.

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.

Fix specifier typo in $after, allow bypassing $container

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

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.

Taxonomy singular label w/ translator note

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.

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

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

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!!