Commons 1.10.10

I’ve just released version 1.10.10 of the CUNY Academic Commons. This maintenance release fixes a number of bugs:

  • Fix unformatted notifications related to bbPress activity when on secondary sites
  • In Reckoning plugin, count private posts
  • Fix incompatibility between bbPress and Add Users Widget plugin
  • Fix problem with redirects to group blogs with mapped domains that don’t support SSL

For complete details on the release, visit the 1.10.10 milestone.

Commons 1.8

I’ve just released version 1.8 of the CUNY Academic Commons. Version 1.8 is a major feature release for the Commons. Features of note:

  • An events calendar for Commons groups and users. The calendar allows users to create events and link these events to one or more groups. Users can then view events on individual or group calendars. Group-linked events are also hooked into our group email notification system. On the technical side, this feature is powered by a plugin called BP Event Organiser, written by Commons team members Raymond Hoh, Christian Wach, and Boone Gorges. BP Event Organiser is, in turn, an add-on for the popular Event Organiser, by Stephen Harris. Event Organiser is freely available in the wordpress.org repo. BP Event Organiser is available via Github, though please note that it’s still in beta form; a cleaned-up version for general use is planned fo the future.
  • When creating a new forum topic in a bbPress-powered group forum, users can optionally cross-post the new topic to other groups that they’re a member of. This custom functionality was developed by Daniel Jones of the Commons development team.
  • Users can now search through the contents of a single bbPress-powered group forum. This is powered by a custom plugin, bbp-single-forum-search, written by Ray Hoh of the Commons dev team.

The Commons 1.8 news post has a more complete round-up of new user-facing features in this release.

Commons 1.8 is also a major plugin/theme update release, including an upgrade to the WordPress 4.2.x series.

For complete details on the release, visit the 1.8 milestone.

Commons 1.7

I’ve just released version 1.7 of the CUNY Academic Commons. This is a major feature release for the Commons. Some highlights:

  • The new My Commons feature, which is a landing page that provides an at-a-glance view of activity related to your groups, friends, and sites on the Commons. My Commons is powered by the BuddyPress activity stream, and uses a custom page template for display.
  • A related feature is the ability to follow sites. Following a site will make activity from that site show up on your My Commons page, and your followed sites appear in a list on your Commons Profile. This feature is powered by the BuddyPress Followers plugin, written my team member Ray Hoh.
  • Group forums have been migrated from our ancient bbPress 1.x installation to the bbPress 2.x. I wrote a custom plugin that handled the migration between the old forum-attachments-for-buddypress plugin and our new forum attachment software.
  • BuddyPress Docs has also been brought up to date. The BuddyPress Docs In Group plugin was written as a shim to allow us to update without radically changing our interface.
  • Group members can download zip archives of group files, either en masse or by folder. This is a custom add-on for buddypress-group-documents, written by team member Daniel Jones.

For a complete list of changes in the release, visit the 1.7 milestone.

Commons In A Box – 1.0 beta 1

After nearly a year of development, the CUNY Academic Commons development team is proud to offer a first public beta of Commons In A Box.

Commons In A Box, funded by a generous grant from the Alfred P. Sloan Foundation, is a WordPress plugin that helps you to set up a powerful community site in no time flat. We’ve taken BuddyPress and packaged it with a number of the plugins that enhance the BuddyPress experience; bundled it with a brand-new theme based on the Infinity theme engine; and provided an installation experience that downloads, activates and configures these various pieces in just a few clicks. No more scouring Google and the wordpress.org plugin repository for BuddyPress plugins. No more wondering whether an upgrade to BuddyPress or one of your other plugins will break your site. Commons In A Box takes care of these aspects for you, so that you can spend your energy where it really counts: in fostering your community.


As you might gather from the name of the project, the impetus for Commons In A Box was the CUNY Academic Commons itself. Since launching in 2009, the Commons team has fielded countless inquiries about how we managed to pull together the site: what plugins are we using, what’s our theme called, where can I download the package. All sorts of organizations – and especially academic, educational, and non-profit institutions – have been realizing that a focused community space can enhance engagement both online and off, and the Commons has often served as a successful model. So, as we set out to put the Commons infrastructure into an easy-to-install-and-maintain package, we looked carefully at the technical aspects of the Commons that help to make the site a success. Commons In A Box represents what we think is an elegant set of tools that can help even those with modest technical skills go from zero to a functional site with as little hassle as possible, while also maintaining the flexibility and power of the free software platforms at the core of the package.

