[ Index ]

PHP Cross Reference of BuddyPress




/src/bp-groups/classes/ -> class-bp-group-extension.php (summary)

BuddyPress Groups Classes.

File Size: 1699 lines (52 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class

BP_Group_Extension:: (49 methods):

Class: BP_Group_Extension  - X-Ref

API for creating group extensions without having to hardcode the content into
the theme.

To implement, extend this class. In your constructor, pass an optional array
of arguments to parent::init() to configure your widget. The config array
supports the following values:
- 'slug' A unique identifier for your extension. This value will be used
to build URLs, so make it URL-safe.
- 'name' A translatable name for your extension. This value is used to
populate the navigation tab, as well as the default titles for admin/
edit/create tabs.
- 'visibility' Set to 'public' (default) for your extension (the main tab
as well as the widget) to be available to anyone who can access the
group, 'private' otherwise.
- 'nav_item_position' An integer explaining where the nav item should
appear in the tab list.
- 'enable_nav_item' Set to true for your extension's main tab to be
available to anyone who can access the group.
- 'nav_item_name' The translatable text you want to appear in the nav tab.
Defaults to the value of 'name'.
- 'display_hook' The WordPress action that the widget_display() method is
hooked to.
- 'template_file' The template file that will be used to load the content
of your main extension tab. Defaults to 'groups/single/plugins.php'.
- 'screens' A multi-dimensional array, described below.
- 'access' Which users can visit the plugin's tab.
- 'show_tab' Which users can see the plugin's navigation tab.

BP_Group_Extension uses the concept of "settings screens". There are three
contexts for settings screens:
- 'create', which inserts a new step into the group creation process
- 'edit', which adds a tab for your extension into the Admin section of
a group
- 'admin', which adds a metabox to the Groups administration panel in the
WordPress Dashboard
Each of these settings screens is populated by a pair of methods: one that
creates the markup for the screen, and one that processes form data
submitted from the screen. If your plugin needs screens in all three
contexts, and if the markup and form processing logic will be the same in
each case, you can define two methods to handle all of the screens:
function settings_screen() {}
function settings_screen_save() {}
If one or more of your settings screen needs separate logic, you may define
context-specific methods, for example:
function edit_screen() {}
function edit_screen_save() {}
BP_Group_Extension will use the more specific methods if they are available.

You can further customize the settings screens (tab names, etc) by passing
an optional 'screens' parameter to the init array. The format is as follows:
'screens' => array(
'create' => array(
'slug' => 'foo',
'name' => 'Foo',
'position' => 55,
'screen_callback' => 'my_create_screen_callback',
'screen_save_callback' => 'my_create_screen_save_callback',
'edit' => array( // ...
Only provide those arguments that you actually want to change from the
default configuration. BP_Group_Extension will do the rest.

Note that the 'edit' screen accepts an additional parameter: 'submit_text',
which defines the text of the Submit button automatically added to the Edit
screen of the extension (defaults to 'Save Changes'). Also, the 'admin'
screen accepts two additional parameters: 'metabox_priority' and
'metabox_context'. See the docs for add_meta_box() for more details on these

Prior to BuddyPress 1.7, group extension configurations were set slightly
differently. The legacy method is still supported, though deprecated.

display( $group_id = null )   X-Ref
The content of the group tab.

param: int|null $group_id ID of the group to display.
since: 1.1.0

widget_display()   X-Ref
Content displayed in a widget sidebar, if applicable.

since: 1.1.0

settings_screen( $group_id = null )   X-Ref
No description

settings_screen_save( $group_id = null )   X-Ref
No description

edit_screen( $group_id = null )   X-Ref
No description

edit_screen_save( $group_id = null )   X-Ref
No description

create_screen( $group_id = null )   X-Ref
No description

create_screen_save( $group_id = null )   X-Ref
No description

admin_screen( $group_id = null )   X-Ref
No description

admin_screen_save( $group_id = null )   X-Ref
No description

init( $args = array()   X-Ref
Initialize the extension, using your config settings.

Your plugin should call this method at the very end of its
constructor, like so:

public function __construct() {
$args = array(
'slug' => 'my-group-extension',
'name' => 'My Group Extension',
// ...

parent::init( $args );

param: array $args {
since: 1.8.0
since: 2.1.0 Added 'access' and 'show_tab' arguments to `$args`.

_register()   X-Ref
The main setup routine for the extension.

This method contains the primary logic for setting up an extension's
configuration, setting up backward compatibility for legacy plugins,
and hooking the extension's screen functions into WP and BP.

Marked 'public' because it must be accessible to add_action().
However, you should never need to invoke this method yourself - it
is called automatically at the right point in the load order by

since: 1.1.0

setup_class_info()   X-Ref
Set up some basic info about the Extension.

Here we collect the name of the extending class, as well as a
ReflectionClass that is used in get_screen_callback() to determine
whether your extension overrides certain callback methods.

since: 1.8.0

get_group_id()   X-Ref
Get the current group ID.

Check for:
- current group
- new group
- group admin

return: int
since: 1.8.0

get_default_screens()   X-Ref
Gather configuration data about your screens.

return: array
since: 1.8.0

setup_screens()   X-Ref
Set up screens array based on params.

since: 1.8.0

setup_access_settings()   X-Ref
Set up access-related settings for this extension.

since: 2.1.0

user_meets_access_condition( $access_condition )   X-Ref
Check whether the current user meets an access condition.

return: bool
param: string $access_condition 'anyone', 'loggedin', 'member',
since: 2.1.0

setup_display_hooks()   X-Ref
Hook this extension's group tab into BuddyPress, if necessary.

since: 1.8.0

_display_hook()   X-Ref
Hook the main display method, and loads the template file.

since: 1.1.0

call_display()   X-Ref
Call the display() method.

We use this wrapper so that we can pass the group_id to the
display() callback.

since: 2.1.1

user_can_see_nav_item( $user_can_see_nav_item = false )   X-Ref
Determine whether the current user should see this nav tab.

Note that this controls only the display of the navigation item.
Access to the tab is controlled by the user_can_visit() check.

return: bool
param: bool $user_can_see_nav_item Whether or not the user can see the nav item.
since: 2.1.0

user_can_visit( $user_can_visit = false )   X-Ref
Determine whether the current user has access to visit this tab.

Note that this controls the ability of a user to access a tab.
Display of the navigation item is controlled by user_can_see_nav_item().

return: bool
param: bool $user_can_visit Whether or not the user can visit the tab.
since: 2.1.0

group_access_protection( $user_can_visit, &$no_access_args )   X-Ref
Filter the access check in bp_groups_group_access_protection() for this extension.

Note that $no_access_args is passed by reference, as there are some
circumstances where the bp_core_no_access() arguments need to be
modified before the redirect takes place.

return: bool
param: bool  $user_can_visit Whether or not the user can visit the tab.
param: array $no_access_args Array of args to help determine access.
since: 2.1.0

setup_create_hooks()   X-Ref
Hook this extension's Create step into BuddyPress, if necessary.

since: 1.8.0

maybe_create_screen()   X-Ref
Call the create_screen() method, if we're on the right page.

since: 1.8.0

maybe_create_screen_save()   X-Ref
Call the create_screen_save() method, if we're on the right page.

since: 1.8.0

setup_edit_hooks()   X-Ref
Hook this extension's Edit panel into BuddyPress, if necessary.

since: 1.8.0

call_edit_screen()   X-Ref
Call the edit_screen() method.

Previous versions of BP_Group_Extension required plugins to provide
their own Submit button and nonce fields when building markup. In
BP 1.8, this requirement was lifted - BP_Group_Extension now handles
all required submit buttons and nonces.

We put the edit screen markup into an output buffer before echoing.
This is so that we can check for the presence of a hardcoded submit
button, as would be present in legacy plugins; if one is found, we
do not auto-add our own button.

since: 1.8.0

call_edit_screen_save()   X-Ref
Check the nonce, and call the edit_screen_save() method.

since: 1.8.0

call_edit_screen_template_loader()   X-Ref
Load the template that houses the Edit screen.

Separated out into a callback so that it can run after all other
Group Extensions have had a chance to register their navigation, to
avoid missing tabs.

Hooked to 'bp_screens'.

since: 1.8.0

maybe_add_submit_button( $screen = '' )   X-Ref
Add a submit button to the edit form, if it needs one.

There's an inconsistency in the way that the group Edit and Create
screens are rendered: the Create screen has a submit button built
in, but the Edit screen does not. This function allows plugin
authors to write markup that does not contain the submit button for
use on both the Create and Edit screens - BP will provide the button
if one is not found.

return: string $screen The same markup, with a submit button added.
param: string $screen The screen markup, captured in the output
since: 1.8.0

has_submit_button( $screen = '' )   X-Ref
Does the given markup have a submit button?

return: bool True if a Submit button is found, otherwise false.
param: string $screen The markup to check.
since: 1.8.0

detect_post_save_redirect( $redirect = '' )   X-Ref
Detect redirects hardcoded into edit_screen_save() callbacks.

return: string
param: string $redirect Redirect string.
since: 2.1.0

setup_admin_hooks()   X-Ref
Hook this extension's Admin metabox into BuddyPress, if necessary.

since: 1.8.0

call_admin_screen()   X-Ref
Call the admin_screen() method, and add a nonce field.

since: 1.8.0

call_admin_screen_save()   X-Ref
Check the nonce, and call the admin_screen_save() method.

since: 1.8.0

_meta_box_display_callback()   X-Ref
Create the Dashboard meta box for this extension.

since: 1.7.0

nonce_field( $context = '' )   X-Ref
Generate the nonce fields for a settings form.

The nonce field name (the second param passed to wp_nonce_field)
contains this extension's slug and is thus unique to this extension.
This is necessary because in some cases (namely, the Dashboard),
more than one extension may generate nonces on the same page, and we
must avoid name clashes.

param: string $context Screen context. 'create', 'edit', or 'admin'.
since: 1.8.0

check_nonce( $context = '' )   X-Ref
Check the nonce on a submitted settings form.

param: string $context Screen context. 'create', 'edit', or 'admin'.
since: 1.8.0

is_screen_enabled( $context = '' )   X-Ref
Is the specified screen enabled?

To be enabled, a screen must both have the 'enabled' key set to true
(legacy: $this->enable_create_step, etc), and its screen_callback
must also exist and be callable.

return: bool True if the screen is enabled, otherwise false.
param: string $context Screen context. 'create', 'edit', or 'admin'.
since: 1.8.0

get_screen_callback( $context = '', $type = 'screen' )   X-Ref
Get the appropriate screen callback for the specified context/type.

BP Group Extensions have three special "screen contexts": create,
admin, and edit. Each of these contexts has a corresponding
_screen() and _screen_save() method, which allow group extension
plugins to define different markup and logic for each context.

BP also supports fallback settings_screen() and
settings_screen_save() methods, which can be used to define markup
and logic that is shared between context. For each context, you may
either provide context-specific methods, or you can let BP fall back
on the shared settings_* callbacks.

For example, consider a BP_Group_Extension implementation that looks
like this:

// ...
function create_screen( $group_id ) { ... }
function create_screen_save( $group_id ) { ... }
function settings_screen( $group_id ) { ... }
function settings_screen_save( $group_id ) { ... }
// ...

BP_Group_Extension will use your create_* methods for the Create
steps, and will use your generic settings_* methods for the Edit
and Admin contexts. This schema allows plugin authors maximum
flexibility without having to repeat themselves.

The get_screen_callback() method uses a ReflectionClass object to
determine whether your extension has provided a given callback.

return: callable A callable function handle.
param: string $context Screen context. 'create', 'edit', or 'admin'.
param: string $type    Screen type. 'screen' or 'screen_save'. Default:
since: 1.8.0

parse_args_r( &$a, $b )   X-Ref
Recursive argument parsing.

This acts like a multi-dimensional version of wp_parse_args() (minus
the querystring parsing - you must pass arrays).

Values from $a override those from $b; keys in $b that don't exist
in $a are passed through.

This is different from array_merge_recursive(), both because of the
order of preference ($a overrides $b) and because of the fact that
array_merge_recursive() combines arrays deep in the tree, rather
than overwriting the b array with the a array.

The implementation of this function is specific to the needs of
BP_Group_Extension, where we know that arrays will always be
associative, and that an argument under a given key in one array
will be matched by a value of identical depth in the other one. The
function is NOT designed for general use, and will probably result
in unexpected results when used with data in the wild. See, eg,

return: array Parsed arguments.
param: array $a First set of arguments.
param: array $b Second set of arguments.
since: 1.8.0

__get( $key )   X-Ref
Provide access to otherwise unavailable object properties.

This magic method is here for backward compatibility with plugins
that refer to config properties that have moved to a different
location (such as enable_create_step, which is now at

The legacy_properties array is set up in

return: mixed The value if found, otherwise null.
param: string $key Property name.
since: 1.8.0

__isset( $key )   X-Ref
Provide a fallback for isset( $this->foo ) when foo is unavailable.

This magic method is here for backward compatibility with plugins
that have set their class config options directly in the class
constructor. The parse_legacy_properties() method of the current
class needs to check whether any legacy keys have been put into the
$this->data array.

return: bool True if the value is set, otherwise false.
param: string $key Property name.
since: 1.8.0

__set( $key, $value )   X-Ref
Allow plugins to set otherwise unavailable object properties.

This magic method is here for backward compatibility with plugins
that may attempt to modify the group extension by manually assigning
a value to an object property that no longer exists, such as

param: string $key Property name.
param: mixed  $value Property value.
since: 1.8.0

get_legacy_property_list()   X-Ref
Return a list of legacy properties.

The legacy implementation of BP_Group_Extension used all of these
object properties for configuration. Some have been moved.

return: array List of legacy property keys.
since: 1.8.0

parse_legacy_properties()   X-Ref
Parse legacy properties.

The old standard for BP_Group_Extension was for plugins to register
their settings as properties in their constructor. The new method is
to pass a config array to the init() method. In order to support
legacy plugins, we slurp up legacy properties, and later on we'll
parse them into the new init() array.

since: 1.8.0

setup_legacy_properties()   X-Ref
Set up legacy properties.

This method is responsible for ensuring that all legacy config
properties are stored in an array $this->legacy_properties, so that
they remain available to plugins that reference the variables at
their old locations.

since: 1.8.0

Generated: Thu Jun 13 01:00:57 2024 Cross-referenced by PHPXref 0.7.1