[buddypress-trac] [BuddyPress Trac] #9098: Rethink Site (Wide) notices

[buddypress-trac]

#9098: Rethink Site (Wide) notices
-----------------------------+-----------------------
 Reporter:  imath            |       Owner:  imath
     Type:  enhancement      |      Status:  assigned
 Priority:  high             |   Milestone:  15.0.0
Component:  Messages         |     Version:  1.0
 Severity:  normal           |  Resolution:
 Keywords:  early has-patch  |
-----------------------------+-----------------------
Changes (by prbot):

 * keywords:  needs-patch early => early has-patch


Comment:

 ''This ticket was mentioned in
 [https://github.com/buddypress/buddypress/pull/368 PR #368] on
 [https://github.com/buddypress/buddypress/ buddypress/buddypress] by
 [https://profiles.wordpress.org/imath/ @imath].''
 The goal of this PR is to transform the code used into the Private
 Messages component (*an optional component => only available when the
 Private Messages component is active*) to send all community members a
 “SiteWide Notice” into a Members component (*a required component =>
 always available*) feature so that:

 - The BP Team can use it to inform Administrators about important changes:
 this new Members Feature is replacing the Admin Notifications workaround
 we introduced in 11.4.0 to communicate about 12.0.0 important changes.
 - Site administrators can notice all community members or all contributors
 or all other administrators about important informations dealing with
 community, contribution, or administration matters.
 - Integration with the Notifications component is improved as Notices
 behave similarly to Notifications => they “disappear” once they are
 dismissed by the user.
 ## Notices: a Members component feature

 While I first thought Notices should be a Core component feature, I
 quickly changed my mind when working on code changes. The Core component
 is not setting [https://github.com/buddypress/buddypress/blob/master/src
 /bp-core/classes/class-bp-component.php#L345|L448 needed globals] such as
 DB table/table meta and after more thoughts I believe Notices have more to
 do with Members.

 The Members Notices can be deactivated using this filter:

 {{{
 #!php
 add_filter( 'bp_is_members_notices_active', '__return_false' );
 }}}


 Although I’d strongly recommend not to disable it, we’ll always make some
 adventure users unhappy with it…

 A notice is a piece of informations targeting specific member roles:

 - `community` All members are targeted by the notice.
 - `contributors` Only members able to write posts are targeted by the
 notice.
 - `admins` Only administrators are targeted by the notic.

 A notice can have 5 priority levels. 2 levels are not available to
 administrators:

 - `0`  the “Very High” priority level is restricted to the BuddyPress team
 to inform Administrators about important plugin changes.
 - `1` the “High” priority level can be used to move a notice to the top of
 the notices list.
 - `2` the “Regular” priority level is the default one.
 - `3` the “Low” priority level can be used to move a notice at the bottom
 of the notices list.
 - `127` is a specific level used to deactivate a notice (just like it was
 possible within the Private Messages component)

 A notice can include a call to action as long as the destination URL has
 the same domain name than the WordPress site.

 Notices are stored into the `wp_bp_notices` table and data about the list
 of users who dismissed a notice is no longer inside a serialized array of
 the corresponding user meta but stored as rows into the
 `wp_bp_notices_meta` table. There’s one row for a user/notice and the name
 of the Notice meta is `dismissed_by`: Notice ID (`notice_id`  field of the
 table) was dismissed by (`meta_key` field of the table) User ID
 (`meta_value`  field of the table).
 The BuddyPress DB Schema was updated to migrate data inside the
 `wp_bp_messages_notices` table if it exists into the new `wp_bp_notices`
 table.

 **Notices management**
 Administrators can manage notices from the `Users > Member notices` WP
 Dashboard menu. From there they can add, edit, deactivate or delete all
 the notices they created. BuddyPress “Very High” notices cannot be edited
 or created by the administrators. They can deactivate this kind of notices
 but they need to wait for all administrators to dismiss it before being
 able to delete it.

 **The BP Notices center**
 An orange bell with the number of unread notices/notifications is added to
 the WP Admin Bar only if there is a notice or a notification (when the
 Notifications component is active) to display.

 Once the orange bell is clicked an HTML Popover is appearing: the first
 part of it is displaying a “Community notices” section and when the
 Notifications component is active, it also includes a “Personal
 notifications” section.

 > [!NOTE]
 > If users browser doesn’t support the
 [https://caniuse.com/?search=popover HTML Popover API], they are
 redirected to the Notices Member’s front-end profile area when clicking on
 the orange bell.

 > [!NOTE]
 > In other words, the Notifications component is using this BP Notices
 Center to display the logged in member’s notifications. It doesn’t create
 any new node to the WP Admin Bar anymore and the `src/bp-notifications/bp-
 notifications-adminbar.php` file is deprecated since 15.0.0.

 The “Community notices” section is a “no JS” slider allowing the logged in
 member to slide up to 5 top priority notices. If there are more than 5
 active notices a link is added to the slider’s pagination to view all
 notices from the Notices Member’s front-end profile area.

 A notice can always be dismissed from there thanks to the corresponding
 “Dismiss” button. If the notice contains a call to action, another button
 is added for it and clicking on this button will first dismiss the notice
 before redirecting the user to the call to action URL.

 BuddyPress is using this call to action when noticing an upgrade to a
 major release was successful so that the administrator can directly open
 the BP Hello/changelog modal to discover what’s new. As a reminder this
 modal is only automatically displayed after a successful install.

 > [!NOTE]
 > BuddyPress Admin Notices are still displayed into the Notices tab of the
 BuddyPress settings administration screen. From there it’s possible to
 view dismissed notices as well.

 **Notices Member’s front-end profile area**
 All notices are by default available into a Notices navigation of the
 user’s profile. When the Notifications component is active this navigation
 is moved as a Notifications sub navigation. In this case the Notifications
 count also takes in account the Notices count. The Notices loop is
 paginated 5 by 5 and can be filtered to list all unread or dismissed
 notices. Both Legacy and Nouveau template packs were updated to include
 notices templates.

 ## The component’s feature API (new!)

 The PR includes a new `BP_Component_Feature` class. Looking back at how we
 implemented the Site Invitations feature, I believed this part needed to
 be improved. For Site Invitations we created a component using the
 `BP_Members_Invitations_Component` object just to be able to have a
 primary nav into the member’s profile area. The downside of this is it’s
 creating an active component into the `buddypress()` global. Extending
 this new `BP_Component_Feature` class which itself extends the
 `BP_Component` class we avoid the downside and have better control on how
 to build feature specificities (see `BP_Members_Notices_Feature`). I
 believe we should go a bit further grouping features files into a
 feature’s directory. For now I just did the same than we did before: group
 all functions, template tags etc.., into a single `bp-members-notices.php`
 file (`bp-{component-name}-{feature-name}.php`).

 ## The Notices Rest Controller

 > [!TIP]
 > Until BP REST API v2 is merged into Core, you’ll need to use the
 following code snippet within a
 [https://github.com/buddypress/buddypress/blob/master/docs/user/advanced/functionalities.md
 bp-custom.php] file to be able to test the JavaScript Powered dismiss
 action:

 {{{
 #!php
 function force_notices_feature_rest_api( $feature_class ) {
     add_action( 'bp_rest_api_init', array( $feature_class, 'rest_api_init'
 ), 10 );
 }
 add_action( 'bp_members_notices_setup_actions',
 'force_notices_feature_rest_api' );
 }}}


 I remember having discussions with @renatonascalves about the best way to
 deprecate BP REST API v1 and class naming for the BP REST API v2. I was
 confronted to it and after more thoughts, I believe we should name v2 REST
 API Class controllers like this `BP_{component}_{feature}_REST_Controller`
 (I probably changed my mind there, sorry!): one of benefit for this is we
 are following the class autoloader regular map and don’t need to add
 entries for irregular ones. Here’s the deprecation strategy I used:

 - In `BuddyPress->autoload()` keep deprecated endpoint class, eg:
 `'BP_REST_Sitewide_Notices_Endpoint' => 'messages', // deprecated.`
 - Keep & deprecate the old class file, see `src/bp-messages/classes/class-
 bp-rest-sitewide-notices-endpoint.php` for an example.

 The `BP_Members_Notices_REST_Controller`  will greatly benefit from
 @renatonascalves review & improvements.

 Thanks in advance for your tests & reviews!

 > [!IMPORTANT]
 > Go to `site.url/wp-admin/` first to test the PR, the upgrade routine
 needs to be accomplished first, you'd get DB errors otherwise.

 Trac ticket: https://buddypress.trac.wordpress.org/ticket/9098

-- 
Ticket URL: <https://buddypress.trac.wordpress.org/ticket/9098#comment:17>
BuddyPress Trac <http://buddypress.org/>
BuddyPress Trac