Our first task was to select a list of plugins that would replicate some of the best functionality of the CUNY Academic Commons. At the core of the package is BuddyPress, which provides extended profiles, groups, and the other social features that form the foundation of the Commons community. We also included a number of tools that have been custom-developed by the Commons development team over the last few years, ranging from collaborative document editing tools to widgets for featuring outstanding community content to the ability to respond to site content without leaving your email inbox. The package is rounded out with a number of third-party plugins that have proved crucial to the success of the Commons as a community platform, such as discussion boards and blogs linked to BuddyPress groups

Knowing which plugins to install is one barrier to entry that Commons In A Box aims to lower. The next is knowing which plugins are compatible with each other, and keeping them up to date. That’s why Commons In A Box features an installation and upgrade manager. For all plugins that are shipped with Commons In A Box, we remove the corresponding entries from the WordPress plugin screens, and centralize them on a single Commons In A Box admin panel. When you install Commons In A Box, we install recommended plugins on your behalf, making it that much quicker to get up and running. When upgrades are available for your CBOX-related plugins, we send you a single upgrade notice, and you can be totally up-to-date with a single click. We take care of making sure that the latest versions of each plugin work with each other. And we provide documentation that serves as a centralized resource for learning about BuddyPress components and add-ons.

Beyond the raw functionality of the Commons, we’ve worked tirelessly to make sure that our site’s design is professional and inviting, functional and fun. This work is reflected in Commons In A Box through the CBOX default theme, which echoes some of the more successful design considerations from the Commons. The theme includes a flexible, widgetized homepage template like you see on the Commons. We’ve packaged a large number of widget areas, making configuration a breeze. The Commons In A Box theme is powered by the Infinity Theming Engine, which strikes a perfect balance for the Commons In A Box project: it makes it easy for admins of any skill level to configure their site’s appearance, while also providing tools for designers and developers to create a truly unique community hub. Any BuddyPress-enabled WordPress theme will work well with Commons In A Box, but we think that our default theme will be a great starter for a large number of use cases.

The Commons In A Box team is hopeful that the Commons In A Box package will put BuddyPress-powered community sites within the reach of a far greater number of people than is currently the case. We’ve set up a community site where you can seek out help, talk with others who are using Commons In A Box, and share your own experiences setting up your own CBOX-powered community. And if you’re a developer and want to contribute to Commons In A Box itself, the project’s development home is github.com/cuny-academic-commons/commons-in-a-box.

Download Commons In A Box today, in the Plugins > Add New interface of your WordPress Dashboard, or by downloading directly from the wordpress.org plugin repository.

Upgrading from BuddyPress 1.0 to 1.1

The upgrade from BuddyPress 1.0.x to BuddyPress 1.1 on the CUNY Academic Commons posed a number of challenges. Between the big changes to theme structure, the one-click installation of bbPress forums, and ongoing plugin compatibility issues, a lot of planning and testing was required. This week, I and the rest of the CAC development team finally made the switch. Over the course of a few practice upgrades in development environments, followed by an upgrade on the production site, I developed a pretty detailed set of instructions for myself. I thought I’d write up an annotated version of those instructions, for the benefit of anyone who might be facing a similar upgrade.

