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

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

161 lines 4.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	* Alternative terms used to match the widget type when searching,
112	* e.g. "calendar" for an events widget. Translated at registration
113	* time using the widget's text domain.
114	*
115	* Null when the widget did not declare the field.
116	*
117	* @var string[]\|null
118	*/
119	public $keywords = null;
120
121	/**
122	* Constructor.
123	*
124	* @param string $name Widget type name including namespace.
125	* @param array $args Optional. Widget type arguments. Each key is
126	* copied onto the corresponding object property.
127	* Default empty array.
128	*/
129	public function __construct( $name, $args = array() ) {
130	$this->name = $name;
131	$this->set_props( $args );
132	}
133
134	/**
135	* Returns whether this widget type ships a renderable script module.
136	*
137	* @return bool
138	*/
139	public function is_renderable() {
140	return ! empty( $this->render_module );
141	}
142
143	/**
144	* Hydrates the widget type properties from the args array.
145	*
146	* @param array $args Widget type arguments.
147	*/
148	public function set_props( $args ) {
149	if ( ! is_array( $args ) ) {
150	return;
151	}
152
153	unset( $args['name'] );
154
155	foreach ( $args as $property_name => $property_value ) {
156	$this->$property_name = $property_value;
157	}
158	}
159	}
160	}
161