Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00%
0 / 8
0.00%
0 / 3
 CRAP
0.00%
0 / 1
Widget_Type
0.00%
0 / 8
0.00%
0 / 3
 30
0.00%
0 / 1
 __construct
0.00%
0 / 2
0.00%
0 / 1
 2
 is_renderable
0.00%
0 / 1
0.00%
0 / 1
 2
 set_props
0.00%
0 / 5
0.00%
0 / 1
 12
1<?php
2/**
3 * Widget Types API: Widget_Type class.
4 *
5 * Premium Analytics ships its own copy of the dashboard widget-type registry
6 * (the core/Gutenberg version lives behind an experimental flag and is not
7 * available in stable WordPress). PA-namespaced so it never collides with a
8 * future core API.
9 *
10 * @package automattic/jetpack-premium-analytics
11 */
12
13namespace Automattic\Jetpack\PremiumAnalytics;
14
15/**
16 * Represents a single dashboard widget type.
17 *
18 * Holds the metadata for a widget discovered by the build pipeline. Stored
19 * inside Widget_Type_Registry once registered, and consumed by host code that
20 * needs to enumerate or look up widget types.
21 *
22 * The shape is intentionally minimal: identity (`name`) plus the script-module
23 * handles the build pipeline produced for the widget. Placement and host
24 * concerns (which page or sidebar uses the widget) live with the consumer, not
25 * on the type definition.
26 */
27#[\AllowDynamicProperties]
28class Widget_Type {
29
30    /**
31     * Allowed values for the `presentation` field. Treated as the single
32     * source of truth across the registry, REST response, and any consumer
33     * that needs to validate or enumerate the set.
34     */
35    const PRESENTATION_VALUES = array( 'framed', 'content-bleed', 'full-bleed' );
36
37    /**
38     * Widget type key. Namespaced identifier, e.g. `jpa/hello-world`.
39     *
40     * @var string
41     */
42    public $name;
43
44    /**
45     * Script-module handle for the widget render module.
46     *
47     * Null when the widget folder did not ship a render entry point at build
48     * time.
49     *
50     * @var string|null
51     */
52    public $render_module = null;
53
54    /**
55     * Script-module handle for the widget metadata module.
56     *
57     * Null when the widget folder did not ship a widget entry point at build
58     * time.
59     *
60     * @var string|null
61     */
62    public $widget_module = null;
63
64    /**
65     * Authoring intent about how the widget wants to render. Static and
66     * declarative; not a user-editable attribute.
67     *
68     * One of {@see self::PRESENTATION_VALUES} (first entry is the default).
69     * Null when the widget did not declare the field.
70     *
71     * @var string|null
72     */
73    public $presentation = null;
74
75    /**
76     * Widget types are grouped into categories to help users browse and
77     * discover them. Static and declarative; not a user-editable attribute.
78     *
79     * Null when the widget did not declare the field.
80     *
81     * @var string|null
82     */
83    public $category = null;
84
85    /**
86     * Human-readable title that names the widget type. Translated
87     * at registration time using the widget's text domain.
88     *
89     * Null when the widget did not declare the field.
90     *
91     * @var string|null
92     */
93    public $title = null;
94
95    /**
96     * Human-readable description of what the widget type does.
97     * Translated at registration time using the widget's text domain.
98     *
99     * Null when the widget did not declare the field.
100     *
101     * @var string|null
102     */
103    public $description = null;
104
105    /**
106     * Contextual help note: `content` plus optional `links`.
107     * Translated at registration time using the widget's text domain.
108     *
109     * Null when the widget did not declare the field.
110     *
111     * @var array|null
112     */
113    public $help = null;
114
115    /**
116     * Alternative terms used to match the widget type when searching,
117     * e.g. "calendar" for an events widget. Translated at registration
118     * time using the widget's text domain.
119     *
120     * Null when the widget did not declare the field.
121     *
122     * @var string[]|null
123     */
124    public $keywords = null;
125
126    /**
127     * Constructor.
128     *
129     * @param string $name Widget type name including namespace.
130     * @param array  $args Optional. Widget type arguments. Each key is copied
131     *                     onto the corresponding object property. Default empty
132     *                     array.
133     */
134    public function __construct( $name, $args = array() ) {
135        $this->name = $name;
136        $this->set_props( $args );
137    }
138
139    /**
140     * Returns whether this widget type ships a renderable script module.
141     *
142     * @return bool
143     */
144    public function is_renderable() {
145        return ! empty( $this->render_module );
146    }
147
148    /**
149     * Hydrates the widget type properties from the args array.
150     *
151     * @param array $args Widget type arguments.
152     */
153    public function set_props( $args ) {
154        if ( ! is_array( $args ) ) {
155            return;
156        }
157
158        unset( $args['name'] );
159
160        foreach ( $args as $property_name => $property_value ) {
161            $this->$property_name = $property_value;
162        }
163    }
164}