woocommerce/plugins/woocommerce-admin/docs/examples/activity-panel-inbox.md

241 lines
11 KiB
Markdown
Raw Normal View History

2018-11-01 19:18:43 +00:00
Activity Panel Inbox
====================
Right now, installing and activating WooCommerce and a few extensions quickly results in a cascade of notices vying for the store administrators attention (and pushing whatever wp-admin content they were trying to get to on a page down, way down.)
2018-11-01 19:18:43 +00:00
As part of the Dashboard and Analytics improvements coming to WooCommerce, were going to do something a bit dramatic to try and clean up this notice-palooza.
2018-11-01 19:18:43 +00:00
First, were splitting up notices into two broad categories.
## Category 1: Store Alerts
The first category is what were calling “Store Alerts” - similar to the notices you have today, these notices are present at the top of administration pages and will look something like this:
2018-11-01 19:18:43 +00:00
2018-11-01 19:38:36 +00:00
![Store Alerts](images/activity-panel-store-alerts.png)
2018-11-01 19:18:43 +00:00
But unlike todays notices, this part of the UI will be reserved for “priority” messages to the administrator - things like version and security updates and critical errors. What sort of errors are “critical errors”? Well, things like a payment gateway that has stopped working because its connection is down, or when the store is set for physical product support but no shipping methods are defined.
## Category 2: Activity Panel Inbox
The second category is what were focusing on in this example - and what we expect the vast majority of extension developers will want to extend - we call it the “Activity Panel Inbox.” It will look something like this:
2018-11-01 19:18:43 +00:00
2018-11-01 19:38:36 +00:00
![Activity Panel Inbox](images/activity-panel-inbox.png)
2018-11-01 19:18:43 +00:00
This section is dedicated to informational content coming from multiple sources such as WooCommerce core, WooCommerce.com Subscription management, extensions activity and store achievements. This section was also envisioned to display more insightful content in the future, e.g. content that could help with the day to day tasks of managing and optimizing a store.
2018-11-01 19:18:43 +00:00
Each notice or “note” has a type represented by an icon (Gridicon), a title, content, a timestamp and one or two actions (action title + link).
### Inbox Design Constraints and Best Practices
Extensions can add their own notes via the data stores well be covering below, but first... some constraints...
2018-11-01 19:18:43 +00:00
There are some constraints extensions should follow when working with the inbox:
1. Generally speaking, dont change the order of items. It is OK for an extension to occasionally “bump” a note to the top of the inbox by deleting a note and adding a new note with similar content, but bumping should be done sparingly. For example, subscription notes will be bumped at 45, 20, 7, and 1 days before the corresponding subscription expires.
1. Generally speaking, dont delete notes. There are a few situations where deleting notes makes sense, like after the user has corrected a bad connection, but again, generally, dont delete notes.
1. That said, it is OK to change note content. This can be useful after the user has taken an action (e.g. renewed an expiring subscription). Changing the message after they do something like that makes it easy for the user to see a chronology of things theyve done.
1. Dont add UI components. Focus on the PHP API.
1. Be aware that notes are stored in the database using the locale in effect when the note was added to the inbox. Also be aware that you can use content_data property of a note in a hook context to “re-localize” notes on the fly into new locales.
1. Feel free to use the content_data property to store other things too - it isnt just limited to things needed for “re-localization” - and it is backed by a longtext column in the database.
1. Notes can have 0, 1, or 2 action buttons. Action buttons have URLs. They can either be complete URLs (like in the case of an external link) or partial URLs (like in the case of an admin page on the site) - in the case of partial URLs youll want to give a string that is the same as what youd supply to WordPress cores admin_url function. You can even include query parameters in that string.
1. You should store your extensions name (slug) in the source property of the note. WooCommerce will store woocommerce there. For example, the “Panda Payments” extension could use a name like “panda-payments” - this makes it easier to use built in functions to get (or delete) all notes with a certain name.
1. You can use the name property of a note to store a sub-type of note. For example, if the Panda Payments extension generates notes for both connection problems AND for new features, they might both have panda-payments in the source property but then use connection-problem and new-feature in the name property to distinguish between the two types of notes.
1. Icons are Gridicons. You can find a gallery [here](https://automattic.github.io/gridicons/)
2018-11-01 19:18:43 +00:00
1. As a best practice, have your extension remove its notes on deactivation or at least uninstall.
So, enough rules - lets get into how to code this up. And surprise, no JavaScript is necessary - you can work with the inbox exclusively through PHP -- the inbox front-end is React based, sure, but it draws all its data from a couple of new database tables and the PHP based REST API (and thats where you can work with notes).
### Adding and Removing Inbox Items
Heres a short example plugin that adds a new activity panel inbox note on plugin activation, and removes it on deactivation:
```
<?php
/**
* Plugin Name: WooCommerce Activity Panel Inbox Example Plugin One
* Plugin URI: https://woocommerce.com/
* Description: An example plugin.
* Author: Automattic
* Author URI: https://woocommerce.com/
* Text Domain: wapi-example-one
* Version: 1.0.0
*/
class WooCommerce_Activity_Panel_Inbox_Example_Plugin_One {
const NOTE_NAME = 'wapi-example-plugin-one';
/**
* Adds a note to the merchant' inbox.
*/
public static function add_activity_panel_inbox_welcome_note() {
if ( ! class_exists( 'WC_Admin_Notes' ) ) {
return;
}
if ( ! class_exists( 'WC_Data_Store' ) ) {
return;
}
$data_store = WC_Data_Store::load( 'admin-note' );
// First, see if we've already created this kind of note so we don't do it again.
$note_ids = $data_store->get_notes_with_name( self::NOTE_NAME );
foreach( (array) $note_ids as $note_id ) {
$note = WC_Admin_Notes::get_note( $note_id );
$content_data = $note->get_content_data();
if ( property_exists( $content_data, 'getting_started' ) ) {
return;
}
}
// Otherwise, add the note
$activated_time = current_time( 'timestamp', 0 );
$activated_time_formatted = date( 'F jS', $activated_time );
$note = new WC_Admin_Note();
$note->set_title( __( 'Getting Started', 'wapi-example-plugin-one' ) );
$note->set_content(
sprintf(
/* translators: a date, e.g. November 1st */
__( 'Plugin activated on %s.', 'wapi-example-plugin-one' ),
$activated_time_formatted
)
);
$note->set_content_data( (object) array(
'getting_started' => true,
'activated' => $activated_time,
'activated_formatted' => $activated_time_formatted,
) );
$note->set_type( WC_Admin_Note::E_WC_ADMIN_NOTE_INFORMATIONAL );
// See https://automattic.github.io/gridicons/ for icon names.
// Don't include the gridicons- part of the name.
$note->set_icon( 'info' );
$note->set_name( self::NOTE_NAME );
$note->set_source( 'wapi-example-plugin-one' );
// This example has two actions. A note can have 0 or 1 as well.
$note->add_action(
'settings',
__( 'Open Settings', 'wapi-example-plugin-one' ),
'?page=wc-settings&tab=general'
);
$note->add_action(
'settings',
__( 'Learn More', 'wapi-example-plugin-one' ),
'https://github.com/woocommerce/wc-admin/tree/master/docs'
);
$note->save();
}
/**
* Removes any notes this plugin created.
*/
public static function remove_activity_panel_inbox_notes() {
if ( ! class_exists( 'WC_Admin_Notes' ) ) {
return;
}
WC_Admin_Notes::delete_notes_with_name( self::NOTE_NAME );
}
}
function wapi_example_one_activate() {
WooCommerce_Activity_Panel_Inbox_Example_Plugin_One::add_activity_panel_inbox_welcome_note();
}
register_activation_hook( __FILE__, 'wapi_example_one_activate' );
function wapi_example_one_deactivate() {
WooCommerce_Activity_Panel_Inbox_Example_Plugin_One::remove_activity_panel_inbox_notes();
}
register_deactivation_hook( __FILE__, 'wapi_example_one_deactivate' );
```
### Updating Inbox Items
Heres a short example plugin that updates an activity panel inbox note:
```
<?php
/**
* Plugin Name: WooCommerce Activity Panel Inbox Example Plugin Two
* Plugin URI: https://woocommerce.com/
* Description: An example plugin.
* Author: Automattic
* Author URI: https://woocommerce.com/
* Text Domain: wapi-example-plugin-two
* Version: 1.0.0
*/
class WooCommerce_Activity_Panel_Inbox_Example_Plugin_Two {
const NOTE_NAME = 'wapi-example-plugin-two';
/**
* Adds a note to the merchant' inbox.
*/
public static function add_or_update_activity_panel_inbox_note() {
if ( ! class_exists( 'WC_Admin_Notes' ) ) {
return;
}
if ( ! class_exists( 'WC_Data_Store' ) ) {
return;
}
$data_store = WC_Data_Store::load( 'admin-note' );
// First, see if we've already created our note so we don't do it again.
$note_ids = $data_store->get_notes_with_name( self::NOTE_NAME );
if ( empty( $note_ids ) ) {
$note = new WC_Admin_Note();
$note->set_title( __( 'Domain Renewal Coming Up', 'wapi-example-plugin-two' ) );
} else {
$note = WC_Admin_Notes::get_note( $note_ids[0] );
}
$expires_in_days = rand( 2, 365 );
$note->set_content(
sprintf(
/* translators: a number of days, e.g. 100 */
__( 'Your domain expires in %d days.', 'wapi-example-plugin-wto' ),
$expires_in_days
)
);
$note->set_content_data( (object) array(
'expires_in_days' => $expires_in_days,
) );
$note->set_type( WC_Admin_Note::E_WC_ADMIN_NOTE_INFORMATIONAL );
// See https://automattic.github.io/gridicons/ for icon names.
// Don't include the gridicons- part of the name.
$note->set_icon( 'info' );
$note->set_name( self::NOTE_NAME );
$note->set_source( 'wapi-example-plugin-two' );
// This example has no actions. A note can have 1 or 2 as well.
$note->save();
}
/**
* Removes any notes this plugin created.
*/
public static function remove_activity_panel_inbox_notes() {
if ( ! class_exists( 'WC_Admin_Notes' ) ) {
return;
}
WC_Admin_Notes::delete_notes_with_name( self::NOTE_NAME );
}
}
function admin_init() {
WooCommerce_Activity_Panel_Inbox_Example_Plugin_Two::add_or_update_activity_panel_inbox_note();
}
add_action( 'admin_init', 'admin_init' );
function wapi_example_two_deactivate() {
WooCommerce_Activity_Panel_Inbox_Example_Plugin_Two::remove_activity_panel_inbox_notes();
}
register_deactivation_hook( __FILE__, 'wapi_example_two_deactivate' );
```
## Questions?
This is just the tip of the iceberg for possibilities for your own extensions to WooCommerce. Check
out the new [sales record notes](https://github.com/woocommerce/wc-admin/blob/master/includes/class-wc-admin-notes-new-sales-record.php) and the [settings notes](https://github.com/woocommerce/wc-admin/blob/master/includes/class-wc-admin-notes-settings-notes.php) for in the wc-admin code itself for other examples of working with this fun new feature.