Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
Significance: minor
Type: added

Widgets: Carry the attributes a widget.json declares through the registry to the dashboard.
48 changes: 33 additions & 15 deletions projects/packages/premium-analytics/docs/dashboard-widgets.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,17 @@ This page covers the registration path. Sections, which place widget instances i

## Vocabulary

| Term | Meaning | Example |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| Widget type name | Namespaced identifier, `<namespace>/<name>`, lowercase. The namespace names the owner. | `jpa/clicks`, `wordads/highlights` |
| Field type name | Namespaced identifier a widget attribute names by `type`; the dashboard registers the definition and renders the control. | `jpa/toggle-group` |
| Render module, widget module | The script-module ids of the widget's render entry and metadata entry, which the client `import()`s through the page import map. | `jetpack-premium-analytics/widgets/clicks/render` |
| Manifest | The widgets wp-build discovered under `widgets/`, generated into `build/widgets.php` and read through `jpa_get_registered_widget_modules()`. | see `Analytics::widget_manifest_path()` |
| Candidate | A manifest entry before the registry-time filter. A dropped candidate never registers. | `jetpack_premium_analytics_registrable_widget_types` |
| Metadata | `presentation`, `category`, `title`, `description`, `help`, `icon`, `actions`, `keywords`: what the picker shows, translated and sanitized on the way into the registry. | see `Widget_Type` |
| Catalog location | `textdomain` and `i18n_manifest`: the text domain the widget's bundles are stamped with, and the i18n manifest of the build that serves them. | see `Widget_Type` |
| SDK | `@automattic/jetpack-premium-analytics-sdk`: the one name a plugin's widgets import the dashboard through. | `projects/js-packages/premium-analytics-sdk` |
| Term | Meaning | Example |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Widget type name | Namespaced identifier, `<namespace>/<name>`, lowercase. The namespace names the owner. | `jpa/clicks`, `wordads/highlights` |
| Field type name | Namespaced identifier a widget attribute names by `type`; the dashboard registers the definition and renders the control. | `jpa/toggle-group` |
| Render module, widget module | The script-module ids of the widget's render entry and metadata entry, which the client `import()`s through the page import map. | `jetpack-premium-analytics/widgets/clicks/render` |
| Manifest | The widgets wp-build discovered under `widgets/`, generated into `build/widgets.php` and read through `jpa_get_registered_widget_modules()`. | see `Analytics::widget_manifest_path()` |
| Candidate | A manifest entry before the registry-time filter. A dropped candidate never registers. | `jetpack_premium_analytics_registrable_widget_types` |
| Metadata | `presentation`, `category`, `title`, `description`, `help`, `icon`, `actions`, `attributes`, `keywords`: what the picker shows and the settings it offers, translated and sanitized on the way into the registry. | see `Widget_Type` |
| Attribute | One setting of a widget instance: a DataViews field in its JSON form, plus the keys the dashboard reads on top of a field (`relevance`, so far). An element names its `icon` by reference. | `attributes` in `widget.json` |
| Catalog location | `textdomain` and `i18n_manifest`: the text domain the widget's bundles are stamped with, and the i18n manifest of the build that serves them. | see `Widget_Type` |
| SDK | `@automattic/jetpack-premium-analytics-sdk`: the one name a plugin's widgets import the dashboard through. | `projects/js-packages/premium-analytics-sdk` |

## Files

Expand Down Expand Up @@ -55,7 +56,7 @@ A read before `init` is a `_doing_it_wrong()`. It answers only what was register

`register_widget_types()` in `src/widget-types.php` registers them from a callback on the action at priority 10, into the registry the action hands over.

Each manifest candidate that survives `jetpack_premium_analytics_registrable_widget_types` is translated by `translate_widget_metadata()`, sanitized (`help`, `icon`, `actions`) and registered. A name already registered is skipped.
Each manifest candidate that survives `jetpack_premium_analytics_registrable_widget_types` is translated by `translate_widget_metadata()`, sanitized (`help`, `icon`, `actions`, `attributes`) and registered. A name already registered is skipped.

### A plugin's widgets

