gutenberg / lib / widgets-api.php

widgets-api.php in Gutenberg 10.4.1, at lib/widgets-api.php

230 lines 5.9 KB

Raw Download Zip

1	<?php
2	/**
3	* Functions for working with widgets in WordPress. These should ultimately live
4	* in wp-includes/widgets.php, wp-admin/includes/widgets.php, etc. when merged
5	* to Core.
6	*
7	* @package gutenberg
8	*/
9
10	/**
11	* Assigns a widget to the given sidebar.
12	*
13	* Belongs in wp-includes/widgets.php when merged to Core.
14	*
15	* @since 10.2.0
16	*
17	* @param string $widget_id The widget id to assign.
18	* @param string $sidebar_id The sidebar id to assign to. If empty, the widget won't be added to any sidebar.
19	*/
20	function gutenberg_assign_widget_to_sidebar( $widget_id, $sidebar_id ) {
21	$sidebars = wp_get_sidebars_widgets();
22
23	foreach ( $sidebars as $maybe_sidebar_id => $widgets ) {
24	foreach ( $widgets as $i => $maybe_widget_id ) {
25	if ( $widget_id === $maybe_widget_id && $sidebar_id !== $maybe_sidebar_id ) {
26	unset( $sidebars[ $maybe_sidebar_id ][ $i ] );
27	// We could technically break 2 here, but continue looping in case the id is duplicated.
28	continue 2;
29	}
30	}
31	}
32
33	if ( $sidebar_id ) {
34	$sidebars[ $sidebar_id ][] = $widget_id;
35	}
36
37	wp_set_sidebars_widgets( $sidebars );
38	}
39
40	/**
41	* Finds the sidebar that a given widget belongs to.
42	*
43	* Belongs in wp-includes/widgets.php when merged to Core.
44	*
45	* @since 10.3.0
46	*
47	* @param string $widget_id The widget id to look for.
48	* @return string\|null The found sidebar's id, or null if it was not found.
49	*/
50	function gutenberg_find_widgets_sidebar( $widget_id ) {
51	foreach ( wp_get_sidebars_widgets() as $sidebar_id => $widget_ids ) {
52	foreach ( $widget_ids as $maybe_widget_id ) {
53	if ( $maybe_widget_id === $widget_id ) {
54	return (string) $sidebar_id;
55	}
56	}
57	}
58
59	return null;
60	}
61
62	/**
63	* Converts a widget ID into its id_base and number components.
64	*
65	* Belongs in wp-includes/widgets.php when merged to Core.
66	* WP_Customize_Widgets::parse_widget_id should then be deprecated.
67	*
68	* @since 10.2.0
69	*
70	* @param string $id Widget ID.
71	* @return array Array containing a widget's id_base and number components.
72	*/
73	function gutenberg_parse_widget_id( $id ) {
74	$parsed = array();
75
76	if ( preg_match( '/^(.+)-(\d+)$/', $id, $matches ) ) {
77	$parsed['id_base'] = $matches[1];
78	$parsed['number'] = (int) $matches[2];
79	} else {
80	// Likely an old single widget.
81	$parsed['id_base'] = $id;
82	}
83
84	return $parsed;
85	}
86
87	/**
88	* Calls the render callback of a widget and returns the output.
89	*
90	* Belongs in wp-includes/widgets.php when merged to Core. Some of the code in
91	* dynamic_sidebar() and WP_Customize_Widgets should then be DRYed up.
92	*
93	* @since 10.2.0
94	*
95	* @param string $widget_id Widget ID.
96	* @param string $sidebar_id Sidebar ID.
97	* @return string
98	*/
99	function gutenberg_render_widget( $widget_id, $sidebar_id ) {
100	global $wp_registered_widgets, $wp_registered_sidebars;
101
102	if ( ! isset( $wp_registered_widgets[ $widget_id ] ) ) {
103	return '';
104	}
105
106	if ( isset( $wp_registered_sidebars[ $sidebar_id ] ) ) {
107	$sidebar = $wp_registered_sidebars[ $sidebar_id ];
108	} elseif ( 'wp_inactive_widgets' === $sidebar_id ) {
109	$sidebar = array();
110	} else {
111	return '';
112	}
113
114	$params = array_merge(
115	array(
116	array_merge(
117	$sidebar,
118	array(
119	'widget_id' => $widget_id,
120	'widget_name' => $wp_registered_widgets[ $widget_id ]['name'],
121	)
122	),
123	),
124	(array) $wp_registered_widgets[ $widget_id ]['params']
125	);
126
127	// Substitute HTML `id` and `class` attributes into `before_widget`.
128	$classname_ = '';
129	foreach ( (array) $wp_registered_widgets[ $widget_id ]['classname'] as $cn ) {
130	if ( is_string( $cn ) ) {
131	$classname_ .= '_' . $cn;
132	} elseif ( is_object( $cn ) ) {
133	$classname_ .= '_' . get_class( $cn );
134	}
135	}
136	$classname_ = ltrim( $classname_, '_' );
137	$params[0]['before_widget'] = sprintf( $params[0]['before_widget'], $widget_id, $classname_ );
138
139	/** This filter is documented in wp-includes/widgets.php */
140	$params = apply_filters( 'dynamic_sidebar_params', $params );
141
142	$callback = $wp_registered_widgets[ $widget_id ]['callback'];
143
144	ob_start();
145
146	/** This filter is documented in wp-includes/widgets.php */
147	do_action( 'dynamic_sidebar', $wp_registered_widgets[ $widget_id ] );
148
149	if ( is_callable( $callback ) ) {
150	call_user_func_array( $callback, $params );
151	}
152
153	return ob_get_clean();
154	}
155
156	/**
157	* Calls the control callback of a widget and returns the output.
158	*
159	* Belongs in wp-admin/includes/widgets.php when merged to Core. Some of the
160	* code in wp_widget_control() should then be DRYed up.
161	*
162	* @since 10.2.0
163	*
164	* @param string $id Widget ID.
165	* @return string\|null
166	*/
167	function gutenberg_render_widget_control( $id ) {
168	global $wp_registered_widget_controls;
169
170	if ( ! isset( $wp_registered_widget_controls[ $id ]['callback'] ) ) {
171	return null;
172	}
173
174	$callback = $wp_registered_widget_controls[ $id ]['callback'];
175	$params = $wp_registered_widget_controls[ $id ]['params'];
176
177	ob_start();
178
179	if ( is_callable( $callback ) ) {
180	call_user_func_array( $callback, $params );
181	}
182
183	return ob_get_clean();
184	}
185
186	/**
187	* Returns the instance settings of the given widget. Must be a widget that
188	* is registered using WP_Widget.
189	*
190	* Belongs in WP_Widget when merged to Core.
191	*
192	* @since 10.2.0
193	*
194	* @param string $id Widget ID.
195	* @return array\|null
196	*/
197	function gutenberg_get_widget_instance( $id ) {
198	$parsed_id = gutenberg_parse_widget_id( $id );
199	$widget_object = gutenberg_get_widget_object( $parsed_id['id_base'] );
200
201	if ( ! isset( $parsed_id['number'] ) \|\| ! $widget_object ) {
202	return null;
203	}
204
205	$all_instances = $widget_object->get_settings();
206	return $all_instances[ $parsed_id['number'] ];
207	}
208
209	/**
210	* Returns the registered WP_Widget object for the given widget type.
211	*
212	* Belongs in WP_Widget_Factory when merged to Core.
213	*
214	* @since 10.2.0
215	*
216	* @param string $id_base Widget type ID.
217	* @return WP_Widget\|null
218	*/
219	function gutenberg_get_widget_object( $id_base ) {
220	global $wp_widget_factory;
221
222	foreach ( $wp_widget_factory->widgets as $widget_object ) {
223	if ( $widget_object->id_base === $id_base ) {
224	return $widget_object;
225	}
226	}
227
228	return null;
229	}
230