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

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

301 lines 9.9 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	$tag_name = $attributes['tagName'] ?? null;
156	if ( empty( $tag_name ) \|\| ! is_string( $tag_name ) \|\| tag_escape( $tag_name ) !== $tag_name ) {
157	$area_tag = 'div';
158	if ( $area_definition && isset( $area_definition['area_tag'] ) ) {
159	$area_tag = $area_definition['area_tag'];
160	}
161	$html_tag = $area_tag;
162	} else {
163	$html_tag = esc_attr( $attributes['tagName'] );
164	}
165	$wrapper_attributes = get_block_wrapper_attributes();
166
167	return "<$html_tag $wrapper_attributes>" . str_replace( ']]>', ']]>', $content ) . "</$html_tag>";
168	}
169
170	/**
171	* Returns an array of area variation objects for the template part block.
172	*
173	* @since 6.1.0
174	*
175	* @param array $instance_variations The variations for instances.
176	*
177	* @return array Array containing the block variation objects.
178	*/
179	function gutenberg_build_template_part_block_area_variations( $instance_variations ) {
180	$variations = array();
181	$defined_areas = get_allowed_block_template_part_areas();
182
183	foreach ( $defined_areas as $area ) {
184	if ( 'uncategorized' !== $area['area'] && 'navigation-overlay' !== $area['area'] ) {
185	$has_instance_for_area = false;
186	foreach ( $instance_variations as $variation ) {
187	if ( $variation['attributes']['area'] === $area['area'] ) {
188	$has_instance_for_area = true;
189	break;
190	}
191	}
192
193	$scope = $has_instance_for_area ? array() : array( 'inserter' );
194
195	$variations[] = array(
196	'name' => 'area_' . $area['area'],
197	'title' => $area['label'],
198	'description' => $area['description'],
199	'attributes' => array(
200	'area' => $area['area'],
201	),
202	'scope' => $scope,
203	'icon' => $area['icon'],
204	);
205	}
206	}
207	return $variations;
208	}
209
210	/**
211	* Returns an array of instance variation objects for the template part block
212	*
213	* @since 6.1.0
214	*
215	* @return array Array containing the block variation objects.
216	*/
217	function gutenberg_build_template_part_block_instance_variations() {
218	// Block themes are unavailable during installation.
219	if ( wp_installing() ) {
220	return array();
221	}
222
223	if ( ! current_theme_supports( 'block-templates' ) && ! current_theme_supports( 'block-template-parts' ) ) {
224	return array();
225	}
226
227	$variations = array();
228	$template_parts = get_block_templates(
229	array(
230	'post_type' => 'wp_template_part',
231	),
232	'wp_template_part'
233	);
234
235	$defined_areas = get_allowed_block_template_part_areas();
236	$icon_by_area = array_combine( array_column( $defined_areas, 'area' ), array_column( $defined_areas, 'icon' ) );
237
238	foreach ( $template_parts as $template_part ) {
239	// Navigation overlay template parts should not appear in the
240	// general inserter. They are managed through the Navigation
241	// block's overlay template part selector.
242	$scope = ( 'navigation-overlay' === $template_part->area )
243	? array()
244	: array( 'inserter' );
245
246	$variations[] = array(
247	'name' => 'instance_' . sanitize_title( $template_part->slug ),
248	'title' => $template_part->title,
249	// If there's no description for the template part don't show the
250	// block description. This is a bit hacky, but prevent the fallback
251	// by using a non-breaking space so that the value of description
252	// isn't falsey.
253	'description' => $template_part->description \|\| ' ',
254	'attributes' => array(
255	'slug' => $template_part->slug,
256	'theme' => $template_part->theme,
257	'area' => $template_part->area,
258	),
259	'scope' => $scope,
260	'icon' => $icon_by_area[ $template_part->area ] ?? null,
261	'example' => array(
262	'attributes' => array(
263	'slug' => $template_part->slug,
264	'theme' => $template_part->theme,
265	'area' => $template_part->area,
266	),
267	),
268	);
269	}
270	return $variations;
271	}
272
273	/**
274	* Returns an array of all template part block variations.
275	*
276	* @since 5.9.0
277	*
278	* @return array Array containing the block variation objects.
279	*/
280	function gutenberg_build_template_part_block_variations() {
281	$instance_variations = gutenberg_build_template_part_block_instance_variations();
282	$area_variations = gutenberg_build_template_part_block_area_variations( $instance_variations );
283	return array_merge( $area_variations, $instance_variations );
284	}
285
286	/**
287	* Registers the `core/template-part` block on the server.
288	*
289	* @since 5.9.0
290	*/
291	function gutenberg_register_block_core_template_part() {
292	register_block_type_from_metadata(
293	__DIR__ . '/template-part',
294	array(
295	'render_callback' => 'gutenberg_render_block_core_template_part',
296	'variation_callback' => 'gutenberg_build_template_part_block_variations',
297	)
298	);
299	}
300	add_action( 'init', 'gutenberg_register_block_core_template_part', 20 );
301