feat: add support for tag labels

newspack-theme/functions.php

@@ -182,6 +182,7 @@ function newspack_setup() {
 		$secondary_color_variation = newspack_adjust_brightness( $secondary_color, -40 );
 
 		// Editor color palette.
+		// phpcs:disable Squiz.Commenting.InlineComment.InvalidEndChar -- Let's not be too precious about the brief comments here.
 		add_theme_support(
 			'editor-color-palette',
 			array(
@@ -227,6 +228,7 @@ function newspack_setup() {
 				),
 			)
 		);
+		// phpcs:enable Squiz.Commenting.InlineComment.InvalidEndChar
 
 		add_theme_support(
 			'editor-gradient-presets',
@@ -270,7 +272,7 @@ function newspack_setup() {
 		// Add support for responsive embedded content.
 		add_theme_support( 'responsive-embeds' );
 
-		// Make our theme AMP/PWA Native
+		// Make our theme AMP/PWA Native.
 		add_theme_support(
 			'amp',
 			[
@@ -281,7 +283,7 @@ function newspack_setup() {
 			]
 		);
 
-		// Add custom theme support - post subtitle
+		// Add custom theme support - post subtitle.
 		add_theme_support( 'post-subtitle' );
 	}
 endif;
@@ -415,7 +417,7 @@ function newspack_widgets_init() {
 function newspack_content_width() {
 	$content_width = 780;
 
-	// Check if front page or using One-Column Wide template
+	// Check if front page or using One-Column Wide template.
 	if ( ( is_front_page() && 'posts' !== get_option( 'show_on_front' ) ) || is_page_template( 'single-wide.php' ) ) {
 		$content_width = 1200;
 	}
@@ -452,11 +454,11 @@ function newspack_scripts() {
 
 	// Load custom fonts, if any.
 	if ( get_theme_mod( 'custom_font_import_code', '' ) ) {
-		wp_enqueue_style( 'newspack-font-import', newspack_custom_typography_link( 'custom_font_import_code' ), array(), null );
+		wp_enqueue_style( 'newspack-font-import', newspack_custom_typography_link( 'custom_font_import_code' ), array(), null );  // phpcs:ignore WordPress.WP.EnqueuedResourceParameters.MissingVersion -- FIXME:  determine if versioning is intentionally omitted.
 	}
 
 	if ( get_theme_mod( 'custom_font_import_code_alternate', '' ) ) {
-		wp_enqueue_style( 'newspack-font-alternative-import', newspack_custom_typography_link( 'custom_font_import_code_alternate' ), array(), null );
+		wp_enqueue_style( 'newspack-font-alternative-import', newspack_custom_typography_link( 'custom_font_import_code_alternate' ), array(), null );  // phpcs:ignore WordPress.WP.EnqueuedResourceParameters.MissingVersion -- FIXME:  determine if versioning is intentionally omitted.
 	}
 
 	/**
@@ -608,6 +610,7 @@ function newspack_enqueue_scripts() {
 	}
 
 	// Featured Image options.
+	// phpcs:ignore WordPress.WP.EnqueuedResourceParameters.NotInFooter -- TODO: Should we set $in_footer?
 	wp_register_script(
 		'newspack-extend-featured-image-script',
 		get_theme_file_uri( '/js/dist/extend-featured-image-editor.js' ),
@@ -787,10 +790,10 @@ function newspack_editor_customizer_styles() {
 
 	// If custom fonts are assigned, enqueue them as well.
 	if ( get_theme_mod( 'custom_font_import_code', '' ) ) {
-		wp_enqueue_style( 'newspack-font-import', newspack_custom_typography_link( 'custom_font_import_code' ), array(), null );
+		wp_enqueue_style( 'newspack-font-import', newspack_custom_typography_link( 'custom_font_import_code' ), array(), null );  // phpcs:ignore WordPress.WP.EnqueuedResourceParameters.MissingVersion -- FIXME:  determine if versioning is intentionally omitted.
 	}
 	if ( get_theme_mod( 'custom_font_import_code_alternate', '' ) ) {
-		wp_enqueue_style( 'newspack-font-alternative-import', newspack_custom_typography_link( 'custom_font_import_code_alternate' ), array(), null );
+		wp_enqueue_style( 'newspack-font-alternative-import', newspack_custom_typography_link( 'custom_font_import_code_alternate' ), array(), null );  // phpcs:ignore WordPress.WP.EnqueuedResourceParameters.MissingVersion -- FIXME:  determine if versioning is intentionally omitted.
 	}
 
 }
@@ -818,6 +821,8 @@ function newspack_check_current_template() {
 
 /**
  * Add body class on editor pages if editing the static front page.
+ *
+ * @param string $classes Existing classes.
  */
 function newspack_filter_admin_body_class( $classes ) {
 
@@ -847,6 +852,8 @@ function newspack_filter_admin_body_class( $classes ) {
 
 /**
  * Enqueue CSS styles for the editor that use the <body> tag.
+ *
+ * @param string $classes Existing classes.
  */
 function newspack_enqueue_editor_override_assets( $classes ) {
 	wp_enqueue_style( 'newspack-editor-overrides', get_theme_file_uri( '/styles/style-editor-overrides.css' ), false, '1.1', 'all' );
@@ -987,6 +994,9 @@ function newspack_register_meta() {
 /**
  * Migrate theme settings when switching within the family of Newspack themes.
  *
+ * @param string         $old_name  The name of the old theme.
+ * @param WP_Theme|false $old_theme The old theme object (default: false).
+ *
  * @since Newspack Theme 1.0.0
  */
 function newspack_migrate_settings( $old_name, $old_theme = false ) {
@@ -1136,26 +1146,30 @@ function newspack_sanitize_svgs() {
 
 /**
  * Truncates text to a specific character length, without breaking a character.
+ *
+ * @param string $content The text to truncate.
+ * @param int    $length The character length to truncate to.
+ * @param string $after Text to append after truncation. Default is '...'.
  */
 function newspack_truncate_text( $content, $length, $after = '...' ) {
 	// If content is already shorter than the truncate length, return it.
 	if ( strlen( $content ) <= $length ) {
 		return $content;
 	}
 
-	// Find the first space after the desired length:
+	// Find the first space after the desired length.
 	$breakpoint = strpos( $content, ' ', $length );
 
-	// Make sure $breakpoint isn't returning false, and is less than length of content:
+	// Make sure $breakpoint isn't returning false, and is less than length of content.
 	if ( false !== $breakpoint && $breakpoint < strlen( $content ) - 1 ) {
 		$content = substr( $content, 0, $breakpoint ) . $after;
 	}
 	return $content;
 }
 
- /**
-  * Returns an array of 'acceptable' avatar tags, to use with wp_kses().
-  */
+/**
+ * Returns an array of 'acceptable' avatar tags, to use with wp_kses().
+ */
 function newspack_sanitize_avatars() {
 	$avatar_args = array(
 		'img'      => array(
@@ -1207,6 +1221,8 @@ function newspack_get_post_toggle_post_types() {
 /**
  * Co-authors in RSS and other feeds
  * /wp-includes/feed-rss2.php uses the_author(), so we selectively filter the_author value
+ *
+ * @param string $the_author The author's display name.
  */
 function newspack_coauthors_in_rss( $the_author ) {
 	if ( ! is_feed() || ! function_exists( 'coauthors' ) ) {
@@ -1236,9 +1252,11 @@ function newspack_theme_newspack_ads_maybe_use_responsive_placement( $responsive
 
 /**
  * Add a extra span and class to the_archive_title, for easier styling.
+ *
+ * @param string $title Archive title to be displayed.
  */
 function newspack_update_the_archive_title( $title ) {
-	// Split the title into parts so we can wrap them with spans:
+	// Split the title into parts so we can wrap them with spans.
 	$title_parts  = explode( '<span class="page-description">', $title, 2 );
 	$title_format = get_theme_mod( 'archive_title_format', 'default' );
 
@@ -1370,6 +1388,13 @@ function newspack_dequeue_mediaelement() {
 	require get_template_directory() . '/inc/newspack-sponsors.php';
 }
 
+/**
+ * Load Tag Labels compatibility file.
+ */
+if ( class_exists( '\Newspack\Tag_Labels' ) ) {
+	require get_template_directory() . '/inc/newspack-tag-labels.php';
+}
+
 /**
  * Load Newsletters compatibility file.
  */

newspack-theme/inc/newspack-tag-labels.php

@@ -0,0 +1,119 @@
+<?php
+/**
+ * Newspack Tag Labels shim
+ *
+ * @package Newspack
+ */
+
+if ( ! function_exists( 'newspack_get_tag_labels' ) ) :
+	/**
+	 * Returns array of tag labels for the given post.
+	 *
+	 * @param int|WP_Post|null $post Post to check.
+	 *
+	 * @return array|null
+	 */
+	function newspack_get_tag_labels( $post = null ) {
+
+		if ( class_exists( '\Newspack\Tag_Labels' ) && method_exists( '\Newspack\Tag_Labels', 'get_labels_for_post' ) ) {
+			return \Newspack\Tag_Labels::get_labels_for_post( $post );
+		}
+
+		return null;
+	}
+endif;
+
+
+if ( ! function_exists( 'newspack_generate_tag_labels' ) ) :
+	/**
+	 * Generates HTML for given tag labels.
+	 *
+	 * @param array $labels Labels to display.
+	 * @param bool  $links  Whether to include links to tag archives.
+	 * @param array $outer_classes Classes to apply to the outer container.
+	 * @param array $inner_classes Classes to apply to the inner container.
+	 *
+	 * @return string       Tag labels as HTML.
+	 */
+	function newspack_generate_tag_labels( $labels = null, $links = true, $outer_classes = array( 'tag-labels' ), $inner_classes = array( 'tag-label', 'flag' ) ) {
+		if ( empty( $labels ) ) {
+			return '';
+		}
+
+		$labels_html  = '';
+		$labels_html .= '<span class="' . join( ' ', array_map( 'esc_attr', $outer_classes ) ) . '">';
+		foreach ( $labels as $label ) {
+			if ( $links && isset( $label['flag'] ) && $label['link'] ) {
+				$labels_html .= '<a class="' . join( ' ', array_map( 'esc_attr', $inner_classes ) ) . '" href="' . esc_url( $label['link'] ) . '" rel="tag">' . esc_html( $label['flag'] ) . '</a>';
+			} elseif ( isset( $label['flag'] ) ) {
+				$labels_html .= '<span class="' . join( ' ', array_map( 'esc_attr', $inner_classes ) ) . '">' . esc_html( $label['flag'] ) . '</span>';
+			}
+		}
+		$labels_html .= '</span><!-- .tag-labels -->';
+
+		return $labels_html;
+	}
+endif;
+
+if ( ! function_exists( 'newspack_display_tag_labels' ) ) :
+	/**
+	 * Outputs HTML for given tag labels.
+	 *
+	 * @param array $labels Labels to display.
+	 * @param bool  $links  Whether to include links to tag archives.
+	 *
+	 * @return null
+	 */
+	function newspack_display_tag_labels( $labels = null, $links = true ) {
+		if ( empty( $labels ) ) {
+			return null;
+		}
+
+		echo wp_kses_post( newspack_generate_tag_labels( $labels, $links, array( 'tag-labels', 'cat-links' ) ) . ' ' );
+
+		return null;
+	}
+endif;
+
+/**
+ * Adds label to post title where applicable.
+ *
+ * @param string $post_title Title of the post.
+ * @param int    $post_id    ID of the post.
+ *
+ * @return string
+ */
+function newspack_tag_labels_for_post_title( $post_title, $post_id ) {
+
+	// Apply title changes only to front/home views and non-singular views.
+	if ( ! class_exists( 'Newspack\Tag_Labels' ) || ( defined( 'WP_CLI' ) && WP_CLI ) || is_admin() || ( is_singular() && ! ( is_front_page() || is_home() ) ) ) {
+		return $post_title;
+	}
+
+	$labels = newspack_get_tag_labels( $post_id );
+	if ( empty( $labels ) ) {
+		return $post_title;
+	}
+
+	// Disable label links, as entire post title will be linked.
+	$labels_html = newspack_generate_tag_labels( $labels, false );
+
+	return $labels_html ? ( $labels_html . ' ' . $post_title ) : $post_title;
+}
+add_filter( 'the_title', 'newspack_tag_labels_for_post_title', 10, 2 );
+
+/**
+ * Enqueue styles.
+ */
+function newspack_tag_labels_enqueue_styles() {
+	if ( ( defined( 'WP_CLI' ) && WP_CLI ) || is_admin() || ! class_exists( 'Newspack\Tag_Labels' ) ) {
+		return;
+	}
+	wp_enqueue_style(
+		'newspack-tag-labels-style',
+		get_template_directory_uri() . '/styles/newspack-tag-labels.css',
+		array( 'newspack-style' ),
+		wp_get_theme()->get( 'Version' )
+	);
+}
+add_action( 'wp_enqueue_scripts', 'newspack_tag_labels_enqueue_styles' );

newspack-theme/sass/plugins/newspack-tag-labels.scss

@@ -0,0 +1,77 @@
+@use "../variables-site/variables-site";
+@use "../mixins/mixins-main";
+@use "../mixins/utilities";
+@use "../variables-site/structure";
+
+// Tag labels
+.tag-labels {
+	align-items: stretch;
+	display: inline-flex;
+	position: relative;
+
+	a,
+	a:visited {
+		color: #fff;
+		}
+
+	a:hover {
+		opacity: 0.8;
+	}
+}
+
+/* stylelint-disable selector-type-no-unknown  */
+.tag-labels,
+amp-script .tag-labels {
+	.tag-label {
+		background: var(--newspack-theme-color-highlight);
+		color: var(--newspack-theme-color-text-main);
+		line-height: 1;
+		padding: 0.3em 0.5em;
+		text-transform: uppercase;
+	}
+	.tag-label + .tag-label {
+		margin-left: 0.3em; // Don't collapse multiple labels.
+	}
+}
+/* stylelint-enable */
+
+/* Single Posts */
+.single {
+	// When categories are visible
+	.tag-labels {
+		display: inline-flex;
+	}
+	.tag-labels + .cat-links {
+		display: inline-block;
+		margin-left: 0.5em;
+	}
+
+	// Workaround margin override for featured images.
+	.featured-image-behind .cat-links.tag-labels a {
+		margin-right: 0.5em;
+	}
+}
+
+// Archives
+.search,
+.archive,
+.blog {
+	article {
+		.tag-labels {
+			display: inline-flex;
+			font-size: 65%;
+		}
+	}
+}
+
+.search article .tag-labels + .cat-links {
+	display: inline-block;
+}
+
+.tag-labels + .page-title {
+	&::before,
+	&::after,
+	.page-subtitle {
+		display: none;
+	}
+}