[buddypress-trac] [BuddyPress] #4955: Improvements to BP_Group_Extension

[buddypress-trac]

#4955: Improvements to BP_Group_Extension
--------------------------+---------------------------
 Reporter:  boonebgorges  |       Owner:  boonebgorges
     Type:  task          |      Status:  new
 Priority:  high          |   Milestone:  1.8
Component:  Groups        |     Version:
 Severity:  major         |  Resolution:
 Keywords:                |
--------------------------+---------------------------

Comment (by boonebgorges):

 4955.01.patch is a first pass at a major cleanup of `BP_Group_Extension`.
 Several of the problems I needed to solve had to be solved at the same
 time, thus the huge patch. A summary of the improvements:

 1. Markup requirements are now standardized between `edit_screen()`,
 `admin_screen()`, and `create_screen()`. You no longer need to provide a
 Submit button in your `edit_screen()` markup - we provide it for you
 (though if an existing plugin *does* provide its own Submit button, we
 detect it and do not add a second one). Nonces are now created and checked
 automatically for all form contexts. And `BP_Group_Extension` is smart
 about checking whether your markup should appear in a given place - you
 don't have to check `if ( bp_is_group_creation_step( $this->slug ) )` etc
 anymore, because we do it for you.

 2. Because markup and logic requirements for the `_screen()` and
 `_screen_save()` functions are now identical, I've introduced support for
 generic fallback methods called `settings_screen()` and
 `settings_screen_save()`. When you define these methods in your extension,
 they'll provide the markup and save-logic for your Create, Edit, and Admin
 panels. If you provide the specific methods for a given context (say,
 `edit_screen()` and `create_screen_save()`), `BP_Group_Extension` detects
 it, and uses the more specific ones instead. So: maximum flexibility for
 plugin authors, while making it as simple as possible for the majority of
 plugins (which will share logic/markup between all those screens).

 3. Instead of configuring your extension using a hodge-podge of object
 properties (like `$this->enable_nav_item = true;` in your `__construct()`
 method), I've converted to using an array of config options, which should
 then be passed to `parent::init()` at the end of the extension
 constructor. This has several major benefits:
     - It keeps all config in a single place
     - It mirrors the way that `BP_Component` extensions work
     - It allows us to use `wp_parse_args()` style logic to parse custom
 params with defaults. One very cool feature here is that I've added a
 recursive version of `wp_parse_args()`, which means that your config array
 only has to contain the specific values that you want to change, even if
 they're one or two levels deep in the array - `BP_Group_Extension` will
 parse them intelligently with the default config. (It's like child theming
 for your config arrays :) )

     See the patch, and the inline documentation, for more details on how
 these arguments look. (They're mostly ported directly over, except for
 those that are specific to 'edit', 'create', and 'admin', in which case
 they've been moved to a structured 'screens' array.)

 4. Complete backward compatibility with existing `BP_Group_Extension`
 plugins. I had to do a couple of tricks to ensure that plugin configured
 the old way could be converted to the new way (see the 'Legacy Support'
 section of the patch). I've written unit tests for the trickiest bits of
 this backward compatibility layer. Testing with a dozen or so plugins that
 use `BP_Group_Extension` in different ways.

 5. Basic reorganization and modularizing. `BP_Group_Extension` is
 currently a rat's nest, especially the `_register()` method and its inline
 logic. I have reorganized the class so that it makes much more sense. I've
 broken logic out into its own separate (and testable) methods. And I've
 written inline docs for the entire thing.

 I'm attaching three files:
 a. 4955.01.patch is the patch, which includes unit tests
 b. bp-group-extension.php is a clean copy of the newly reorganized class.
 You might find this a bit easier to read, if you're going to get into the
 nitty-gritty.
 c. bpge_test.zip is a small plugin that demonstrates how awesome the
 `BP_Group_Extension` class. It contains two extensions: one is basic, and
 one is a bit more customized. You might consider starting with this plugin
 *first* (before spending much time with the patch), so that you can see
 firsthand how the changes in 4955.01.patch make `BP_Group_Extension` so
 much more flexible and pleasant to use.

 Thanks in advance for your feedback.

-- 
Ticket URL: <https://buddypress.trac.wordpress.org/ticket/4955#comment:7>
BuddyPress <http://buddypress.org/>
BuddyPress