jetpack / modules / theme-tools / featured-content.php

featured-content.php in Jetpack – WP Security, Backup, Speed, & Growth 16.2, at modules/theme-tools/featured-content.php

365 lines 14.5 KB

Raw Download Zip

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	}
365