← All changes | modules/theme-tools/featured-content.php +364 -0 16.2-beta → 16.3 View file →

		@@ -1,0 +1,364 @@
	1	+<?php // phpcs:ignore WordPress.Files.FileName.InvalidClassFileName
	2	+/**
	3	+ * Theme Tools: functions for Featured Content enhancements.
	4	+ *
	5	+ * @package automattic/jetpack
	6	+ */
	7	+use Automattic\Jetpack\Status\Host;
	8	+
	9	+if ( ! class_exists( 'Featured_Content' ) && isset( $GLOBALS['pagenow'] ) && 'plugins.php' !== $GLOBALS['pagenow'] ) {
	10	+
	11	+ /**
	12	+ * Featured Content.
	13	+ *
	14	+ * This module will allow users to define a subset of posts to be displayed in a
	15	+ * theme-designated featured content area.
	16	+ *
	17	+ * This feature will only be activated for themes that declare that they support
	18	+ * it. This can be done by adding code similar to the following during the
	19	+ * "after_setup_theme" action:
	20	+ *
	21	+ * add_theme_support( 'featured-content', array(
	22	+ * 'filter' => 'mytheme_get_featured_content',
	23	+ * 'max_posts' => 20,
	24	+ * 'post_types' => array( 'post', 'page' ),
	25	+ * ) );
	26	+ *
	27	+ * For maximum compatibility with different methods of posting users will
	28	+ * designate a featured post tag to associate posts with. Since this tag now has
	29	+ * special meaning beyond that of a normal tags, users will have the ability to
	30	+ * hide it from the front-end of their site.
	31	+ *
	32	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	33	+ */
	34	+ class Featured_Content {
	35	+ /**
	36	+ * The maximum number of posts that a Featured Content area can contain. We
	37	+ * define a default value here but themes can override this by defining a
	38	+ * "max_posts" entry in the second parameter passed in the call to
	39	+ * add_theme_support( 'featured-content' ).
	40	+ *
	41	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	42	+ * @see Featured_Content::init()
	43	+ * @var int
	44	+ */
	45	+ public static $max_posts = 15;
	46	+
	47	+ /**
	48	+ * The registered post types supported by Featured Content. Themes can add
	49	+ * Featured Content support for registered post types by defining a
	50	+ * 'post_types' argument (string|array) in the call to
	51	+ * add_theme_support( 'featured-content' ).
	52	+ *
	53	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	54	+ * @see Featured_Content::init()
	55	+ * @var array
	56	+ */
	57	+ public static $post_types = array( 'post' );
	58	+
	59	+ /**
	60	+ * The tag that is used to mark featured content. Users can define
	61	+ * a custom tag name that will be stored in this variable.
	62	+ *
	63	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	64	+ * @see Featured_Content::hide_featured_term
	65	+ * @var string
	66	+ */
	67	+ public static $tag;
	68	+
	69	+ /**
	70	+ * Instantiate.
	71	+ *
	72	+ * All custom functionality will be hooked into the "init" action.
	73	+ *
	74	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	75	+ */
	76	+ public static function setup() {
	77	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content::setup' );
	78	+ Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::setup();
	79	+ }
	80	+
	81	+ /**
	82	+ * Conditionally hook into WordPress.
	83	+ *
	84	+ * Themes must declare that they support this module by adding
	85	+ * add_theme_support( 'featured-content' ); during after_setup_theme.
	86	+ *
	87	+ * If no theme support is found there is no need to hook into WordPress. We'll
	88	+ * just return early instead.
	89	+ *
	90	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	91	+ *
	92	+ * @uses Featured_Content::$max_posts
	93	+ */
	94	+ public static function init() {
	95	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\init' );
	96	+ return Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::init();
	97	+ }
	98	+
	99	+ /**
	100	+ * Hide "featured" tag from the front-end.
	101	+ *
	102	+ * Has to run on wp_loaded so that the preview filters of the customizer
	103	+ * have a chance to alter the value.
	104	+ *
	105	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	106	+ */
	107	+ public static function wp_loaded() {
	108	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\wp_loaded' );
	109	+ return Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::wp_loaded();
	110	+ }
	111	+
	112	+ /**
	113	+ * Get featured posts
	114	+ *
	115	+ * This method is not intended to be called directly. Theme developers should
	116	+ * place a filter directly in their theme and then pass its name as a value of
	117	+ * the "filter" key in the array passed as the $args parameter during the call
	118	+ * to: add_theme_support( 'featured-content', $args ).
	119	+ *
	120	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	121	+ * @uses Featured_Content::get_featured_post_ids()
	122	+ *
	123	+ * @return array
	124	+ */
	125	+ public static function get_featured_posts() {
	126	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\get_featured_posts' );
	127	+ return Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::get_featured_posts();
	128	+ }
	129	+
	130	+ /**
	131	+ * Get featured post IDs
	132	+ *
	133	+ * This function will return the an array containing the post IDs of all
	134	+ * featured posts.
	135	+ *
	136	+ * Sets the "featured_content_ids" transient.
	137	+ *
	138	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	139	+ * @return array Array of post IDs.
	140	+ */
	141	+ public static function get_featured_post_ids() {
	142	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\get_featured_post_ids' );
	143	+ return Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::get_featured_post_ids();
	144	+ }
	145	+
	146	+ /**
	147	+ * Delete Transient.
	148	+ *
	149	+ * Hooks in the "save_post" action.
	150	+ *
	151	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	152	+ * @see Featured_Content::validate_settings().
	153	+ */
	154	+ public static function delete_transient() {
	155	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\delete_transient' );
	156	+ Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::delete_transient();
	157	+ }
	158	+
	159	+ /**
	160	+ * Flush the Post Tag relationships cache.
	161	+ *
	162	+ * Hooks in the "update_option_featured-content" action.
	163	+ *
	164	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	165	+ * @param array $prev Previous option data.
	166	+ * @param array $opts New option data.
	167	+ */
	168	+ public static function flush_post_tag_cache( $prev, $opts ) {
	169	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\flush_post_tag_cache' );
	170	+ Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::flush_post_tag_cache( $prev, $opts );
	171	+ }
	172	+
	173	+ /**
	174	+ * Exclude featured posts from the blog query when the blog is the front-page,
	175	+ * and user has not checked the "Also display tagged posts outside the Featured Content area" checkbox.
	176	+ *
	177	+ * Filter the home page posts, and remove any featured post ID's from it.
	178	+ * Hooked onto the 'pre_get_posts' action, this changes the parameters of the
	179	+ * query before it gets any posts.
	180	+ *
	181	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	182	+ * @uses Featured_Content::get_featured_post_ids();
	183	+ * @uses Featured_Content::get_setting();
	184	+ * @param WP_Query $query WP_Query object.
	185	+ * @return WP_Query Possibly modified WP_Query
	186	+ */
	187	+ public static function pre_get_posts( $query ) {
	188	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\pre_get_posts' );
	189	+
	190	+ return Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::pre_get_posts( $query );
	191	+ }
	192	+
	193	+ /**
	194	+ * Reset tag option when the saved tag is deleted.
	195	+ *
	196	+ * It's important to mention that the transient needs to be deleted, too.
	197	+ * While it may not be obvious by looking at the function alone, the transient
	198	+ * is deleted by Featured_Content::validate_settings().
	199	+ *
	200	+ * Hooks in the "delete_post_tag" action.
	201	+ *
	202	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	203	+ * @see Featured_Content::validate_settings().
	204	+ *
	205	+ * @param int $tag_id The term_id of the tag that has been deleted.
	206	+ * @return void
	207	+ */
	208	+ public static function delete_post_tag( $tag_id ) {
	209	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\delete_post_tag' );
	210	+ Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::delete_post_tag( $tag_id );
	211	+ }
	212	+
	213	+ /**
	214	+ * Hide featured tag from displaying when global terms are queried from
	215	+ * the front-end.
	216	+ *
	217	+ * Hooks into the "get_terms" filter.
	218	+ *
	219	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	220	+ * @uses Featured_Content::get_setting()
	221	+ *
	222	+ * @param array $terms A list of term objects. This is the return value of get_terms().
	223	+ * @param array $taxonomies An array of taxonomy slugs.
	224	+ * @param array $args Array of get_terms() arguments.
	225	+ * @return array $terms
	226	+ */
	227	+ public static function hide_featured_term( $terms, $taxonomies, $args ) {
	228	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\hide_featured_term' );
	229	+
	230	+ return Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::hide_featured_term( $terms, $taxonomies, $args );
	231	+ }
	232	+
	233	+ /**
	234	+ * Hide featured tag from displaying when terms associated with a post object
	235	+ * are queried from the front-end.
	236	+ *
	237	+ * Hooks into the "get_the_terms" filter.
	238	+ *
	239	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	240	+ * @uses Featured_Content::get_setting()
	241	+ *
	242	+ * @param \WP_Term[]|\WP_Error $terms A list of term objects. This is the return value of get_the_terms().
	243	+ * @param int $id The ID field for the post object that terms are associated with.
	244	+ * @param string $taxonomy The slug of the taxonomy.
	245	+ * @return \WP_Term[]|\WP_Error $terms
	246	+ */
	247	+ public static function hide_the_featured_term( $terms, $id, $taxonomy ) {
	248	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\hide_the_featured_term' );
	249	+
	250	+ return Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::hide_the_featured_term( $terms, $id, $taxonomy );
	251	+ }
	252	+
	253	+ /**
	254	+ * Register custom setting on the Settings -> Reading screen.
	255	+ *
	256	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	257	+ * @uses Featured_Content::render_form()
	258	+ * @uses Featured_Content::validate_settings()
	259	+ *
	260	+ * @return void
	261	+ */
	262	+ public static function register_setting() {
	263	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\register_setting' );
	264	+ Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::register_setting();
	265	+ }
	266	+
	267	+ /**
	268	+ * Add settings to the Customizer.
	269	+ *
	270	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	271	+ * @param WP_Customize_Manager $wp_customize Theme Customizer object.
	272	+ */
	273	+ public static function customize_register( $wp_customize ) {
	274	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\customize_register' );
	275	+ Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::customize_register( $wp_customize );
	276	+ }
	277	+
	278	+ /**
	279	+ * Enqueue the tag suggestion script.
	280	+ *
	281	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	282	+ */
	283	+ public static function enqueue_scripts() {
	284	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\enqueue_scripts' );
	285	+ Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::enqueue_scripts();
	286	+ }
	287	+
	288	+ /**
	289	+ * Renders all form fields on the Settings -> Reading screen.
	290	+ *
	291	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	292	+ */
	293	+ public static function render_form() {
	294	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\render_form' );
	295	+ Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::render_form();
	296	+ }
	297	+
	298	+ /**
	299	+ * Get settings
	300	+ *
	301	+ * Get all settings recognized by this module. This function will return all
	302	+ * settings whether or not they have been stored in the database yet. This
	303	+ * ensures that all keys are available at all times.
	304	+ *
	305	+ * In the event that you only require one setting, you may pass its name as the
	306	+ * first parameter to the function and only that value will be returned.
	307	+ *
	308	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	309	+ * @param string $key The key of a recognized setting.
	310	+ * @return mixed Array of all settings by default. A single value if passed as first parameter.
	311	+ */
	312	+ public static function get_setting( $key = 'all' ) {
	313	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\get_setting' );
	314	+ return Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::get_setting( $key );
	315	+ }
	316	+
	317	+ /**
	318	+ * Validate settings
	319	+ *
	320	+ * Make sure that all user supplied content is in an expected format before
	321	+ * saving to the database. This function will also delete the transient set in
	322	+ * Featured_Content::get_featured_content().
	323	+ *
	324	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	325	+ * @uses Featured_Content::delete_transient()
	326	+ *
	327	+ * @param array $input Array of settings input.
	328	+ * @return array $output
	329	+ */
	330	+ public static function validate_settings( $input ) {
	331	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\validate_settings' );
	332	+ return Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::validate_settings( $input );
	333	+ }
	334	+
	335	+ /**
	336	+ * Removes the quantity setting from the options array.
	337	+ *
	338	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	339	+ * @return void
	340	+ */
	341	+ public static function switch_theme() {
	342	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\switch_theme' );
	343	+ Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::switch_theme();
	344	+ }
	345	+
	346	+ /**
	347	+ * Update Featured Content term data as necessary when a shared term is split.
	348	+ *
	349	+ * @deprecated 13.6 Moved to Classic Theme Helper package.
	350	+ * @param int $old_term_id ID of the formerly shared term.
	351	+ * @param int $new_term_id ID of the new term created for the $term_taxonomy_id.
	352	+ * @param int $term_taxonomy_id ID for the term_taxonomy row affected by the split.
	353	+ * @param string $taxonomy Taxonomy for the split term.
	354	+ */
	355	+ public static function jetpack_update_featured_content_for_split_terms( $old_term_id, $new_term_id, $term_taxonomy_id, $taxonomy ) {
	356	+ _deprecated_function( __METHOD__, 'jetpack-13.6', 'Automattic\\Jetpack\\Classic_Theme_Helper\\Featured_Content\\jetpack_update_featured_content_for_split_terms' );
	357	+ Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::jetpack_update_featured_content_for_split_terms( $old_term_id, $new_term_id, $term_taxonomy_id, $taxonomy );
	358	+ }
	359	+ }
	360	+
	361	+ if ( ! ( new Host() )->is_wpcom_platform() ) {
	362	+ Automattic\Jetpack\Classic_Theme_Helper\Featured_Content::setup();
	363	+ }
	364	+}