gutenberg / lib / experimental / dashboard-widgets / class-wp-widget-type.php

class-wp-widget-type.php in Gutenberg 24.1.0, at lib/experimental/dashboard-widgets/class-wp-widget-type.php

196 lines 5.1 KB

Raw Download Zip

1	<?php
2	/**
3	* Widget Types API: WP_Widget_Type class.
4	*
5	* @package gutenberg
6	*/
7
8	if ( ! class_exists( 'WP_Widget_Type' ) ) {
9
10	/**
11	* Internal class representing a widget type.
12	*
13	* Holds the metadata for a widget discovered by the build pipeline. Stored
14	* inside `WP_Widget_Type_Registry` once registered, and consumed by host
15	* code that needs to enumerate or look up widget types.
16	*
17	* The shape is intentionally minimal: identity (`name`) plus the
18	* script-module handles the build pipeline produced for the widget.
19	* Placement and host concerns (which page or sidebar uses the widget)
20	* live with the consumer, not on the type definition.
21	*/
22	#[AllowDynamicProperties]
23	class WP_Widget_Type {
24
25	/**
26	* Allowed values for the `presentation` field. Treated as the
27	* single source of truth across the registry, REST schema, and
28	* any consumer that needs to validate or enumerate the set.
29	*/
30	const PRESENTATION_VALUES = array( 'framed', 'content-bleed', 'full-bleed' );
31
32	/**
33	* Widget type key. Namespaced identifier, e.g. `core/hello-world`.
34	*
35	* @var string
36	*/
37	public $name;
38
39	/**
40	* Script-module handle for the widget render module.
41	*
42	* Null when the widget folder did not ship a render entry point at
43	* build time.
44	*
45	* @var string\|null
46	*/
47	public $render_module = null;
48
49	/**
50	* Script-module handle for the widget metadata module.
51	*
52	* Null when the widget folder did not ship a widget entry point at
53	* build time.
54	*
55	* @var string\|null
56	*/
57	public $widget_module = null;
58
59	/**
60	* Authoring intent about how the widget wants to render. Static
61	* and declarative; not a user-editable attribute.
62	*
63	* One of {@see self::PRESENTATION_VALUES} (first entry is the
64	* default). Null when the widget did not declare the field.
65	*
66	* @var string\|null
67	*/
68	public $presentation = null;
69
70	/**
71	* Widget types are grouped into categories to help users browse and
72	* discover them. Static and declarative; not a user-editable attribute.
73	*
74	* Null when the widget did not declare the field.
75	*
76	* @var string\|null
77	*/
78	public $category = null;
79
80	/**
81	* Human-readable title that names the widget type. Translated
82	* at registration time using the widget's text domain.
83	*
84	* Null when the widget did not declare the field.
85	*
86	* @var string\|null
87	*/
88	public $title = null;
89
90	/**
91	* Human-readable description of what the widget type does.
92	* Translated at registration time using the widget's text domain.
93	*
94	* Null when the widget did not declare the field.
95	*
96	* @var string\|null
97	*/
98	public $description = null;
99
100	/**
101	* Contextual help note: `content` plus optional `links`.
102	* Translated at registration time using the widget's text domain.
103	*
104	* Null when the widget did not declare the field.
105	*
106	* @var array\|null
107	*/
108	public $help = null;
109
110	/**
111	* Registered icon name (`collection/icon-name`), resolved by
112	* clients through the Icons API.
113	*
114	* Null when the widget did not declare the field.
115	*
116	* @var string\|null
117	*/
118	public $icon = null;
119
120	/**
121	* Declarative actions the widget exposes. Each entry carries `id`,
122	* `label`, `href`, and optional `download`/`openInNewTab`/`icon`/
123	* `relevance`. Labels are translated at registration time using the
124	* widget's text domain.
125	*
126	* Null when the widget did not declare the field.
127	*
128	* @var array\|null
129	*/
130	public $actions = null;
131
132	/**
133	* Attribute schema: the JSON-expressible subset of a DataViews
134	* `Field` per entry (`id`, `type`, `label`, `elements`, ...) plus an
135	* optional `relevance`. Labels, headers, descriptions, placeholders
136	* and option strings are translated at registration time using the
137	* widget's text domain.
138	*
139	* Null when the widget did not declare the field.
140	*
141	* @var array\|null
142	*/
143	public $attributes = null;
144
145	/**
146	* Alternative terms used to match the widget type when searching,
147	* e.g. "calendar" for an events widget. Translated at registration
148	* time using the widget's text domain.
149	*
150	* Null when the widget did not declare the field.
151	*
152	* @var string[]\|null
153	*/
154	public $keywords = null;
155
156	/**
157	* Constructor.
158	*
159	* @param string $name Widget type name including namespace.
160	* @param array $args Optional. Widget type arguments. Each key is
161	* copied onto the corresponding object property.
162	* Default empty array.
163	*/
164	public function __construct( $name, $args = array() ) {
165	$this->name = $name;
166	$this->set_props( $args );
167	}
168
169	/**
170	* Returns whether this widget type ships a renderable script module.
171	*
172	* @return bool
173	*/
174	public function is_renderable() {
175	return ! empty( $this->render_module );
176	}
177
178	/**
179	* Hydrates the widget type properties from the args array.
180	*
181	* @param array $args Widget type arguments.
182	*/
183	public function set_props( $args ) {
184	if ( ! is_array( $args ) ) {
185	return;
186	}
187
188	unset( $args['name'] );
189
190	foreach ( $args as $property_name => $property_value ) {
191	$this->$property_name = $property_value;
192	}
193	}
194	}
195	}
196