jetpack / jetpack_vendor / automattic / jetpack-premium-analytics / src / dashboard-layout.php

dashboard-layout.php in Jetpack – WP Security, Backup, Speed, & Growth 16.3-a.7, at jetpack_vendor/automattic/jetpack-premium-analytics/src/dashboard-layout.php

131 lines 4.0 KB

Raw Download Zip

1	<?php
2	/**
3	* Dashboard Layout: the default-layout primitives shared by the section API and its registrants.
4	*
5	* A section declares its default layout when it registers, and
6	* Dashboard_Section::get_default_layout() runs it through DASHBOARD_DEFAULT_LAYOUT_FILTER: the
7	* package drops the widget types the site cannot serve there, and a plugin may add its own
8	* instances to any section.
9	*
10	* @package automattic/jetpack-premium-analytics
11	*/
12
13	namespace Automattic\Jetpack\PremiumAnalytics;
14
15	// Availability policy for default layout instances: defaults are read outside
16	// the widget registry bootstrap, so the policy must be loaded here explicitly.
17	require_once __DIR__ . '/widget-type-support.php';
18
19	/**
20	* Identifier of the Premium Analytics dashboard, formatted as `<plugin>_<page>`
21	* to match the underscore form produced by the wp-build pipeline. Used as the
22	* `{name}` segment of the sections REST route.
23	*/
24	const DASHBOARD_NAME = 'jetpack-premium-analytics_dashboard';
25
26	/**
27	* Filter through which a section's default layout is resolved. Documented where it
28	* runs, in Dashboard_Section::get_default_layout().
29	*/
30	const DASHBOARD_DEFAULT_LAYOUT_FILTER = 'jetpack_premium_analytics_dashboard_default_layout';
31
32	/**
33	* Builds a widget instance for a section's default layout.
34	*
35	* @param string $uuid Widget instance UUID.
36	* @param string $type Widget type.
37	* @param int $order Widget placement order.
38	* @param int $width Widget placement width.
39	* @param int $height Widget placement height.
40	* @param array $attributes Optional widget attributes.
41	* @return array Widget instance.
42	*/
43	function get_dashboard_default_widget_instance(
44	$uuid,
45	$type,
46	$order,
47	$width = 1,
48	$height = 1,
49	$attributes = array()
50	) {
51	$widget = array(
52	'uuid' => $uuid,
53	'type' => $type,
54	);
55
56	if ( ! empty( $attributes ) ) {
57	$widget['attributes'] = $attributes;
58	}
59
60	$widget['placement'] = array(
61	'width' => $width,
62	'height' => $height,
63	'order' => $order,
64	);
65
66	return $widget;
67	}
68
69	/**
70	* Drops the widget instances the site cannot serve from a section's default layout.
71	*
72	* A persisted layout keeps such an instance as a removable ghost widget; a default must not
73	* seed one. Hooked late, after the callbacks that add instances, so it covers those too.
74	*
75	* @param array $layout Default widget instances.
76	* @return array The layout minus the unsupported instances.
77	*/
78	function remove_unsupported_default_layout_items( $layout ) {
79	$layout = remove_unsupported_widget_items(
80	is_array( $layout ) ? $layout : array(),
81	'type',
82	get_widget_support_context()
83	);
84
85	return remove_unregistered_default_layout_items( $layout );
86	}
87	add_filter( DASHBOARD_DEFAULT_LAYOUT_FILTER, __NAMESPACE__ . '\\remove_unsupported_default_layout_items', 100 );
88
89	/**
90	* Drops the widget instances whose type the widget type registry does not know.
91	*
92	* Only once the registry can answer: after `init`, with the widget type API loaded and at least
93	* one type registered. Before that, or on a checkout without a build, the default stays as
94	* declared rather than emptying itself.
95	*
96	* @since 0.9.0
97	*
98	* @param array $layout Default widget instances.
99	* @return array The layout minus the instances of unregistered types.
100	*/
101	function remove_unregistered_default_layout_items( $layout ) {
102	if ( ! did_action( 'init' ) \|\| ! function_exists( __NAMESPACE__ . '\\ensure_widget_registry_ready' ) ) {
103	return $layout;
104	}
105
106	ensure_widget_registry_ready();
107	$registered = Widget_Type_Registry::get_instance()->get_all_registered();
108	if ( empty( $registered ) ) {
109	return $layout;
110	}
111
112	return array_values(
113	array_filter(
114	$layout,
115	static function ( $item ) use ( $registered ) {
116	return ! is_array( $item ) \|\| isset( $registered[ $item['type'] ?? '' ] );
117	}
118	)
119	);
120	}
121
122	/**
123	* No-op kept for older copies of the package: they guard their include of this file on this
124	* symbol and call it from boot_routes(), so a newer copy loading first must still define it.
125	*
126	* @since 0.8.0 Registers nothing; the route it registered is gone.
127	*
128	* @return void
129	*/
130	function register_dashboard_default_layout_route() {}
131