feat(collections): add hierarchical fields (#4051)

Author: rbcorrales

includes/collections/README.md

@@ -44,31 +44,47 @@ The Collections system is built around a custom post type (`newspack_collection`
 
 ## Backend components
 
-### 1. Anatomy of a collection
+### Anatomy of a collection
 
 A collection is a post of the `newspack_collection` CPT and a term of the `newspack_collection_taxonomy` at the same time. Both entities are linked together and share the same name.
 
 A post is assigned to a collection via the `newspack_collection_taxonomy` taxonomy. Posts can also be organized in the `newspack_collection_section` taxonomy. When visiting the Collections page (single template for the collection CPT), posts will be listed and organized by the Sections taxonomy.
 
 The collections themselves can also be categorized using the `newspack_collection_category` taxonomy. This will allow us to not only have one archive to list all the collections, but additional archives for each Collection category.
 
-### 2. Collection custom post type ([`class-post-type.php`](class-post-type.php))
+### Global settings ([`class-settings.php`](class-settings.php))
+
+Collections can be configured globally via the Newspack settings.
+The following nested options are available as properties of the `newspack_collections_settings` option array:
+
+| Setting | Type | Description | Format |
+|---------|------|-------------|--------|
+| `custom_naming_enabled` | Boolean | Enable custom naming for collections | Boolean |
+| `custom_name` | String | Custom plural name for collections. Only affects the reader-facing nomenclature | Text (e.g., "Issues") |
+| `custom_singular_name` | String | Custom singular name for collections. Only affects the reader-facing nomenclature | Text (e.g., "Issue") |
+| `custom_slug` | String | Custom URL slug for collections. | Text (e.g., "issue") |
+| `subscribe_link` | String | Global subscription URL displayed on collection pages | Valid URL |
+| `order_link` | String | Global order URL for purchasing physical copies | Valid URL |
+
+The `subscribe_link` and `order_link` settings provide defaults that can be overridden at the collection category level (via term meta) or collection level (via post meta).
+
+### Collection custom post type ([`class-post-type.php`](class-post-type.php))
 - Defined as a `newspack_collection` CPT.
 - Supports: `title`, `editor`, `thumbnail`, `custom-fields`, and `page-attributes`.
 - Includes custom ordering functionality via `menu_order`.
 - Provides admin interface customizations.
 
-### 3. Collection post meta fields ([`class-collection-meta.php`](class-collection-meta.php))
+### Collection post meta fields ([`class-collection-meta.php`](class-collection-meta.php))
 
 The following table details all available meta fields for collections:
 
 | Meta Field | Type | Description | Format |
-|------------|------|-------------|---------|
+|------------|------|-------------|--------|
 | `newspack_collection_volume` | String | Collection volume information | Text (e.g., "IV") |
 | `newspack_collection_number` | String | Collection number | Text (e.g., "#22") |
 | `newspack_collection_period` | String | Collection period | Text (e.g., "Spring 2025") |
-| `newspack_collection_subscribe_link` | String | A link to subscribe that will be displayed as a button on the collection page | Valid URL |
-| `newspack_collection_order_link` | String | A link to order the physical version of that collection | Valid URL |
+| `newspack_collection_subscribe_link` | String | Override global/category subscription link for this specific collection | Valid URL |
+| `newspack_collection_order_link` | String | Override global/category order link for this specific collection | Valid URL |
 | `newspack_collection_ctas` | Array | An array of CTAs (Call-to-Action buttons) | Array of objects with `label`, `type`, `id` and `url` properties |
 
 Sample `newspack_collection_ctas` post meta structure:
@@ -89,36 +105,50 @@ Sample `newspack_collection_ctas` post meta structure:
 
 Where `type` can either be `link` or `attachment`, and `id` is the attachment ID.
 
-### 4. Data management ([`class-enqueuer.php`](class-enqueuer.php))
+### Data management ([`class-enqueuer.php`](class-enqueuer.php))
 - Manages JavaScript data localization.
 - Provides a common interface for adding/retrieving collection data dynamically.
 - Dynamically handles styles and scripts enqueuing in a single place if data is localized and passed to the frontend.
 
-### 5. Taxonomies
+### Taxonomies
 The system includes multiple taxonomy classes for organizing collections:
 
 #### Collection category taxonomy ([`class-collection-category-taxonomy.php`](class-collection-category-taxonomy.php))
 - Taxonomy name: `newspack_collection_category`.
 - Non-hierarchical taxonomy for categorizing collections.
 - Similar to WordPress post categories.
+- Term meta fields:
+
+| Meta Field | Type | Description | Format |
+|------------|------|-------------|--------|
+| `newspack_collection_subscribe_link` | String | Override global subscription link for the current collection category | Valid URL |
+| `newspack_collection_order_link` | String | Override global order link for the current collection category | Valid URL |
 
 #### Collection section taxonomy ([`class-collection-section-taxonomy.php`](class-collection-section-taxonomy.php))
 - Taxonomy name: `newspack_collection_section`.
 - Non-hierarchical taxonomy for categorizing posts into sections.
 - Similar to WordPress tags.
 - Adds a new "Section" column to the post list.
-- Order is stored in the term meta `newspack_collection_section_order`.
+- Term meta fields:
+
+| Meta Field | Type | Description | Format |
+|------------|------|-------------|--------|
+| `newspack_collection_section_order` | Integer | Order of the section | Integer |
 
 #### Collection taxonomy ([`class-collection-taxonomy.php`](class-collection-taxonomy.php))
 - Taxonomy name: `newspack_collection_taxonomy`.
-- Special internal taxonomy (`newspack_collection_taxonomy`) for associating collections with posts.
+- Special internal taxonomy for associating collections with posts.
 - It's a copy of the collection post title and slug to allow regular posts to be tagged with collections.
 - Not publicly queryable.
 - Hidden from the admin UI.
 - Adds a new "Collection" column to the post list.
-- Terms can be deactivated via an internal `_newspack_collection_inactive` term meta. Used when trashing posts, as terms don't manage status.
+- Term meta fields:
+
+| Meta Field | Type | Description | Format |
+|------------|------|-------------|--------|
+| `_newspack_collection_inactive` | Boolean | Internal. Whether the section is inactive. Used when trashing posts, as terms don't manage status. | Boolean |
 
-### 6. Synchronization ([`class-sync.php`](class-sync.php))
+### Synchronization ([`class-sync.php`](class-sync.php))
 - Handles synchronization of collection posts and collection terms.
 - Ensures data consistency across objects using a two-way meta relationship:
   - For posts, link via `_newspack_collection_term_id` internal post meta.
@@ -135,9 +165,11 @@ Term edited    -> Post edited (copy title and slug)
 Term deleted   -> Post trashed (to prevent data loss)
 ```
 
-### 7. Post meta fields ([`class-post-meta.php`](class-post-meta.php))
-- Meta key: `newspack_order_in_collection`.
-- Used for storing the post order in collection.
+### Post meta fields ([`class-post-meta.php`](class-post-meta.php))
+
+| Meta Field | Type | Description | Format |
+|------------|------|-------------|--------|
+| `newspack_order_in_collection` | Integer | Order of the post in a collection | Integer |
 
 ## Frontend components
 

includes/collections/class-collection-category-taxonomy.php

@@ -17,28 +17,78 @@
 class Collection_Category_Taxonomy {
 
 	/**
-	 * Taxonomy for Collection Categories.
+	 * Taxonomy and term meta prefix.
 	 *
 	 * @var string
 	 */
-	private const TAXONOMY = 'newspack_collection_category';
+	public const PREFIX = 'newspack_collection_';
 
 	/**
 	 * Get the taxonomy for Collection Categories.
 	 *
 	 * @return string The taxonomy name.
 	 */
 	public static function get_taxonomy() {
-		return self::TAXONOMY;
+		return self::PREFIX . 'category';
+	}
+
+	/**
+	 * Get meta keys.
+	 *
+	 * @return array {
+	 *     Array of term meta definitions.
+	 *
+	 *     @type string $type              The type of data associated with this meta key.
+	 *     @type string $label             A human-readable label of the data attached to this meta key.
+	 *     @type string $description       A description of the data attached to this meta key.
+	 *     @type bool   $single            Whether the meta key has one value per object, or an array of values per object.
+	 *     @type string $sanitize_callback A function or method to call when sanitizing `$meta_key` data.
+	 *     @type array  $show_in_rest      Show in REST configuration.
+	 * }
+	 */
+	public static function get_metas() {
+		return [
+			'subscribe_link' => [
+				'type'              => 'string',
+				'label'             => __( 'Subscription URL', 'newspack-plugin' ),
+				'description'       => __( 'Override the global subscription link for this category.', 'newspack-plugin' ),
+				'single'            => true,
+				'sanitize_callback' => 'esc_url_raw',
+				'show_in_rest'      => [
+					'schema' => [
+						'format' => 'uri',
+					],
+				],
+			],
+			'order_link'     => [
+				'type'              => 'string',
+				'label'             => __( 'Order URL', 'newspack-plugin' ),
+				'description'       => __( 'Override the global order link for this category.', 'newspack-plugin' ),
+				'single'            => true,
+				'sanitize_callback' => 'esc_url_raw',
+				'show_in_rest'      => [
+					'schema' => [
+						'format' => 'uri',
+					],
+				],
+			],
+		];
 	}
 
 	/**
 	 * Initialize the taxonomy handler.
 	 */
 	public static function init() {
 		add_action( 'init', [ __CLASS__, 'register_taxonomy' ] );
+		add_action( 'init', [ __CLASS__, 'register_term_meta' ] );
 		add_action( 'newspack_collections_before_flush_rewrites', [ __CLASS__, 'register_taxonomy' ] );
 		add_action( 'manage_' . Post_Type::get_post_type() . '_posts_columns', [ __CLASS__, 'set_taxonomy_column_name' ] );
+
+		// Term meta field handling.
+		add_action( self::get_taxonomy() . '_add_form_fields', [ __CLASS__, 'add_term_meta_fields' ] );
+		add_action( self::get_taxonomy() . '_edit_form_fields', [ __CLASS__, 'edit_term_meta_fields' ] );
+		add_action( 'created_' . self::get_taxonomy(), [ __CLASS__, 'save_term_meta' ] );
+		add_action( 'edited_' . self::get_taxonomy(), [ __CLASS__, 'save_term_meta' ] );
 	}
 
 	/**
@@ -89,4 +139,104 @@ public static function set_taxonomy_column_name( $posts_columns ) {
 
 		return $posts_columns;
 	}
+
+	/**
+	 * Add meta columns to the taxonomy edit screen.
+	 *
+	 * @param array $columns An associative array of column headings.
+	 * @return array The modified columns array.
+	 */
+	public static function add_meta_columns( $columns ) {
+		foreach ( self::get_metas() as $key => $meta ) {
+			$columns[ self::PREFIX . $key ] = $meta['label'];
+		}
+		return $columns;
+	}
+
+	/**
+	 * Register meta fields for the collection category taxonomy.
+	 */
+	public static function register_term_meta() {
+		foreach ( self::get_metas() as $key => $meta ) {
+			register_term_meta(
+				self::get_taxonomy(),
+				self::PREFIX . $key,
+				array_merge(
+					$meta,
+					[
+						'auth_callback' => [ __CLASS__, 'auth_callback' ],
+					]
+				)
+			);
+		}
+	}
+
+	/**
+	 * Add term meta fields to the add term form.
+	 */
+	public static function add_term_meta_fields() {
+		foreach ( self::get_metas() as $key => $meta ) {
+			$meta_key = self::PREFIX . $key;
+			?>
+			<div class="form-field">
+				<label for="<?php echo esc_attr( $meta_key ); ?>"><?php echo esc_html( $meta['label'] ); ?></label>
+				<input type="url" name="<?php echo esc_attr( $meta_key ); ?>" id="<?php echo esc_attr( $meta_key ); ?>" value="" />
+				<p class="description"><?php echo esc_html( $meta['description'] ); ?></p>
+			</div>
+			<?php
+		}
+	}
+
+	/**
+	 * Add term meta fields to the edit term form.
+	 *
+	 * @param WP_Term $term Current taxonomy term object.
+	 */
+	public static function edit_term_meta_fields( $term ) {
+		foreach ( self::get_metas() as $key => $meta ) {
+			$meta_key = self::PREFIX . $key;
+			$value    = get_term_meta( $term->term_id, $meta_key, true );
+			?>
+			<tr class="form-field">
+				<th scope="row">
+					<label for="<?php echo esc_attr( $meta_key ); ?>"><?php echo esc_html( $meta['label'] ); ?></label>
+				</th>
+				<td>
+					<input type="url" name="<?php echo esc_attr( $meta_key ); ?>" id="<?php echo esc_attr( $meta_key ); ?>" value="<?php echo esc_attr( $value ); ?>" />
+					<p class="description"><?php echo esc_html( $meta['description'] ); ?></p>
+				</td>
+			</tr>
+			<?php
+		}
+	}
+
+	/**
+	 * Save the term meta when term is created or updated.
+	 *
+	 * @param int $term_id Term ID.
+	 */
+	public static function save_term_meta( $term_id ) {
+		// phpcs:disable WordPress.Security.NonceVerification.Missing, WordPress.Security.ValidatedSanitizedInput.InputNotSanitized
+		foreach ( self::get_metas() as $key => $meta ) {
+			$meta_key = self::PREFIX . $key;
+			if ( isset( $_POST[ $meta_key ] ) ) {
+				$value = $meta['sanitize_callback']( $_POST[ $meta_key ] );
+				if ( $value ) {
+					update_term_meta( $term_id, $meta_key, $value );
+				} else {
+					delete_term_meta( $term_id, $meta_key );
+				}
+			}
+		}
+		// phpcs:enable WordPress.Security.NonceVerification.Missing, WordPress.Security.ValidatedSanitizedInput.InputNotSanitized
+	}
+
+	/**
+	 * Auth callback for term meta fields.
+	 *
+	 * @return bool Whether the user can manage categories.
+	 */
+	public static function auth_callback() {
+		return current_user_can( 'manage_categories' );
+	}
 }

includes/collections/class-settings.php

@@ -28,6 +28,7 @@ class Settings {
 		'custom_singular_name'  => '',
 		'custom_slug'           => '',
 		'subscribe_link'        => '',
+		'order_link'            => '',
 	];
 
 	/**
@@ -110,6 +111,10 @@ public static function get_rest_args() {
 				'required'          => false,
 				'sanitize_callback' => 'esc_url_raw',
 			],
+			'order_link'            => [
+				'required'          => false,
+				'sanitize_callback' => 'esc_url_raw',
+			],
 		];
 	}
 

src/wizards/newspack/views/settings/collections/custom-naming-card.tsx

@@ -20,7 +20,7 @@ const CustomNamingCard: React.FC< CustomNamingCardProps > = ( { settings, isSavi
 		hasGreyHeader={ !! settings.custom_naming_enabled }
 	>
 		{ settings.custom_naming_enabled && (
-			<Grid columns={ 1 } gutter={ 24 }>
+			<Grid columns={ 2 } gutter={ 24 }>
 				<TextControl
 					label={ __( 'Name', 'newspack-plugin' ) }
 					help={ __( 'Name to be used instead of "Collections" (e.g., "Issues", "Magazines")', 'newspack-plugin' ) }

src/wizards/newspack/views/settings/collections/index.tsx

@@ -23,6 +23,7 @@ const DEFAULT_COLLECTIONS_SETTINGS: CollectionsSettingsData = {
 	custom_singular_name: '',
 	custom_slug: '',
 	subscribe_link: '',
+	order_link: '',
 };
 
 // Helper function to extract collection settings from API data with defaults.
@@ -91,14 +92,27 @@ function Collections() {
 				<>
 					<CustomNamingCard settings={ settings } isSaving={ isSavingSettings } onChange={ updateSetting } />
 
-					<Grid columns={ 1 } gutter={ 32 }>
+					<Grid columns={ 2 } gutter={ 32 }>
 						<TextControl
 							label={ __( 'Subscription URL', 'newspack-plugin' ) }
-							help={ __( 'Global URL where readers can subscribe to collections.', 'newspack-plugin' ) }
+							help={ __(
+								'URL for the "Subscribe" button that will be displayed in the Collections archive pages when no subscription URL is set for the Collection or its parent category.',
+								'newspack-plugin'
+							) }
 							value={ settings.subscribe_link }
 							onChange={ ( value: string ) => updateSetting( 'subscribe_link', value ) }
 							placeholder={ `e.g., https://${ window.location.hostname }/subscribe` }
 						/>
+						<TextControl
+							label={ __( 'Order URL', 'newspack-plugin' ) }
+							help={ __(
+								'URL for the "Order" button that will be displayed in the Collections archive pages when no order URL is set for the Collection or its parent category.',
+								'newspack-plugin'
+							) }
+							value={ settings.order_link }
+							onChange={ ( value: string ) => updateSetting( 'order_link', value ) }
+							placeholder={ `e.g., https://${ window.location.hostname }/order` }
+						/>
 					</Grid>
 
 					<div className="newspack-buttons-card">

src/wizards/newspack/views/settings/collections/types.d.ts

@@ -6,9 +6,7 @@ type CollectionsSettingsData = {
 	custom_singular_name: string;
 	custom_slug: string;
 	subscribe_link: string;
+	order_link: string;
 };
 
-type FieldChangeHandler< T > = < K extends keyof T >(
-	key: K,
-	value: T[ K ]
-) => void;
+type FieldChangeHandler< T > = < K extends keyof T >( key: K, value: T[ K ] ) => void;