BP Dev Chat Summary: July 10, 2019

BP REST API focus

REST fields (~= BuddyPress Components metadata)

PRs #189, #193, & #194 have been merged into the BP REST API by @espellcaste : they brought these REST fields for the Activity, Groups, Members, Messages, Notifications, and xProfile (field/group/data) endpoints.

If you are a BuddyPress plugin developer, here’s how you can use this feature to create/update and get your custom REST Fields.

// Registers a REST field for the Activity Endpoints.
function example_register_activity_rest_field() {
	bp_rest_register_field(
		'activity',      // Id of the BuddyPress component the REST field is about
		'example_field', // Used into the REST response/request
		array(
			'get_callback'    => 'example_get_rest_field_callback',    // The function to use to get the value of the REST Field
			'update_callback' => 'example_update_rest_field_callback', // The function to use to update the value of the REST Field
			'schema'          => array(                                // The example_field REST schema.
				'description' => 'Example of Activity Meta Field',
				'type'        => 'string',
				'context'     => array( 'view', 'edit' ),
			),
		)
	);
}
add_action( 'bp_rest_api_init', 'example_register_activity_rest_field' );

/**
 * The function to use to get the value of the REST Field.
 *
 * @param  array  $array     The list of properties of the BuddyPress component's object.
 * @param  string $attribute The REST Field key used into the REST response.
 * @return string            The value of the REST Field to include into the REST response.
 */
function example_get_rest_field_callback( $array, $attribute ) {
	// The key of the metadata can be different from the REST Field key.
	$metadata_key = '_example_metadata_key';
	
	return bp_activity_get_meta( $array['id'], $metadata_key );
}

/**
 * The function to use to update the value of the REST Field.
 *
 * @param  object $object    The BuddyPress component's object that was just created/updated during the request.
 *                           (in this case the BP_Activity_Activity object).
 * @return string $value     The value of the REST Field to save.
 * @param  string $attribute The REST Field key used into the REST response.
 */
function example_update_rest_field_callback( $object, $value, $attribute ) {
	// The key of the metadata can be different from the REST Field key.
	$metadata_key = '_example_metadata_key';
	
	bp_activity_update_meta( $object->id, $metadata_key, $value );
}

View the code on Gist.GitHub.com

REST links

The Message endpoint got its filterable links (See the prepare_links() method of its endpoint).

@espellcaste and I are agreeing the other components should also include a filter to let plugin developers eventually add custom links. #Needs-PR 😉

Documentation site about the BP REST API

We’ve discussed about the post where I suggest possible roads for a while with @espellcaste. In particular, I’ve shared my 2 concerns about the Restsplain plugin generated documentation :

  • I think we should use it to write a more “human understandable” documentation. For instance, use “Create an activity” instead of POST
  • It would be better to use our bp.apiRequest function in code examples instead of the fetch() one.

