gutenberg / build / scripts / block-library / template-part.php

template-part.php in Gutenberg 23.6.2, at build/scripts/block-library/template-part.php

300 lines 9.8 KB

Raw Download Zip

1	<?php
2	/**
3	* Server-side rendering of the `core/template-part` block.
4	*
5	* @package WordPress
6	*/
7
8	/**
9	* Renders the `core/template-part` block on the server.
10	*
11	* @since 5.9.0
12	*
13	* @global WP_Embed $wp_embed WordPress Embed object.
14	*
15	* @param array $attributes The block attributes.
16	*
17	* @return string The render.
18	*/
19	function gutenberg_render_block_core_template_part( $attributes ) {
20	static $seen_ids = array();
21
22	$template_part_id = null;
23	$content = null;
24	$area = WP_TEMPLATE_PART_AREA_UNCATEGORIZED;
25	$theme = $attributes['theme'] ?? get_stylesheet();
26
27	if ( isset( $attributes['slug'] ) && get_stylesheet() === $theme ) {
28	$template_part_id = $theme . '//' . $attributes['slug'];
29	$template_part_query = new WP_Query(
30	array(
31	'post_type' => 'wp_template_part',
32	'post_status' => 'publish',
33	'post_name__in' => array( $attributes['slug'] ),
34	'tax_query' => array(
35	array(
36	'taxonomy' => 'wp_theme',
37	'field' => 'name',
38	'terms' => $theme,
39	),
40	),
41	'posts_per_page' => 1,
42	'no_found_rows' => true,
43	'lazy_load_term_meta' => false, // Do not lazy load term meta, as template parts only have one term.
44	)
45	);
46	$template_part_post = $template_part_query->have_posts() ? $template_part_query->next_post() : null;
47	if ( $template_part_post ) {
48	// A published post might already exist if this template part was customized elsewhere
49	// or if it's part of a customized template.
50	$block_template = _build_block_template_result_from_post( $template_part_post );
51	$content = $block_template->content;
52	if ( isset( $block_template->area ) ) {
53	$area = $block_template->area;
54	}
55	/**
56	* Fires when a block template part is loaded from a template post stored in the database.
57	*
58	* @since 5.9.0
59	*
60	* @param string $template_part_id The requested template part namespaced to the theme.
61	* @param array $attributes The block attributes.
62	* @param WP_Post $template_part_post The template part post object.
63	* @param string $content The template part content.
64	*/
65	do_action( 'render_block_core_template_part_post', $template_part_id, $attributes, $template_part_post, $content );
66	} else {
67	$template_part_file_path = '';
68	// Else, if the template part was provided by the active theme,
69	// render the corresponding file content.
70	if ( 0 === validate_file( $attributes['slug'] ) ) {
71	$block_template = get_block_file_template( $template_part_id, 'wp_template_part' );
72
73	if ( isset( $block_template->content ) ) {
74	$content = $block_template->content;
75	}
76	if ( isset( $block_template->area ) ) {
77	$area = $block_template->area;
78	}
79
80	// Needed for the `render_block_core_template_part_file` and `render_block_core_template_part_none` actions below.
81	$block_template_file = _get_block_template_file( 'wp_template_part', $attributes['slug'] );
82	if ( $block_template_file ) {
83	$template_part_file_path = $block_template_file['path'];
84	}
85	}
86
87	if ( '' !== $content && null !== $content ) {
88	/**
89	* Fires when a block template part is loaded from a template part in the theme.
90	*
91	* @since 5.9.0
92	*
93	* @param string $template_part_id The requested template part namespaced to the theme.
94	* @param array $attributes The block attributes.
95	* @param string $template_part_file_path Absolute path to the template path.
96	* @param string $content The template part content.
97	*/
98	do_action( 'render_block_core_template_part_file', $template_part_id, $attributes, $template_part_file_path, $content );
99	} else {
100	/**
101	* Fires when a requested block template part does not exist in the database nor in the theme.
102	*
103	* @since 5.9.0
104	*
105	* @param string $template_part_id The requested template part namespaced to the theme.
106	* @param array $attributes The block attributes.
107	* @param string $template_part_file_path Absolute path to the not found template path.
108	*/
109	do_action( 'render_block_core_template_part_none', $template_part_id, $attributes, $template_part_file_path );
110	}
111	}
112	}
113
114	// WP_DEBUG_DISPLAY must only be honored when WP_DEBUG. This precedent
115	// is set in `wp_debug_mode()`.
116	$is_debug = WP_DEBUG && WP_DEBUG_DISPLAY;
117
118	if ( is_null( $content ) ) {
119	if ( $is_debug && isset( $attributes['slug'] ) ) {
120	return sprintf(
121	/* translators: %s: Template part slug. */
122	__( 'Template part has been deleted or is unavailable: %s' ),
123	$attributes['slug']
124	);
125	}
126
127	return '';
128	}
129
130	if ( isset( $seen_ids[ $template_part_id ] ) ) {
131	return $is_debug ?
132	// translators: Visible only in the front end, this warning takes the place of a faulty block.
133	__( '[block rendering halted]' ) :
134	'';
135	}
136
137	// Look up area definition.
138	$area_definition = null;
139	$defined_areas = get_allowed_block_template_part_areas();
140	foreach ( $defined_areas as $defined_area ) {
141	if ( $defined_area['area'] === $area ) {
142	$area_definition = $defined_area;
143	break;
144	}
145	}
146
147	// If $area is not allowed, set it back to the uncategorized default.
148	if ( ! $area_definition ) {
149	$area = WP_TEMPLATE_PART_AREA_UNCATEGORIZED;
150	}
151
152	// Run through the actions that are typically taken on the_content.
153	$content = _wp_apply_block_content_filters( $content, "template_part_{$area}", $seen_ids, $template_part_id );
154
155	if ( empty( $attributes['tagName'] ) \|\| tag_escape( $attributes['tagName'] ) !== $attributes['tagName'] ) {
156	$area_tag = 'div';
157	if ( $area_definition && isset( $area_definition['area_tag'] ) ) {
158	$area_tag = $area_definition['area_tag'];
159	}
160	$html_tag = $area_tag;
161	} else {
162	$html_tag = esc_attr( $attributes['tagName'] );
163	}
164	$wrapper_attributes = get_block_wrapper_attributes();
165
166	return "<$html_tag $wrapper_attributes>" . str_replace( ']]>', ']]>', $content ) . "</$html_tag>";
167	}
168
169	/**
170	* Returns an array of area variation objects for the template part block.
171	*
172	* @since 6.1.0
173	*
174	* @param array $instance_variations The variations for instances.
175	*
176	* @return array Array containing the block variation objects.
177	*/
178	function gutenberg_build_template_part_block_area_variations( $instance_variations ) {
179	$variations = array();
180	$defined_areas = get_allowed_block_template_part_areas();
181
182	foreach ( $defined_areas as $area ) {
183	if ( 'uncategorized' !== $area['area'] && 'navigation-overlay' !== $area['area'] ) {
184	$has_instance_for_area = false;
185	foreach ( $instance_variations as $variation ) {
186	if ( $variation['attributes']['area'] === $area['area'] ) {
187	$has_instance_for_area = true;
188	break;
189	}
190	}
191
192	$scope = $has_instance_for_area ? array() : array( 'inserter' );
193
194	$variations[] = array(
195	'name' => 'area_' . $area['area'],
196	'title' => $area['label'],
197	'description' => $area['description'],
198	'attributes' => array(
199	'area' => $area['area'],
200	),
201	'scope' => $scope,
202	'icon' => $area['icon'],
203	);
204	}
205	}
206	return $variations;
207	}
208
209	/**
210	* Returns an array of instance variation objects for the template part block
211	*
212	* @since 6.1.0
213	*
214	* @return array Array containing the block variation objects.
215	*/
216	function gutenberg_build_template_part_block_instance_variations() {
217	// Block themes are unavailable during installation.
218	if ( wp_installing() ) {
219	return array();
220	}
221
222	if ( ! current_theme_supports( 'block-templates' ) && ! current_theme_supports( 'block-template-parts' ) ) {
223	return array();
224	}
225
226	$variations = array();
227	$template_parts = get_block_templates(
228	array(
229	'post_type' => 'wp_template_part',
230	),
231	'wp_template_part'
232	);
233
234	$defined_areas = get_allowed_block_template_part_areas();
235	$icon_by_area = array_combine( array_column( $defined_areas, 'area' ), array_column( $defined_areas, 'icon' ) );
236
237	foreach ( $template_parts as $template_part ) {
238	// Navigation overlay template parts should not appear in the
239	// general inserter. They are managed through the Navigation
240	// block's overlay template part selector.
241	$scope = ( 'navigation-overlay' === $template_part->area )
242	? array()
243	: array( 'inserter' );
244
245	$variations[] = array(
246	'name' => 'instance_' . sanitize_title( $template_part->slug ),
247	'title' => $template_part->title,
248	// If there's no description for the template part don't show the
249	// block description. This is a bit hacky, but prevent the fallback
250	// by using a non-breaking space so that the value of description
251	// isn't falsey.
252	'description' => $template_part->description \|\| ' ',
253	'attributes' => array(
254	'slug' => $template_part->slug,
255	'theme' => $template_part->theme,
256	'area' => $template_part->area,
257	),
258	'scope' => $scope,
259	'icon' => $icon_by_area[ $template_part->area ] ?? null,
260	'example' => array(
261	'attributes' => array(
262	'slug' => $template_part->slug,
263	'theme' => $template_part->theme,
264	'area' => $template_part->area,
265	),
266	),
267	);
268	}
269	return $variations;
270	}
271
272	/**
273	* Returns an array of all template part block variations.
274	*
275	* @since 5.9.0
276	*
277	* @return array Array containing the block variation objects.
278	*/
279	function gutenberg_build_template_part_block_variations() {
280	$instance_variations = gutenberg_build_template_part_block_instance_variations();
281	$area_variations = gutenberg_build_template_part_block_area_variations( $instance_variations );
282	return array_merge( $area_variations, $instance_variations );
283	}
284
285	/**
286	* Registers the `core/template-part` block on the server.
287	*
288	* @since 5.9.0
289	*/
290	function gutenberg_register_block_core_template_part() {
291	register_block_type_from_metadata(
292	__DIR__ . '/template-part',
293	array(
294	'render_callback' => 'gutenberg_render_block_core_template_part',
295	'variation_callback' => 'gutenberg_build_template_part_block_variations',
296	)
297	);
298	}
299	add_action( 'init', 'gutenberg_register_block_core_template_part', 20 );
300