The Academic Commons had previously been set up roughly along the same lines as Jim Groom describes here: with bbPress storing its data in a separate database, but through the cunning use of various clever plugins, sharing user data, cookies, and BP group info with the WPMU installation. BP 1.1 does things differently: the one click installation of BP forums expects to store its data in tables that exist in the BP/WP database. In order to save the old data, we had two choices: move the old data into the new structure, or make BP 1.1 recognize the old db setup. Fellow dev team member Chris Stein and I decided that the former choice would be the easiest and most future proof. Here’s how it was done.

    Dealing with bbPress forums

  1. Move orphan forums into groups. Strictly speaking, this doesn’t have to be done first, but if you’ve got bbPress forums that aren’t attached to groups, you’ve got to get them in a group in order for them to display in BP. To the best of my knowledge, there’s no really way to do this from the bbPress or BP admin panels, but it’s easy to do manually. Set up a new group for each forum (a “Help” forum might get a “Help” group, for example), make sure the group has discussion forums enabled, and then find the line in table wp_bp_groups_groupmeta corresponding to the group_id of the new group and meta key `forum_id`, and change the meta_value to match the forum number of the orphan group. Rinse and repeat.
  2. Export your bbPress database to a local file.
  3. Replace HTML markup. bbPress (my installation at least) stored formatting in HTML. The most common markup has to do with line breaks: bbPress interprets a single line break in a forum post as <br />, and double line breaks as </p> and <p>. Opening the local version of the bbPress db in a plain text editor, I did a couple big search-and-replaces:
    • </p>\\n<p> became \n\r\n\r (redundant UNIX newlines)
    • Some <p> and </p> tags still remain (single paragraph posts), which I replaced with an empty string
    • <br /> became \n\r

    You’ll also need to make sure that all references to tables in the SQL dump are replaced with the proper names. For me, that meant replacing things like bb_posts with wp_bb_posts, but it might be different depending on the prefixes you use for bbPress and WP. If you’re not sure about how BP will name the tables, do the one-button forum setup in BP 1.1 (as a new installation) and post a test forum item, to make sure the forums get created. Then check out the database to see how BP formats table names on your install.

  4. Upgrading

    The instructions at buddypress.org are quite helpful. Here’s a short version:

  5. Deactivate BP-dependent plugins. I once neglected to do this. If you do, and then deactivate BP, there is a very good chance that your entire site will go white-screen-of-death, as the plugins will be making reference to BP functions that do not exist. Check your plugin list three or four times to make sure you’ve deactivated each one that has to do with BuddyPress. I like to make a list, so that I remember which ones to activate after the upgrade (though some, like the bbPress integration plugins, won’t be necessary).
  6. Back up all your data. Always! I like to take a snapshot of the whole database, and then an individual export of the wp_sitemeta table. That way, if I screw anything up (say, by deactivating plugins in the wrong order!) I can bring the site back to life by reverting to a previous state that is known to work.
  7. Upgrade BuddyPress. Deactivate, upload, reactivate.
  8. Reactivate BP dependent plugins. I didn’t have too many issues with plugin compatibility, but you might, depending on what you use. Some plugins will not be necessary anymore, while others (like Forum Attachments for BuddyPress) become useful.
  9. Themes

    The CUNY Academic Commons was in the midst of a redesign, so it made sense to have the new design implemented in BuddyPress’s new, parent-child theme environment. Buddypress.org has some instructions that you might find helpful. Our theme consists of a highly customized home page, header, and footer, with interior BuddyPress pages that are more or less similar in terms of markup to the BuddyPress parent theme. Thus it made sense for us to create a child theme in wp-content/themes (by copying and renaming the bp-default folder that comes with BuddyPress), make our CSS changes, and fill our child theme with only those templates where our markup had to differ from bp-sn-parent. For us that means home.php, header.php, footer.php, functions.php (which does not override but adds to bp-sn-parent/functions.php), and a few other miscellaneous files. How to implement:

  10. Rename bp-themes. If BuddyPress sees the bp-themes folder, it will assume that you’re going to use the older, deprecated theme structure. I renamed it to bp-themes-old, and will remove it altogether once we’re 100% done with the migration.
  11. Move bp-sn-parent, bp-default, and your child theme to the main WP themes folder. In most cases this is wp-content/themes.
  12. Activate the themes in Dashboard > Site Admin > Themes. No need to activate bp-sn-parent, since it’s not used directly.
  13. Apply the child theme of your choice (either bp-default or your custom theme) to the main blog.
  14. Setting up the forums

    You’ve exported and modified the forum data from the bbPress standalone version, but you’ll still need to get them into BP.

  15. Rename /forums. In our case, our previous installation of bbPress just happened to live at [BP install dir]/forums – exactly where the BP 1.1 forum directory goes. I don’t think it’d hurt anything to leave that folder named the way it is (because of the order in which BP handles URL arguments), but just to be safe I changed it to forums-old.
  16. Set up BP forums. In Dashboard > BuddyPress > Forum Setup, set up forums as a new installation.
  17. Drop the empty forum tables from the BP database. I can’t remember whether BP creates the forum tables upon installation or upon the first forum post, but in any case you won’t be able to import your old data properly without first dropping any table prefixed with wp_bb_.
  18. Import the modified local version of your forum data. I did it in PHPMyAdmin, which was easy because the file had been exported in the form of a huge INSERT command. If all goes well – and it should! – you should now be able to navigate to your groups and see the proper forum posts for that group.

There are kinks we’re still trying to work out of the system. Some strange things happened to some users’ avatars after the upgrade. And tweaking the theme is turning out to be a hassle in a lot of ways. But overall, the migration of data – which I had lost a bit of sleep over – went extremely smoothly. Good luck!

Displaying the BuddyPress admin bar in other applications

By popular demand, here’s the method we used at the CUNY Academic Commons to get the BuddyPress admin bar to appear on the non-WP/BP portions of our site. In our case, that means MediaWiki and bbPress, but theoretically this method could work for any kind of software out there.

