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

BuddyPress 4.3.0, a security and…

BuddyPress 4.3.0, a security and maintenance release, is now available. https://buddypress.org/2019/04/buddypress-4-3-0-security-and-maintenance-release/