jetpack
/
jetpack_vendor
/
automattic
/
jetpack-premium-analytics
/
src
/
class-dashboard-section.php
REST
2 weeks ago
Reports
1 week ago
Sync
2 weeks ago
class-analytics.php
3 days ago
class-capabilities.php
2 weeks ago
class-connection-configuration.php
2 weeks ago
class-dashboard-section-registry.php
2 weeks ago
class-dashboard-section.php
3 days ago
class-dashboard-support-routes.php
1 week ago
class-jetpack-stats-tracker.php
2 weeks ago
class-notices.php
2 weeks ago
class-widget-type-registry.php
2 weeks ago
class-widget-type.php
2 weeks ago
class-woocommerce-analytics-tracker.php
2 weeks ago
csv-exports.php
2 weeks ago
dashboard-grammar.php
2 weeks ago
dashboard-layout.php
3 days ago
dashboard-sections.php
3 days ago
rest-namespace.php
2 weeks ago
videopress-availability.php
3 days ago
widget-availability.php
3 days ago
widget-i18n.json
2 weeks ago
widget-modules.php
3 days ago
widget-type-support.php
3 days ago
widget-types.php
2 weeks ago
class-dashboard-section.php
259 lines
| 1 | <?php |
| 2 | /** |
| 3 | * Dashboard Sections API: Dashboard_Section class. |
| 4 | * |
| 5 | * @package automattic/jetpack-premium-analytics |
| 6 | */ |
| 7 | |
| 8 | namespace Automattic\Jetpack\PremiumAnalytics; |
| 9 | |
| 10 | /** |
| 11 | * Represents a dashboard section. |
| 12 | * |
| 13 | * A dashboard section is the server-owned model behind a top-level dashboard |
| 14 | * tab. It carries display metadata plus availability and default-layout |
| 15 | * callbacks that can be extended by consumers. |
| 16 | */ |
| 17 | final class Dashboard_Section { |
| 18 | |
| 19 | /** |
| 20 | * Date-filter surface offering the rolling date-range picker (today, last 7 |
| 21 | * days, a custom range, …) plus the comparison control. The default. |
| 22 | * |
| 23 | * @since 0.2.0 |
| 24 | * @var string |
| 25 | */ |
| 26 | const DATE_FILTER_RANGE = 'range'; |
| 27 | |
| 28 | /** |
| 29 | * Date-filter surface offering all time plus one entry per calendar year, |
| 30 | * for sections whose data is read as whole history rather than as a |
| 31 | * rolling window. |
| 32 | * |
| 33 | * @since 0.2.0 |
| 34 | * @var string |
| 35 | */ |
| 36 | const DATE_FILTER_YEAR = 'year'; |
| 37 | |
| 38 | /** |
| 39 | * Date-filter surfaces a section may declare. |
| 40 | * |
| 41 | * @since 0.2.0 |
| 42 | * @var string[] |
| 43 | */ |
| 44 | const DATE_FILTERS = array( self::DATE_FILTER_RANGE, self::DATE_FILTER_YEAR ); |
| 45 | |
| 46 | /** |
| 47 | * Dashboard identifier. |
| 48 | * |
| 49 | * @var string |
| 50 | */ |
| 51 | public $dashboard_name; |
| 52 | |
| 53 | /** |
| 54 | * Section identifier. |
| 55 | * |
| 56 | * @var string |
| 57 | */ |
| 58 | public $id; |
| 59 | |
| 60 | /** |
| 61 | * URL-facing section slug, derived from the identifier. |
| 62 | * |
| 63 | * @var string |
| 64 | */ |
| 65 | public $slug; |
| 66 | |
| 67 | /** |
| 68 | * Display label, naming the section's tab. |
| 69 | * |
| 70 | * @var string |
| 71 | */ |
| 72 | public $label; |
| 73 | |
| 74 | /** |
| 75 | * Section heading, deliberately distinct from the tab label: the tab reads |
| 76 | * `Traffic` where the heading reads `Site traffic`. Null falls back to the label. |
| 77 | * |
| 78 | * @since 0.3.0 |
| 79 | * @var string|null |
| 80 | */ |
| 81 | public $title = null; |
| 82 | |
| 83 | /** |
| 84 | * Section description, shown as the page subtitle while this section is active. |
| 85 | * |
| 86 | * @since 0.3.0 |
| 87 | * @var string|null |
| 88 | */ |
| 89 | public $description = null; |
| 90 | |
| 91 | /** |
| 92 | * Sort order. |
| 93 | * |
| 94 | * @var int |
| 95 | */ |
| 96 | public $order = 10; |
| 97 | |
| 98 | /** |
| 99 | * Which date filter the section's header offers, as one of self::DATE_FILTERS. |
| 100 | * |
| 101 | * @since 0.2.0 |
| 102 | * @var string |
| 103 | */ |
| 104 | public $date_filter = self::DATE_FILTER_RANGE; |
| 105 | |
| 106 | /** |
| 107 | * Which optional controls the section's date filter offers. |
| 108 | * |
| 109 | * @since 0.3.0 |
| 110 | * @var array |
| 111 | */ |
| 112 | public $date_filter_options = array( |
| 113 | 'with_date_comparison' => true, |
| 114 | ); |
| 115 | |
| 116 | /** |
| 117 | * Availability flag or callback. |
| 118 | * |
| 119 | * @var bool|callable |
| 120 | */ |
| 121 | private $is_available = true; |
| 122 | |
| 123 | /** |
| 124 | * Default layout array or callback. |
| 125 | * |
| 126 | * @var array|callable |
| 127 | */ |
| 128 | private $default_layout = array(); |
| 129 | |
| 130 | /** |
| 131 | * Constructor. |
| 132 | * |
| 133 | * @param string $dashboard_name Dashboard identifier. |
| 134 | * @param string $id Section identifier. |
| 135 | * @param array $args Optional. Section arguments. |
| 136 | */ |
| 137 | public function __construct( $dashboard_name, $id, $args = array() ) { |
| 138 | $this->dashboard_name = $dashboard_name; |
| 139 | $this->id = $id; |
| 140 | $this->slug = self::derive_slug( $id ); |
| 141 | $this->label = $id; |
| 142 | |
| 143 | $this->set_props( $args ); |
| 144 | } |
| 145 | |
| 146 | /** |
| 147 | * Derives the URL-facing slug from a namespaced section identifier. |
| 148 | * |
| 149 | * @param string $id Section identifier, e.g. `analytics/traffic`. |
| 150 | * @return string The segment after the namespace, e.g. `traffic`. |
| 151 | */ |
| 152 | private static function derive_slug( $id ) { |
| 153 | $separator = strpos( (string) $id, '/' ); |
| 154 | |
| 155 | return false === $separator ? (string) $id : substr( $id, $separator + 1 ); |
| 156 | } |
| 157 | |
| 158 | /** |
| 159 | * Returns whether this section should be exposed. |
| 160 | * |
| 161 | * @return bool |
| 162 | */ |
| 163 | public function is_available() { |
| 164 | if ( is_callable( $this->is_available ) ) { |
| 165 | return (bool) call_user_func( $this->is_available, $this ); |
| 166 | } |
| 167 | |
| 168 | return (bool) $this->is_available; |
| 169 | } |
| 170 | |
| 171 | /** |
| 172 | * Returns the section's default widget layout. |
| 173 | * |
| 174 | * @return array Array of widget instances. |
| 175 | */ |
| 176 | public function get_default_layout() { |
| 177 | $layout = is_callable( $this->default_layout ) |
| 178 | ? call_user_func( $this->default_layout, $this ) |
| 179 | : $this->default_layout; |
| 180 | |
| 181 | return is_array( $layout ) ? array_values( $layout ) : array(); |
| 182 | } |
| 183 | |
| 184 | /** |
| 185 | * Returns the public REST representation. |
| 186 | * |
| 187 | * @return array |
| 188 | */ |
| 189 | public function to_array() { |
| 190 | return array( |
| 191 | 'id' => $this->id, |
| 192 | 'slug' => $this->slug, |
| 193 | 'label' => $this->label, |
| 194 | 'title' => $this->title, |
| 195 | 'description' => $this->description, |
| 196 | 'order' => (int) $this->order, |
| 197 | 'date_filter' => $this->date_filter, |
| 198 | 'date_filter_options' => $this->date_filter_options, |
| 199 | 'default_layout' => $this->get_default_layout(), |
| 200 | ); |
| 201 | } |
| 202 | |
| 203 | /** |
| 204 | * Hydrates section properties from the args array. |
| 205 | * |
| 206 | * @param array $args Section arguments. |
| 207 | * @return void |
| 208 | */ |
| 209 | private function set_props( $args ) { |
| 210 | if ( ! is_array( $args ) ) { |
| 211 | return; |
| 212 | } |
| 213 | |
| 214 | if ( isset( $args['label'] ) ) { |
| 215 | $this->label = (string) $args['label']; |
| 216 | } |
| 217 | |
| 218 | // An empty string is a registrant saying "none", not a heading: kept as-is it |
| 219 | // would defeat the label fallback and render an `<h2>` with no accessible name. |
| 220 | if ( isset( $args['title'] ) ) { |
| 221 | $title = (string) $args['title']; |
| 222 | $this->title = '' === $title ? null : $title; |
| 223 | } |
| 224 | |
| 225 | if ( isset( $args['description'] ) ) { |
| 226 | $description = (string) $args['description']; |
| 227 | $this->description = '' === $description ? null : $description; |
| 228 | } |
| 229 | |
| 230 | if ( isset( $args['order'] ) ) { |
| 231 | $this->order = (int) $args['order']; |
| 232 | } |
| 233 | |
| 234 | // An unrecognized surface keeps the default rather than reaching the |
| 235 | // dashboard, where the frontend has no filter to render for it. |
| 236 | if ( isset( $args['date_filter'] ) && in_array( $args['date_filter'], self::DATE_FILTERS, true ) ) { |
| 237 | $this->date_filter = (string) $args['date_filter']; |
| 238 | } |
| 239 | |
| 240 | // Merged over the defaults so a partial array keeps the rest, and narrowed |
| 241 | // to the known options, which is all the dashboard renders. |
| 242 | if ( isset( $args['date_filter_options'] ) && is_array( $args['date_filter_options'] ) ) { |
| 243 | $options = array_merge( $this->date_filter_options, $args['date_filter_options'] ); |
| 244 | |
| 245 | $this->date_filter_options = array( |
| 246 | 'with_date_comparison' => (bool) $options['with_date_comparison'], |
| 247 | ); |
| 248 | } |
| 249 | |
| 250 | if ( array_key_exists( 'is_available', $args ) ) { |
| 251 | $this->is_available = $args['is_available']; |
| 252 | } |
| 253 | |
| 254 | if ( array_key_exists( 'default_layout', $args ) ) { |
| 255 | $this->default_layout = $args['default_layout']; |
| 256 | } |
| 257 | } |
| 258 | } |
| 259 |