NB: After the Dev Chat, @johnjamesjacoby advised to keep docs and support on BuddyPress.org to avoid fragmentation, and to maintain user trust. I agreed it was best and opened a ticket on the Meta Trac (See #4601) to move forward.

Updates about the Tickets into the 5.0.0 milestone

It would be great to have the patches attached to the following list of tickets tested during the next 2 weeks:

Next dev-chat

It will happen on July 24th at 19:00 UTC in #BuddyPress slack channel. In the meantime: have fun contributing to BuddyPress 👩🏻‍💻, we have 1 month left before 5.0.0 first beta 🗓

#5-0

BP Dev Chat Agenda: July 10, 2019

This is the agenda for our next Dev Chat which will happen on July 10th at 19:00 UTC:

  • Updates about the latest BP REST API improvements.
  • BP REST API documentation site (please take a look at this post about a possible road if you haven’t already done it so far).
  • Updates about 5.0.0 tickets.

This meeting is held in the #BuddyPress channel of the Making WordPress Slack.

If you have anything you wish to add to this agenda or specific items related to those listed above, please leave a comment below.

#5-0

BP Dev Chat summary (June 26)

Updates about the Tickets into the 5.0.0 milestone

#8045 is achieved: we now have our very first core feature using the BP REST API. If you chose to use BP Nouveau as your template pack (it is the default template pack for new installs), your group administrators will enjoy a brand new interface to manage the members of their group(s).

The interface is more dynamic than our legacy one and Administrators of popular groups will probably love the search feature! Finding the specific member they want to promote, demote, ban or remove is faster than ever!

#6210 @dcavins is working on a new version of the patch to adapt it to play nicer with BP Nouveau & see how things will evolve with the BP REST API. He worked very hard 💪 🏋🏻‍♂️ so far and I believe he’s very close to achieve his goal. I think it’s a very promising feature that will first improve how we handle group invitations and soon give new opportunities for other objects such as sites of a network. I also think it’s an interesting way to test & review the group invites & requests BP REST API endpoints.

There are 7 tickets with patches. Feel free to help us: testing patches and confirming they do the job is a already a great help. If you can improve them: it’s even greater! If you don’t know where to start, read this comment about how to test BuddyPress patches.

#7156 is the master ticket for the BP REST API. @im4th (me 😄) has suggested a patch to include the BP REST API into the BuddyPress’ build process. It’s a first reply to the question we haven’t replied yet since our previous dev-chat: « How to include the BP REST API into the BuddyPress plugin package? ». Feedbacks are very welcome.

BP REST API focus

REST fields (~= BuddyPress Components metadata)

We still have work on this “field” 😅 I’ve submitted a pull request that is implementing them for a bunch of endpoints. @espellcaste: please have a look at it soon and commit if you feel like me & @boonebgorges the approach is good.

The xProfile REST fields will need an extra work as the meta table is a bit different: we can attach a meta to a data, a field or a group of fields. I’ve posted an issue about it with a suggestion to handle this specific case. I’ll update it with a new pull request to adapt the one I was talking about into the previous paragraph.

The current endpoint about Threads/Private messages is more sensitive imho. REST fiels are messages metadata not threads ones. FYI, I’ve been also exploring how to use the BP REST API into the BP Nouveau Messages UI. I think I will carry on because it’s a nice way to eventually improve it.

REST links

I think we need to harmonise their use, for instance in BP REST Activity, BP REST Groups, BP REST Members, the links should all include a filter to let plugins add custom ones if needed. There should be links for the Private Message object to transport the “star” link, and probably the links of the users involved into the message…

Documentation site about the BP REST API

Last but not least! Feedbacks are very welcome about the post I’ve published to share my suggestions.

Next dev-chat

It will happen on July 10th at 19:00 UTC in #BuddyPress slack channel. In the meantime: have fun contributing to BuddyPress 👍

#5-0

A Developer resources site before the 5.0.0 release?

During our latest dev-chat, we’ve been talking about putting together a documentation site for the BP REST API. I’ve been exploring the subject more deeply this week and I believe we should take this opportunity to try to ship a first version of the developer resources site.

I think 5.0.0 is an interesting time/release (as it’s a very developer oriented one with the inclusion of the BP REST API) to start powering BuddyPress developers with some resources just like WordPress does with its DevHub project.

The « BP » DevHub project?

@tw2113 started working on a BuddyPress Code Reference site 3 years ago, see #6812. In his last comment he expressed his concern about the lack of developer content the site would offer. Then I thought the BP REST API documentation could be a great companion to this BuddyPress Code Reference! So I’ve carried on his work and built a local test site to check how difficult it could be to make this real.

Screen capture of the BP DevHub homepage
Preview of the homepage of the Developer resources site.

It’s doable before the 5.0.0 release!

It took me a couple of days, following and adapting the installation steps described in this chapter of the WordPress Documentation handbook, to build a « proof of concept » framework. Actually all I had to do was to create a child theme for the « wporg-developer » theme and share 2 patches on the Meta Trac (see #4516 & #4517) so that the Meta Team could fix the 2 issues I’ve found during my explorations.

Here’s what we need to do on the existing developer.buddypress.org site :

  1. Make sure Composer and WP CLI are running on the server.
  2. Install the « wporg-developer » theme.
  3. Install the WP Parser plugin → composer create-project wordpress/phpdoc-parser:dev-master --no-dev & activate it.
  4. Install & activate the Syntax Highlighter plugin.
  5. Install/Build the latest version of BuddyPress 😍 (no need to activate it).
  6. Run the WP CLI command using the BuddyPress directory of point 5 as the argument. For example: wp parser create path/to/wp-content/plugins/buddypress --user=1 or wp parser create path/to/wp-content/plugins/buddypress/build --user=1 if trunk is used.
  7. Install & activate the Handbook plugin (We don’t need the wporg-markdown & wporg-cli plugins as we don’t write our documentation on GitHub and moreover it would import the WordPress REST API and Coding standards documentations).
  8. Install & activate the « bporg-developer » child theme I’ve built using the Customizer live preview (so that it automatically creates the starter content – make sure the fresh_site option has its value set to 1).
  9. Go to the General Settings Administration screen and insert the version of BuddyPress into the BuddyPress latest stable version option.

Wait, but what about the BP REST API Documentation?

If you’d go on the BP REST API Handbook at this stage you wouldn’t see any content. We need to create it. We chose to have it generated thanks to the REST schemas of our REST endpoints. The Restsplain plugin does this task for all the WordPress and custom endpoints of the website.

Using it as it would first mean to activate BuddyPress (and possibly the BP REST plugin if not yet included into BuddyPress).

There are benefits of having the generated documentation this way as new endpoints would automatically be included. It’s also possible to create and attached content to our endpoints using the post type included inside the plugin. But there are also disadvantages: 

  • All BuddyPress components would need to be activated.
  • The React Application inside the Restsplain plugin is displaying the real URLs at various places.
  • It is also including a feature to use them into a specific container to make real REST requests.

The good new is: we can filter the list of endpoints the Restsplain plugin is generating. So I’ve added this filter to the bporg-developer theme and the documentation generation is now restricted to BuddyPress endpoints. Then I thought we could avoid the need for BuddyPress to be activated by first looking for an external Json file (a static copy of the array expected by Restsplain, where links are « anonamisized »).

But still, I had to remove completely the live testing of endpoints feature. Although it can be done in CSS, I chose to edit the plugin because:

  • it has not been updated for 7 months and as a result contains outdated node modules and React library.
  • Some real links are built in React using the rest base URL.
  • One of the link of the React endpoint viewes is triggering the live testing.

As a result the version of the plugin I suggest to use is the fork I’ve made here. As I’ve edited the React part, I also edited the styles to match the BuddyPress.org colors. Here’s how it looks:

Screen capture of the "api docs" page

As you can see it’s very different from the output made by the WordPress handbook plugin. The best I could do to make it more looking like it was to use the [restsplain] shortcode in a page.

Screen capture of the shortcode used in a page

That’s why I think we should probably only use this plugin to write a static version into the BP REST API handbook post type of what it generates dynamically.

We have 14 endpoints to document for 5.0.0 and 8 others for the 6.0.0 release and I think we can do some copy/pasting:  it won’t take too much time and the layout of the documentation will be the same for every potential handbooks (eg: BuddyPress plugins or themes).

Moreover we’ll be able to improve the navigation grouping endpoints by components, we’ll be able to use more meaningful titles for the GET, POST, PATCH, DELETE methods, eg: Get a specific user, add a user, update a user and remove a user. Finally we would be able to use code examples using our bp.apiRequest function instead of the fetch function Restsplain uses. Below is a screenshot showing what I mean about this copy/pasting task.

Screen capture of a potential page of the BP REST API handbook

What if we’re running out of time building the developer resources site?

It would be too bad, but not a so much big deal! I’ve already created a documentation site for the BP REST API. You can test it here. We would simply need to attach to this site a more meaningful domain name 😉

And when/if we get the developer.buddypress.org site ready (See the 9 steps above) soon enough we’ll be able to use this website to do the copy/pasting tasks.

Let’s discuss about it during our next dev-chat!

As a reminder, it will happen this Wednesday (June 26) at 19:00 UTC into our Slack channel: #BuddyPress. All BuddyPress Contributors are very welcome to join us. If you’re a bit intimidated (you shouldn’t!) but still want to give us your opinion about this topic, please use the comments area below 👍

#5-0, #developer-documentation

BP Dev-Chat Summary (June 12)

BP REST API

A huge work has been accomplished by @espellcaste 💪 so far from the feature as a plugin “BP REST” and we think the 5.0.0 release will be a good time to bring the REST API within BuddyPress core. As explained in #7156 it will introduce 14 BuddyPress endpoints and you’ll soon be able to play with activity updates, groups, members, private messages and extended profile fields using REST requests 🙌

8 other endpoints (eg: blogs, friends) will arrive in 6.0.0.

BP REST Documentation

As @boonebgorges said during the chat, this part is very important for us to help you build great BuddyPress plugins thanks to this new API. We’ve been looking for a nice tool to generate this documentation out of the endpoints schemas and we think we’ve found a good solution to start. We now have to put up a website to host this documentation. I’ll take care of sketching out the next steps of this site and @boonebgorges will be able to help for the domain name.

Let’s start using the API within BuddyPress core!

The best way to help you discover the BP REST API potential is to use it ourselves 😉. We plan to do so by improving how Group members are managed within the Group Manage screen (front-end) and the Group Admin screen (back-end). Below is a video demo to let you discover a bit early how it should look like on the front-end of your community site.

You can follow our progress from the #8045 ticket.

How to include the BP REST API into the BuddyPress plugin package?

We’ve been discussing about it for about 30 mins during the chat and we haven’t decided yet how this will happen. We have 2 options:

  • Carry on maintaining it from GitHub.com and include it during the BuddyPress plugin’s build process (that’s what we’re doing for BP Default & BP CLI)
  • Merge it into BuddyPress Core.

There are “pros” and “cons” for both options. For example, maintaining it from GitHub can be confusing for contributors because it adds a second place to report for this part of BuddyPress as @boonebgorges noted. It’s also problematic regarding the history of how the decisions were made: it would be “tied up in two places“. @espellcaste also expressed his preference, despite the fact working in GitHub is more convenient, about keeping things “in house” (we have less control about the future of GitHub). Finally @boonebgorges also explained we could keep it on GitHub for a couple of releases before bringing it home as “once we go Trac, we cannot go Back“.

Another relative point on this subjet: how plugins should behave if they are both activated?

  • Should the plugin BP REST take over BuddyPress ? Meaning all endpoints can be maintained from the GitHub repository.
  • Should it be BuddyPress? Meaning the BP REST plugin would only be used to develop the 8 remaining endpoints.

We agreed we still have time until the first beta release to decide, but if you have ideas or recommandations : please share them in comments 😊

About the 5.0.0 release schedule

We agreed on a first date : 5.0.0-beta1 will be released around August 15.

As discussed during the chat, it will give us the time to work on the documentation site and decide about the « BP REST API including » strategy.

It should also give us the time to clear the tickets list of the milestone, there are around 10 tickets left and you are very welcome to give us a hand testing or suggesting patches.

Until Beta1 we will have a dev chat every other Wednesday at 19:00 UTC in #BuddyPress. Here is the planning of our next meetings:

If you are going to Berlin to attend to the WCEU 2019: have fun, make good connections and learn great things! @johnjamesjacoby will be there, don’t hesitate to enjoy his conference 👌 and chat with him about BuddyPress 😍

You can also decide to give a hand to BuddyPress during this WordCamp thanks to the contributing area! We’ll be very happy to help from where we are 😁

#5-0

BP Dev-Chat Agenda

Hi everyone !

Let’s meet at 19:00 UTC on next Wednesday (12th of June) in #BuddyPress to talk about the 5.0.0 release. Here are the topics I’d like we discuss about during this meeting.

BP Rest API

To follow up with our last summary : it will be our main focus/feature for this release and we need to decide about:

  • Endpoints coverage.
  • The tool to use to generate the endpoints documentation.
  • BP Core API Usage : see 8045
  • Build process: as the BP Rest API will carry on be maintained from our GitHub repository, we need to update our build process to include needed files in the BuddyPress plugin’s package.

Tickets on the 5.0.0 roadmap

9 tickets are in the queue, let’s decide the ones we’ll fix/close before completing our milestone.

If you need/want to discuss about other topics, don’t hesitate to add them in comments 👍

#5-0

The state of the BP Nouveau Template Pack

On april 13 we had our first “Template Pack” chat. After 4 months of weekly meetings (on thursdays at 19:00 UTC), we thought it was time to share with you what we’ve accomplished so far.

3 years ago, the very first BuddyPress Template Pack – BP Legacy – was introduced in Totonno (1.7). It was a major improvement. Thanks to the BP Theme Compatibility, BuddyPress can use the template parts included in this Pack and inject them into the wide majority of WordPress themes. Site owners or theme designers can override these template parts to customize the appearance of community sites. And, for sure, they are doing it!

BP Legacy will remain the most compatible Template Pack BuddyPress ever made!

But after 3 years, we are feeling like it’s time we try to improve the user experience and optimize markup, Javascript, CSS, Ajax, etc.. And very quickly we all agreed that this couldn’t be done in BP Legacy without taking the risk to have an impact on all the possible overrides site owners or theme designers did and are still doing. History showed that unfortunately some of them are not necessarly taking the time to synchronise their customizations with the adjustments we sometimes have to do to our template parts… 😦 .

Moving forward with BP “Nouveau”.

In french “Nouveau” means “new”. If you’re thinking i’m the one who had the idea to call a new Template Pack this way, you’re wrong 🙂 @rayisme is the one! But i must admit i love this name!

In BP Nouveau, we’ve decided to follow these guidelines:

  • Modularity in CSS, Javascript and PHP.
  • Think forward instead of being afraid of breaking backward compatibility.
  • Build modern UIs by always taking advantage of the latest improvements WordPress or BuddyPress core are introducing.
  • Ease of customizations for site owners and at the same time advanced techniques for theme or plugin developers.

About this last point, the first drastic decision we’ve made was to remove all do_action hooks from template parts! Some of you might be surprised as these kinds of hook are ways to extend or customize. It appears that after 47 commits it actually gave birth to very interesting improvements:

  1. We first introduced new APIs such as the BP_Buttons_Group class. As you know BuddyPress uses a lot of buttons and in Legacy there are a lot of these hooks to let people add their own buttons. Thanks to this new API plugin/theme developers can choose the exact position where to output their buttons!
  2. Two new template hierarchies appeared (one for each single item object BuddyPress is using). For instance, it’s now possible to have a different activity stream layout for any member/member type or any group/group type.
  3. Template parts have been optimized. The huge groups/single/admin.php has been split so that we can now share some template parts between the Group’s create screens and the Group’s edit screen. The xProfile visibility is now a specific template part that is used by the xProfile edit screen and the signup screen. The WP Profile template we fallback on when xProfiles is not active stopped using old yim/aim/jabber fields in favor of a new loop using the wp_get_user_contact_methods() function so that potentially any new contact methods can be added. Finally The registration template has been completely revamped.
  4. New template tags have been created such as the one to generate standardized template notices and user feedbacks which can also contain “dismiss” buttons.

A BP Template Pack customizer panel.

Site owners will be able to customize their community and preview their changes thanks to the WordPress Customizer.  For instance, they can choose to use our default front pages for groups or members and they can choose between 4 layouts for the Members, Groups and Sites directory loops. Take a minute to discover this last feature in the following video.

They will also be able to reorder the Groups and Members primary navigations according to their preferences!

Improved UIs

First the notifications screens is now using Ajax and we’ve added a search functionality and the possibility to filter notifications by component actions. Of course we’ve kept the sort by date ordered DESC or ASC but it’s now located into the Date Received column header a bit like it’s the case in WordPress administration tables.

notifications

Then i invite you to watch this 3 minutes video to discover our new Group Invites and our new Private Messages UIs.

Finally we’ve started to work on a new extendable Activity Post form 🙂

Modularity

BP Nouveau is only loading what the BuddyPress setups it’s activated on needs. For instance if the Groups component is not active all the corresponding Javascript and PHP code won’t be loaded. SCSS files are now organized into modules.

Getting involved.

You want to help? You are very welcome. To ease our work we’ve packaged the template pack into a plugin we’ve named “next-template-packs”. It adds a new tab into the BuddyPress settings so that it’s easy to switch between BP Legacy and BP Nouveau. In a way it’s a possible interesting start for this core ticket (#7157). You’ll need the latest WordPress version and the latest BuddyPress version (trunk). Here’s the url of our github repository, we would be very pleased to receive some pull requests 😉

Let’s build together the most customizable Template Pack BuddyPress ever made!

#template-pack

#id