Rethink Site (Wide) notices

[imath]

Today, this feature is included into the BP Messages component (although it might be more consistent to have it in the Notifications one). The legacy reason for this is probably due to the fact writing Site Notices was done from the Private Messages front end UI.

To warn Site Admins about important BP information, we used a workaround for the Admin notifications feature in 11.4.0, see #9007.

Recently we had this ​discussion about it working on the new BP Documentation project and I remember we also discussed about it with @espellcaste from a Messages component ticket.

I believe we need a Core feature to send important notices to Admins (The Notifications/Messages component can be deactivated). We experienced this need in 11.4.0 because of the BP Rewrites API important changes and I'm sure we'll need it again soon (See ​roadmap).

I think Admin users shouldn't need to activate the Messages component to send important notices to all their members. We can improve these Site Notices to play some other role like warn only Site writers about important information.

Let's move it out of the Messages component & transform it as a Core feature!

[shawfactor]

This should not be a core feature, it should be its own component. Not everyone is going want it and not everyone will want it done the buddypress way.

In terms of its own component, why not just use a custom post type? The current db schema for notifications is pretty limited…

[imath]

Thanks for your feedback @shawfactor

Actually the first people needing it to be a Core feature is us the Core team :)

The new direction I want to move Site Notices towards is like a BuddyPress "approaching" way of doing something that is taking way too long to happen in WordPress => ​https://wordpress.github.io/wp-feature-notifications/?path=/docs/feature-notifications-introduction--docs

Although it seems to still be under development, it's been ​6 years since it started...

We first need this to be a Core Feature to:

• Inform about important changes happening in BuddyPress: the "Admin notifications" workaround we used for 11.4.0 is not satisfying to me as people expressed the need to be able to read again dismissed Admin notifications.
• It could be used to inform about a getting started guide like it was suggested in Slack.
• It could still be used by site Admins to inform users widely on the front-end and in the back-end.
• It could be used by site Admins to warn specific roles like "author" about important thing to consider when contributing to content, etc..

About using a "custom post type", this is not the reply to every need. I wonder why the WordPress feature as a plugin is not using the CPT feature 😉
​https://wordpress.github.io/wp-feature-notifications/?path=/docs/documentation-database-schema--docs

Finally, if it should be in its own component, then it needs to be outside of BuddyPress as a BP Addon like BP Attachments. The new direction we took is to shrink BuddyPress progressively to move optional components into BP Addons: we won't add new BP Optional components anymore.

[shawfactor]

Actually your approach is logical. The existing site wide notices functionality should move to the notification component and be compatible with the feature as a plugin.

Two issues though

1. How does this schema all map to the actions/componenf logic we currently use in notifications?

2. How would this interact with Multisite. The issue I have atm is segregating sitewide notices by site. This is impossible for me atm as the message component is shared across all sites. The notification comment is also shared so the same issue may still exist.

[imath]

I need more time. I won't be able to make it for 14.0.0, sorry.

[emaralive]

@imath I didn't realize the Legacy template pack behaved differently than Nouveau, apparently Site Notices are rendered across all front-end pages. Since BuddyPress 12.0.0 restricts JavaScript and Style assets loading to BuddyPress pages only; this seems to be a dilemma as to how Site Notices should work as it pertains to the Legacy template pack.

See ​WP Admin -> Users -> Site Notices (Support Forum post) as reference.

[imath]

Thanks for the alert @emaralive I agree this needs a fix, I'll work on it from another specific ticket.

[imath]

Hi everyone, I'm progressing! I almost finish a first version for the PR: I still need to manage cache and the BP Legacy template pack.

Here are some screenshots to have a preview of the revamped notice feature.

The notices center is listing "community notices" as well as personal notifications (when the BP Notifications component is active).

It's listing one notice at a time according to a priority order:

• Highest is restricted to BuddyPress notices to Administrators
• High, regular and low are 3 other notice priority levels the community administrator can use to rearrange the order notices are displayed into the "no js paginated slider"

Only 5 top priority notices are displayed into the notices center, a link if there are more than 5 notices is allowing the user to view all community notices.

When the BP Notifications component is active, all community notices are listed into the Community subnav of the corresponding user's Notifications screens. The count is: number of unread community notices + unread personal notifications.

Users can view dismissed community notices using the filter.

When the BP Notifications is not active, community notices have their own navigation.

The community administrator can manage all notices from the WP Admin Screen:

BuddyPress notices to community admins can only be deleted once all admins dismissed their notice.
The community admin can write a notice targeting all members, only contributors or only admins. He can use a call to action to open a specific link.

Once published, a notice can be updated.

It can be deleted or deactivated.

All BuddyPress notices to admins can be viewed inside the place we were using for Admin Notifications (which are replaced by BuddyPress notices).

To be continued...

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 ​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:

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 ​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 ​bp-custom.php file to be able to test the JavaScript Powered dismiss action:

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

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:

Changing the format of the files for the V2 endpoints is no problem at all. I think the main issue before was renaming the files from V1, but since we will bundle it in the bp rest plugin, keeping their names, again, it's no problem at all.

Hi @renatonascalves thanks a lot for your review 😍 . I'll look at it in details asap!

@renatonascalves I believe I've improved most important parts according to your review.

About the 2 remaining REST API points: duplicate usage of rest_ensure_response and forcing the edit context for create/update/delete requests, I'll do what you confirm is best. I've copied these from the current v1 REST API endpoint.

About the other improvements + adding more unit tests, I'd suggest to work on it once the current code is merged 😅