I should note that I did not devise this method. It was invented by the inimitable Zach and Lucas of Cast Iron Coding.

The concept is as follows. A bit of jQuery looks for a div of a certain ID on a page and, when it finds it, opens a dummy WP page that contains essentially nothing but the BP admin bar loader, which then appears on your page. Download the zip file containing the necessary files (admin-bar-integration) and follow these steps to make it happen.

  1. Upload the file page-component.php to your WP theme directory.
  2. Create a new page in WordPress. The page should be blank. In the Attributes box, select the Template called “Component (do not use)”. Name the page bpnavslug and publish it, making sure that you take note of the permalink. You’ll need that URL (relative to your site’s webroot) in step 4.
  3. If any part of your site creates a menu or a list of your WordPress pages, you’ll want to exclude this empty page from those listings. Find the function call wp_list_pages in your theme (often in header.php or index.php) and add an exclude argument. For example, if the page number of bpnavslug is 4, make sure all references to wp_list_pages read wp_list_pages('exclude=4').
  4. Open the file bp-bar-integration.js. On line 3, you’ll see the path /bpnavslug/. Replace it with the path to the bpnavslug post you created in step 2.
  5. Upload bp-bar-integration.js to your server. For the sake of argument, I’ll put mine at /wp-content/js/bp-bar-integration.js.
  6. Now let’s turn to the application where you want the admin bar to appear. Open the theme file that contains the </body> tag. In bbPress, for example, this is usually footer.php.
  7. Immediately before the body close tag, paste the following code:
    <div id="bpContainer">
    </div>
  8. Next, open the template file that contains the document head (header.php in bbPress, for instance). Make sure that jQuery is also called somewhere in the head. If it’s not, the following code will call up jQuery on a standard installation of WP:
    <script type='text/javascript' src='/wp-includes/js/jquery/jquery.js?ver=1.3.2'></script>
    Now paste the following line somewhere in the head (make sure it comes after the call to jQuery):
    <script type="text/javascript" src="/wp-content/js/bp-bar-integration.js"></script>
    Be sure to replace the src attribute with path from your upload in step 5.
    Finally, you’ll have to include the CSS for the admin bar. On a default installation of BuddyPress 1.0.3 or less, the following code will work:
    <link rel='stylesheet' id='bp-admin-bar-css' href='/wp-content/plugins/buddypress/bp-core/css/admin-bar.css' type='text/css' media='screen' />
    On a more recent version of BP (1.1+), the admin bar stylesheet has been rolled in with the rest of the styles. Either create your own stylesheet containing just the admin bar code, or import the entire stylesheet:
    <link rel='stylesheet' id='bp-admin-bar-css' href='/wp-content/themes/bp-default/style.css' type='text/css' media='screen' />

A note: This method appears to be incompatible with the Google Analytics WP plugin (which appends Google’s JS to the footer of every WP page, and thus into bpnavslug, and ends up gumming up the works). You could probably get around this with some creative if-statements in the GA plugin itself.

Good luck. Because of the diversity of people’s setups, I can’t guarantee that this method will work for everyone, nor can I provide support to everyone who tries it. But I do encourage you to post whether you’ve been successful in the comments, and to help each other figure things out.

New BuddyPress / bbPress plugin: Group Forum Subscription

BuddyPress and bbPress connect nicely, giving BuddyPress groups a handsome forum interface, but the software has no native ability to allow users to receive email when their favorite discussions are updated. Without this functionality, it can be hard for users to keep up-to-date with forums, and subsequently the forums are less active than they otherwise could be.

Subscription panel on group home page
A panel on each group home page lets users know whether they'll automatically receive email notifications of new discussion activity in the group

Group Forum Subscription is a set of plugins I’ve written (mostly on the BuddyPress side, with a small bbPress trigger plugin) that adds the missing forum notification functionality. GFS allows members of BuddyPress communities to subscribe to email notifications of new discussion activity. Subscriptions can be managed on a topic-by-topic or group-by-group basis.

Users can subscribe or unsubscribe from entire groups on the Notification Settings page
Users can subscribe or unsubscribe from entire groups on the Notification Settings page

The plugin also has some administrative settings. Notable among these is the ability to set up email notifications for the first time after the plugin is installed, so that users are automatically subscribed to topics in their groups without having to set it up manually. This is a setup process that we’ll be running in the upcoming days here on the CUNY Academic Commons.

Group Forum Subscription will currently work only on 1.0.x versions of BuddyPress – the brand-new BP 1.1 is not yet supported. I’ll be working on the upgrade very soon. Read more about the guts of the plugin or download it for yourself.