Here’s the scenario: you build WordPress-powered sites for a living, or maybe for free, or even just as a hobby. Someone asks you to build their next site using a feature or two from BuddyPress. “Sure, no problem”, you say. In the privacy of your head, you’re thinking “I haven’t used BuddyPress before, but it’s meant to be a pretty nifty plugin — how hard can it be?”
A few months ago, I started working for Human Made. We help people build really robust, creative, enterprise-scale sites. While Human Made have several developers with really impressive BuddyPress development experience, I naturally look over outgoing proposals or roadmaps for those projects that might use BuddyPress to check it’s a good fit, and to help inform the project roadmap.
As we begin to ramp up work on sites powered by BuddyPress, it’s very likely that some Humans will work with BuddyPress for the first time! I think that’s REALLY exciting! As I started to write some tips from my colleagues on getting started with BuddyPress development, I figured I’d blog it publicly so others (hopefully) find it useful. So, without further ado…
Step 0: Install BuddyPress
In your dev. environment, search for BuddyPress on the Plugins > Add New screen in your WordPress admin area, and activate it. For first-timers, I’d recommend you switch theme to any of the default WordPress twenty* themes.
Step 1: Understand BuddyPress
To introduce you to the entire feature set of the BuddyPress, watch Rocío Valdivia’s presentation from BuddyCamp Brighton 2015:
Step 2: Use BuddyPress
You’d be surprised how often I’ve started to explain to people how to develop for BuddyPress, only to find out that they’ve never even tried the plugin! Now you have BuddyPress installed and have an idea of what it does, spend 30 minutes actually using it.
At a minimum, I’d recommending starting by adding new profile fields, completing your own user profile, upload a profile photo, and exploring the Activity Stream and Groups features. To do this, look at the Settings > BuddyPress and Users > Profile Fields screens in your WordPress admin area — and then visit the front of your site to see what’s changed!
Step 3: Change Theme
Open your user profile in one web browser. In another window or tab, go to your WordPress admin area and change the active theme to any other you have installed. Refresh the browser with your user profile, and BOOM!
It’ll look different, and sure, you’d probably want to add some custom CSS to make the BuddyPress templates work well in your new theme if this were a Real Site™, but essentially, BuddyPress works out the box on every WordPress theme. Pretty cool!
Step 4: Folder and File Organisation
There’s a structure and logic to the file and directory names within BuddyPress. Take a look inside /plugins/buddypress/. Each BuddyPress “component” lives inside its own folder. Go into bp-xprofile, which is the Extended Profile component.
Each component’s filenames share a pattern like bp-xprofile-SOMETHING.php. For the Extended Profile component:
- loader
- Main loader file for this component. Everything starts here.
- functions
- Non-template functions that could be used by anything in BuddyPress.
- actions
- WordPress/BuddyPress action hooks, and any callback functions.
- filters
- WordPress/BuddyPress filter hooks, and any callback functions.
- admin
- If this component implements anything inside the WordPress administration areas, that code will be here.
- cache
- A newer addition to BuddyPress, the file typically implements component-specific object cache clearing and other customisations that may be required.
- classes
- Loads PHP classes for this component. This file will probably be replaced by an auto-loader in the future.
- screens
- Screen functions are the controllers of BuddyPress. They will execute when their specific URL is caught. They will first save or manipulate data using business functions, then pass on the user to a template file.
- template
- Template functions. Typically implements a custom templating loop for this component.
Extended Profiles also has a few more extra files that other components do not have:
- activity
- Extended Profiles integrates with the Activity component. As these files are only loaded when the dependant component is enabled, they are the best place to organise any code that’s specific to another component.
- caps
- Integration with WordPress user roles and capabilities (“caps”).
- cssjs
- Registers and enqueues any new CSS or JS introduced by the component (perhaps not really needed nowadays, nevertheless we still use it).
Step 5: Use BuddyPress actions & filters to simplify dependencies
If you’ve ever written a plugin to extend another plugin, one of the first tasks you’ll have is to manage the dependency; how do you only load your plugin if the other plugin is active, and how do you load it after the other plugin? There are many ways — function_exists, class_exists, and more — and all are useful in the right situation. BuddyPress adds two more techniques: bp_is_active and a series of core actions and filters.
As a WordPress developer, you’ll be familiar with WordPress core actions and filters, such as init, wp, after_setup_theme, and many more. BuddyPress has its own versions of these core actions and filters, which exist to create the concept of plugin dependencies.
Plugin dependencies provide a safe way for plugins to execute code only when BuddyPress is installed and activated, without needing to do complicated guesswork. All of the action/filter names are just prefixed with “bp_” so that they’re easy to remember, and should be used at exactly the same time as when you’d use the plain WordPress version.
If you need to check if a specific component in BuddyPress is enabled (remember, components can be enabled/disabled by the site administrator), bp_is_active is your friend. Remember above I said the Extended Profiles component had an optional bp-xprofile-activity.php file, and that the file contained an integration with the Activity component? We use bp_is_active to make sure we only load the file when we need to.
Step 6: User navigation
BuddyPress has something that’s analogous to WordPress’ Toolbar; we have a user navigation bar, and it lets your site’s members explore the different content screens provided by a component. You’ll have already used it on your test site when you navigated around your user profile (i.e. to edit it, to upload a profile picture).
Most BuddyPress customisations that introduce significant user-facing features will want to add themselves to the navigation bar. To make this easy, we provide a function bp_core_new_nav_item. There’s example usage on our codex.
Conclusion
There’s a lot more I could say about how to build best with BuddyPress, and some of its idiosyncrasies, but the above is what I think I would want to know how to do if I were to start working with BuddyPress today for the first time.
If you think I’ve missed something that every new WordPress developer to BuddyPress should know to help them get started, leave a comment below!
Paul Gibbs 