Expand Down Expand Up @@ -114,7 +115,7 @@ The action hands over the `Widget_Type_Registry` being hydrated. `register_widge

### What the manifest helper does

It runs the candidates through `jetpack_premium_analytics_registrable_widget_types`, gives each one without a `textdomain` or an `i18n_manifest` the ones passed in `$args`, translates the metadata with `translate_widget_metadata()`, sanitizes `help`, `icon` and `actions`, and skips a name already registered.
It runs the candidates through `jetpack_premium_analytics_registrable_widget_types`, gives each one without a `textdomain` or an `i18n_manifest` the ones passed in `$args`, translates the metadata with `translate_widget_metadata()`, sanitizes `help`, `icon`, `actions` and `attributes`, and skips a name already registered.

The package's own `register_widget_types()` is its first caller, with its text domain and no manifest: the page's boot init module loads the package's catalogs.

Expand All @@ -128,9 +129,9 @@ The name must be a lowercase `<namespace>/<name>` string, and must not be regist

### Arguments

Any public property of `Widget_Type`: `render_module`, `widget_module`, `presentation` (`framed`, `content-bleed` or `full-bleed`), `category`, `title`, `description`, `help` (`content` plus optional `links`), `icon` (`collection/name`), `actions`, `keywords`, `textdomain`, `i18n_manifest`, `former_names`, `plan_feature`. `set_props()` copies every key onto the instance.
Any public property of `Widget_Type`: `render_module`, `widget_module`, `presentation` (`framed`, `content-bleed` or `full-bleed`), `category`, `title`, `description`, `help` (`content` plus optional `links`), `icon` (`collection/name`), `actions`, `attributes` (one entry per setting, see [Vocabulary](#vocabulary)), `keywords`, `textdomain`, `i18n_manifest`, `former_names`, `plan_feature`. `set_props()` copies every key onto the instance.

Through `register_widget_type()` the strings arrive translated and `help`, `icon` and `actions` in shape. The manifest helper translates and sanitizes them itself.
Through `register_widget_type()` the strings arrive translated and `help`, `icon`, `actions` and `attributes` in shape. The manifest helper translates and sanitizes them itself.

An `icon` is a `jpa/<name>` reference. The client resolves it through the resolver `packages/init` registers, a lookup in the collection `packages/icons/src/resolve.ts` lists: the `@wordpress/icons` glyphs the widgets use, by kebab-case name, plus the dashboard's own illustrations where no widget names a WordPress one. Where both carry a name (`calendar`, `megaphone`, `payment`, `search`) the list holds the WordPress glyph. A name outside the list, or one in another collection, degrades to no icon; a glyph a widget needs goes into the map first. A `widget.ts` that still exports an icon element shows it while the reference resolves, and keeps it only when the resolution fails.

Expand Down Expand Up @@ -240,7 +241,24 @@ It reads the package's fixed list and, once the registry can answer, the registr

`WIDGET_API_VERSION` names the contract a widget is built against: the `@automattic/jetpack-premium-analytics-sdk` module and the exports it declares, the dashboard modules the facade re-exports from (`@jetpack-premium-analytics/widgets-toolkit`, `data`, `fields`, `datetime`, `externals`), and the `Widget_Type` fields the client reads.

The major changes when a widget built against the previous contract stops working; the minor when a consumer can rely on something new. So far, 1.1.0 added `former_names` and 1.2.0 `Leaderboard`, `describeError()` and `useStatsVideoPlays`, and 1.3.0 `ExporterCsvDownloadButton`, which takes the linked report by id. 1.4.0 added `useReport`, which runs a report query and its comparison in the dashboard's query client, and `toBucketStamp`, which writes the bounds of a report row the way the dashboard's time series read them. 1.5.0 added `Donut`, the breakdown kind, and `WidgetStatus`, the request status every kind takes. 1.6.0 resolves the `jpa/<name>` icon references the records carry, through the resolver `packages/init` registers. 1.7.0 added the `bars` variant of `Leaderboard`, which lays the label above the bar and draws the comparison period as a second bar under a period legend. 1.8.0 added the `half-ring` variant of `Donut`, which draws the breakdown as a semi-circle with the total under the arc, and `withTotal`, off for shares that add up to one. 1.9.0 added `Funnel`, the funnel kind: steps as counts in, the rate of the whole, the shares and the states out. 1.10.0 added `Columns`, the kind for a few categories compared across the periods as vertical bars. 1.11.0 added `Locations`, the kind that lists a ranking of places beside the map that draws them, countries or the regions of one country. 1.12.0 added `plan_feature`, the paid Stats feature a widget shows, which the plan gates lock. 1.13.0 added `chartTitle` to `Columns`, `Donut`, `Funnel`, `Leaderboard`, `Locations` and `MetricTabsChart`, which names the chart "Chart: <title>" for screen readers, and the `Locations` map "Map: <title>"; on an older dashboard the chart keeps its generic name. The field types the dashboard registers are part of the contract too: `jpa/select`, `jpa/toggle-group` and `jpa/array-checkbox` have been there since 1.0.0, so a new name is a minor. `chartTypeAttributeField` left the SDK while it is private and every consumer lives in this repository; a widget declares the attribute itself.
The major changes when a widget built against the previous contract stops working; the minor when a consumer can rely on something new. The field types the dashboard registers are part of the contract: `jpa/select`, `jpa/toggle-group` and `jpa/array-checkbox` since 1.0.0, so a new name is a minor. A widget declares its chart type attribute itself; the SDK exports no helper for it.

| Minor | Added |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1.1.0 | `former_names`. |
| 1.2.0 | `Leaderboard`, `describeError()`, `useStatsVideoPlays`. |
| 1.3.0 | `ExporterCsvDownloadButton`, which takes the linked report by id. |
| 1.4.0 | `useReport`, a report query and its comparison in the dashboard's query client; `toBucketStamp`, the bounds of a report row the way the time series read them. |
| 1.5.0 | `Donut`, the breakdown kind; `WidgetStatus`, the request status every kind takes. |
| 1.6.0 | `jpa/<name>` icon references on the records, resolved through the resolver `packages/init` registers. |
| 1.7.0 | `Leaderboard` variant `bars`: the label above the bar, the comparison period as a second bar under a period legend. |
| 1.8.0 | `Donut` variant `half-ring`, the total under the arc; `withTotal`, off for shares that add up to one. |
| 1.9.0 | `Funnel`: steps as counts in, the rate of the whole, the shares and the states out. |
| 1.10.0 | `Columns`: a few categories compared across the periods as vertical bars. |
| 1.11.0 | `Locations`: a ranking of places beside the map that draws them, countries or the regions of one country. |
| 1.12.0 | `plan_feature`, the paid Stats feature a widget shows, which the plan gates lock. |
| 1.13.0 | `chartTitle` on `Columns`, `Donut`, `Funnel`, `Leaderboard`, `Locations` and `MetricTabsChart`: "Chart: <title>" for screen readers, "Map: <title>" for the `Locations` map. |
| 1.14.0 | `attributes` on the record, which lead the module's by `id`. |

Inside `plugins/jetpack` the package and a consumer module ship together, so the check is a formality. With the standalone `plugins/premium-analytics` next to another plugin, each brings its own copy, and the check is what keeps a widget built against 1.x from registering on a 2.x package.

Expand Down
14 changes: 14 additions & 0 deletions projects/packages/premium-analytics/src/class-widget-type.php
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,20 @@ class Widget_Type {
*/
public $actions = null;

/**
* Attribute schema, one entry per setting of a widget instance: a DataViews
* field in its JSON form, plus the keys the dashboard reads on top of a
* field (`relevance`, so far). User-facing strings are translated at
* registration time using the widget's text domain.
*
* Null when the widget did not declare the field.
*
* @since $$next-version$$
*
* @var array|null
*/
public $attributes = null;

/**
* Alternative terms used to match the widget type when searching,
* e.g. "calendar" for an events widget. Translated at registration
Expand Down
14 changes: 14 additions & 0 deletions projects/packages/premium-analytics/src/widget-i18n.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,19 @@
"links": [ { "label": "widget help link label" } ]
},
"actions": [ { "label": "widget action label" } ],
"attributes": [
{
"label": "widget attribute label",
"header": "widget attribute header",
"description": "widget attribute description",
"placeholder": "widget attribute placeholder",
"elements": [
{
"label": "widget attribute option label",
"description": "widget attribute option description"
}
]
}
],
"keywords": [ "widget keyword" ]
}
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,7 @@ function get_widget_modules_response() {
'help' => $widget_type->help,
'icon' => $widget_type->icon,
'actions' => $widget_type->actions,
'attributes' => $widget_type->attributes,
'keywords' => $widget_type->keywords,
'textdomain' => $widget_type->textdomain,
'i18n_manifest' => $widget_type->i18n_manifest,
Expand Down
Loading
Loading