Skip to:
Content

BuddyPress.org


Ignore:
Timestamp:
11/22/2015 04:58:34 AM (5 years ago)
Author:
tw2113
Message:

More docs cleanup for BP-Groups component.

See #6401.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/bp-groups/classes/class-bp-group-extension.php

    r10248 r10373  
    3636 *     of your main extension tab. Defaults to 'groups/single/plugins.php'.
    3737 *   - 'screens' A multi-dimensional array, described below.
    38  *   - 'access' Which users can visit the plugin's tab.
    39  *   - 'show_tab' Which users can see the plugin's navigation tab.
     38 *   - 'access' Which users can visit the plugin's tab.
     39 *   - 'show_tab' Which users can see the plugin's navigation tab.
    4040 *
    4141 * BP_Group_Extension uses the concept of "settings screens". There are three
     
    6363 *   'screens' => array(
    6464 *       'create' => array(
    65  *       'slug' => 'foo',
    66  *       'name' => 'Foo',
    67  *       'position' => 55,
    68  *       'screen_callback' => 'my_create_screen_callback',
    69  *       'screen_save_callback' => 'my_create_screen_save_callback',
    70  *  ),
    71  *  'edit' => array( // ...
     65 *       'slug' => 'foo',
     66 *       'name' => 'Foo',
     67 *       'position' => 55,
     68 *       'screen_callback' => 'my_create_screen_callback',
     69 *       'screen_save_callback' => 'my_create_screen_save_callback',
     70 *  ),
     71 *  'edit' => array( // ...
    7272 *   ),
    7373 * Only provide those arguments that you actually want to change from the
     
    272272     * The content of the group tab.
    273273     *
    274      * @param int|null $group_id
     274     * @param int|null $group_id ID of the group to display.
    275275     */
    276276    public function display( $group_id = null ) {}
     
    281281    public function widget_display() {}
    282282
    283     // *_screen() displays the settings form for the given context
    284     // *_screen_save() processes data submitted via the settings form
    285     // The settings_* methods are generic fallbacks, which can optionally
    286     // be overridden by the more specific edit_*, create_*, and admin_*
    287     // versions.
     283    /*
     284     * *_screen() displays the settings form for the given context
     285     * *_screen_save() processes data submitted via the settings form
     286     * The settings_* methods are generic fallbacks, which can optionally
     287     * be overridden by the more specific edit_*, create_*, and admin_*
     288     * versions.
     289     */
    288290    public function settings_screen( $group_id = null ) {}
    289291    public function settings_screen_save( $group_id = null ) {}
     
    354356     */
    355357    public function init( $args = array() ) {
    356         // Store the raw arguments
     358        // Store the raw arguments.
    357359        $this->params_raw = $args;
    358360
     
    361363        // compatibility with these plugins, we detect whether this is
    362364        // one of those legacy plugins, and parse any legacy arguments
    363         // with those passed to init()
     365        // with those passed to init().
    364366        $this->parse_legacy_properties();
    365367        $args = $this->parse_args_r( $args, $this->legacy_properties_converted );
    366368
    367         // Parse with defaults
     369        // Parse with defaults.
    368370        $this->params = $this->parse_args_r( $args, array(
    369371            'slug'              => $this->slug,
     
    399401    public function _register() {
    400402
    401         // Detect and parse properties set by legacy extensions
     403        // Detect and parse properties set by legacy extensions.
    402404        $this->parse_legacy_properties();
    403405
    404406        // Initialize, if necessary. This should only happen for
    405         // legacy extensions that don't call parent::init() themselves
     407        // legacy extensions that don't call parent::init() themselves.
    406408        if ( true !== $this->initialized ) {
    407409            $this->init();
    408410        }
    409411
    410         // Set some config values, based on the parsed params
     412        // Set some config values, based on the parsed params.
    411413        $this->group_id          = $this->get_group_id();
    412414        $this->slug              = $this->params['slug'];
     
    418420        $this->template_file     = $this->params['template_file'];
    419421
    420         // Configure 'screens': create, admin, and edit contexts
     422        // Configure 'screens': create, admin, and edit contexts.
    421423        $this->setup_screens();
    422424
    423         // Configure access-related settings
     425        // Configure access-related settings.
    424426        $this->setup_access_settings();
    425427
    426428        // Mirror configuration data so it's accessible to plugins
    427         // that look for it in its old locations
     429        // that look for it in its old locations.
    428430        $this->setup_legacy_properties();
    429431
    430         // Hook the extension into BuddyPress
     432        // Hook the extension into BuddyPress.
    431433        $this->setup_display_hooks();
    432434        $this->setup_create_hooks();
     
    468470    public static function get_group_id() {
    469471
    470         // Usually this will work
     472        // Usually this will work.
    471473        $group_id = bp_get_current_group_id();
    472474
    473         // On the admin, get the group id out of the $_GET params
     475        // On the admin, get the group id out of the $_GET params.
    474476        if ( empty( $group_id ) && is_admin() && ( isset( $_GET['page'] ) && ( 'bp-groups' === $_GET['page'] ) ) && ! empty( $_GET['gid'] ) ) {
    475477            $group_id = (int) $_GET['gid'];
     
    477479
    478480        // This fallback will only be hit when the create step is very
    479         // early
     481        // early.
    480482        if ( empty( $group_id ) && bp_get_new_group_id() ) {
    481483            $group_id = bp_get_new_group_id();
     
    484486        // On some setups, the group id has to be fetched out of the
    485487        // $_POST array
    486         // @todo Figure out why this is happening during group creation
     488        // @todo Figure out why this is happening during group creation.
    487489        if ( empty( $group_id ) && isset( $_POST['group_id'] ) ) {
    488490            $group_id = (int) $_POST['group_id'];
     
    552554     */
    553555    protected function setup_access_settings() {
    554         // Bail if no group ID is available
     556        // Bail if no group ID is available.
    555557        if ( empty( $this->group_id ) ) {
    556558            return;
    557559        }
    558560
    559         // Backward compatibility
     561        // Backward compatibility.
    560562        if ( isset( $this->params['enable_nav_item'] ) ) {
    561563            $this->enable_nav_item = (bool) $this->params['enable_nav_item'];
    562564        }
    563565
    564         // Tab Access
     566        // Tab Access.
    565567        $this->user_can_visit = false;
    566568
    567569        // Backward compatibility for components that do not provide
    568         // explicit 'access' parameter
     570        // explicit 'access' parameter.
    569571        if ( empty( $this->params['access'] ) ) {
    570572            if ( false === $this->enable_nav_item ) {
     
    576578
    577579                if ( ! empty( $group->status ) && 'public' === $group->status ) {
    578                     // Tabs in public groups are accessible to anyone by default
     580                    // Tabs in public groups are accessible to anyone by default.
    579581                    $this->params['access'] = 'anyone';
    580582                } else {
    581                     // All other groups have members-only as the default
     583                    // All other groups have members-only as the default.
    582584                    $this->params['access'] = 'member';
    583585                }
     
    585587        }
    586588
    587         // Parse multiple access conditions into an array
     589        // Parse multiple access conditions into an array.
    588590        $access_conditions = $this->params['access'];
    589591        if ( ! is_array( $access_conditions ) ) {
     
    592594
    593595        // If the current user meets at least one condition, the
    594         // get access
     596        // get access.
    595597        foreach ( $access_conditions as $access_condition ) {
    596598            if ( $this->user_meets_access_condition( $access_condition ) ) {
     
    600602        }
    601603
    602         // Tab Visibility
     604        // Tab Visibility.
    603605        $this->user_can_see_nav_item = false;
    604606
    605607        // Backward compatibility for components that do not provide
    606         // explicit 'show_tab' parameter
     608        // explicit 'show_tab' parameter.
    607609        if ( empty( $this->params['show_tab'] ) ) {
    608610            if ( false === $this->params['enable_nav_item'] ) {
    609                 // enable_nav_item is only false if it's been
     611                // The enable_nav_item index is only false if it's been
    610612                // defined explicitly as such in the
    611                 // constructor. So we always trust this value
     613                // constructor. So we always trust this value.
    612614                $this->params['show_tab'] = 'noone';
    613615
     
    616618                // we assume this  is a legacy extension.
    617619                // Legacy behavior is that enable_nav_item=true +
    618                 // visibility=private implies members-only
     620                // visibility=private implies members-only.
    619621                if ( 'public' !== $this->visibility ) {
    620622                    $this->params['show_tab'] = 'member';
     
    625627            } else {
    626628                // No show_tab or enable_nav_item value is
    627                 // available, so match the value of 'access'
     629                // available, so match the value of 'access'.
    628630                $this->params['show_tab'] = $this->params['access'];
    629631            }
    630632        }
    631633
    632         // Parse multiple access conditions into an array
     634        // Parse multiple access conditions into an array.
    633635        $access_conditions = $this->params['show_tab'];
    634636        if ( ! is_array( $access_conditions ) ) {
     
    637639
    638640        // If the current user meets at least one condition, the
    639         // get access
     641        // get access.
    640642        foreach ( $access_conditions as $access_condition ) {
    641643            if ( $this->user_meets_access_condition( $access_condition ) ) {
     
    697699    protected function setup_display_hooks() {
    698700
    699         // Bail if not a group
     701        // Bail if not a group.
    700702        if ( ! bp_is_group() ) {
    701703            return;
    702704        }
    703705
    704         // Backward compatibility only
     706        // Backward compatibility only.
    705707        if ( ( 'public' !== $this->visibility ) && ! buddypress()->groups->current_group->user_has_access ) {
    706708            return;
     
    740742            ) );
    741743
    742             // When we are viewing the extension display page, set the title and options title
     744            // When we are viewing the extension display page, set the title and options title.
    743745            if ( bp_is_current_action( $this->slug ) ) {
    744746                add_filter( 'bp_group_user_has_access',   array( $this, 'group_access_protection' ), 10, 2 );
     
    748750        }
    749751
    750         // Hook the group home widget
     752        // Hook the group home widget.
    751753        if ( ! bp_current_action() && bp_is_current_action( 'home' ) ) {
    752754            add_action( $this->display_hook, array( &$this, 'widget_display' ) );
     
    790792     * @since 2.1.0
    791793     *
    792      * @param bool $user_can_see_nav_item
    793      *
     794     * @param bool $user_can_see_nav_item Whether or not the user can see the nav item.
    794795     * @return bool
    795796     */
     
    807808     * @since 2.1.0
    808809     *
    809      * @param bool $user_can_visit
    810      *
     810     * @param bool $user_can_visit Whether or not the user can visit the tab.
    811811     * @return bool
    812812     */
     
    828828     * @since 2.1.0
    829829     *
    830      * @param bool  $user_can_visit
    831      * @param array $no_access_args
    832      *
     830     * @param bool  $user_can_visit Whether or not the user can visit the tab.
     831     * @param array $no_access_args Array of args to help determine access.
    833832     * @return bool
    834833     */
     
    864863        $screen = $this->screens['create'];
    865864
    866         // Insert the group creation step for the new group extension
     865        // Insert the group creation step for the new group extension.
    867866        buddypress()->groups->group_creation_steps[ $screen['slug'] ] = array(
    868867            'name'     => $screen['name'],
     
    875874        // correct group creation step). Hooked in separate
    876875        // methods because current creation step info not yet
    877         // available at this point
     876        // available at this point.
    878877        add_action( 'groups_custom_create_steps', array( $this, 'maybe_create_screen' ) );
    879878        add_action( 'groups_create_group_step_save_' . $screen['slug'], array( $this, 'maybe_create_screen_save' ) );
     
    894893
    895894        // The create screen requires an additional nonce field
    896         // due to a quirk in the way the templates are built
     895        // due to a quirk in the way the templates are built.
    897896        wp_nonce_field( 'groups_create_save_' . bp_get_groups_current_create_step(), '_wpnonce', false );
    898897    }
     
    920919     */
    921920    protected function setup_edit_hooks() {
    922         // Bail if not in a group
     921        // Bail if not in a group.
    923922        if ( ! bp_is_group() ) {
    924923            return;
    925924        }
    926925
    927         // Bail if not an edit screen
     926        // Bail if not an edit screen.
    928927        if ( ! $this->is_screen_enabled( 'edit' ) || ! bp_is_item_admin() ) {
    929928            return;
     
    948947        );
    949948
    950         // Should we add a menu to the Group's WP Admin Bar
     949        // Should we add a menu to the Group's WP Admin Bar.
    951950        if ( ! empty( $screen['show_in_admin_bar'] ) ) {
    952951            $subnav_args['show_in_admin_bar'] = true;
    953952        }
    954953
    955         // Add the tab to the manage navigation
     954        // Add the tab to the manage navigation.
    956955        bp_core_new_subnav_item( $subnav_args );
    957956
    958         // Catch the edit screen and forward it to the plugin template
     957        // Catch the edit screen and forward it to the plugin template.
    959958        if ( bp_is_groups_component() && bp_is_current_action( 'admin' ) && bp_is_action_variable( $screen['slug'], 0 ) ) {
    960959            $this->call_edit_screen_save( $this->group_id );
     
    963962
    964963            // Determine the proper template and save for later
    965             // loading
     964            // loading.
    966965            if ( '' !== bp_locate_template( array( 'groups/single/home.php' ), false ) ) {
    967966                $this->edit_screen_template = '/groups/single/home';
     
    973972
    974973            // We load the template at bp_screens, to give all
    975             // extensions a chance to load
     974            // extensions a chance to load.
    976975            add_action( 'bp_screens', array( $this, 'call_edit_screen_template_loader' ) );
    977976        }
     
    10151014
    10161015        // When DOING_AJAX, the POST global will be populated, but we
    1017         // should assume it's a save
     1016        // should assume it's a save.
    10181017        if ( defined( 'DOING_AJAX' ) && DOING_AJAX ) {
    10191018            return;
     
    10231022
    10241023        // Detect whether the screen_save_callback is performing a
    1025         // redirect, so that we don't do one of our own
     1024        // redirect, so that we don't do one of our own.
    10261025        add_filter( 'wp_redirect', array( $this, 'detect_post_save_redirect' ) );
    10271026
    1028         // Call the extension's save routine
     1027        // Call the extension's save routine.
    10291028        call_user_func( $this->screens['edit']['screen_save_callback'], $this->group_id );
    10301029
    1031         // Clean up detection filters
     1030        // Clean up detection filters.
    10321031        remove_filter( 'wp_redirect', array( $this, 'detect_post_save_redirect' ) );
    10331032
    1034         // Perform a redirect only if one has not already taken place
     1033        // Perform a redirect only if one has not already taken place.
    10351034        if ( empty( $this->post_save_redirect ) ) {
    10361035
     
    10821081     * @param string $screen The screen markup, captured in the output
    10831082     *                       buffer.
    1084      *
    10851083     * @return string $screen The same markup, with a submit button added.
    10861084     */
     
    11041102     *
    11051103     * @param string $screen The markup to check.
    1106      *
    11071104     * @return bool True if a Submit button is found, otherwise false.
    11081105     */
     
    11181115     * @since 2.1.0
    11191116     *
    1120      * @param string $redirect
    1121      *
     1117     * @param string $redirect Redirect string.
    11221118     * @return string
    11231119     */
     
    11421138        }
    11431139
    1144         // Hook the admin screen markup function to the content hook
     1140        // Hook the admin screen markup function to the content hook.
    11451141        add_action( 'bp_groups_admin_meta_box_content_' . $this->slug, array( $this, 'call_admin_screen' ) );
    11461142
    1147         // Initialize the metabox
     1143        // Initialize the metabox.
    11481144        add_action( 'bp_groups_admin_meta_boxes', array( $this, '_meta_box_display_callback' ) );
    11491145
    1150         // Catch the metabox save
     1146        // Catch the metabox save.
    11511147        add_action( 'bp_group_admin_edit_after', array( $this, 'call_admin_screen_save' ), 10 );
    11521148    }
     
    12321228     *
    12331229     * @param string $context Screen context. 'create', 'edit', or 'admin'.
    1234      *
    12351230     * @return bool True if the screen is enabled, otherwise false.
    12361231     */
     
    12821277     * @param string $type    Screen type. 'screen' or 'screen_save'. Default:
    12831278     *                        'screen'.
    1284      *
    12851279     * @return callable A callable function handle.
    12861280     */
     
    12881282        $callback = '';
    12891283
    1290         // Try the context-specific callback first
     1284        // Try the context-specific callback first.
    12911285        $method  = $context . '_' . $type;
    12921286        $rmethod = $this->class_reflection->getMethod( $method );
     
    13321326     * @param array $a First set of arguments.
    13331327     * @param array $b Second set of arguments.
    1334      *
    13351328     * @return array Parsed arguments.
    13361329     */
     
    13761369     *
    13771370     * @param string $key Property name.
    1378      *
    13791371     * @return mixed The value if found, otherwise null.
    13801372     */
     
    14011393     *
    14021394     * @param string $key Property name.
    1403      *
    14041395     * @return bool True if the value is set, otherwise false.
    14051396     */
     
    14251416     *
    14261417     * @param string $key Property name.
    1427      * @param mixed $value Property value.
     1418     * @param mixed  $value Property value.
    14281419     */
    14291420    public function __set( $key, $value ) {
     
    14501441                break;
    14511442
    1452             // Note: 'admin' becomes 'edit' to distinguish from Dashboard 'admin'
     1443            // Note: 'admin' becomes 'edit' to distinguish from Dashboard 'admin'.
    14531444            case 'admin_name' :
    14541445                $this->screens['edit']['name'] = $value;
     
    15271518    protected function parse_legacy_properties() {
    15281519
    1529         // Only run this one time
     1520        // Only run this one time.
    15301521        if ( ! empty( $this->legacy_properties_converted ) ) {
    15311522            return;
     
    15341525        $properties = $this->get_legacy_property_list();
    15351526
    1536         // By-reference variable for convenience
     1527        // By-reference variable for convenience.
    15371528        $lpc =& $this->legacy_properties_converted;
    15381529
    15391530        foreach ( $properties as $property ) {
    15401531
    1541             // No legacy config exists for this key
     1532            // No legacy config exists for this key.
    15421533            if ( ! isset( $this->{$property} ) ) {
    15431534                continue;
    15441535            }
    15451536
    1546             // Grab the value and record it as appropriate
     1537            // Grab the value and record it as appropriate.
    15471538            $value = $this->{$property};
    15481539
     
    15641555                    break;
    15651556
    1566                 // Note: 'admin' becomes 'edit' to distinguish from Dashboard 'admin'
     1557                // Note: 'admin' becomes 'edit' to distinguish from Dashboard 'admin'.
    15671558                case 'admin_name' :
    15681559                    $lpc['screens']['edit']['name'] = $value;
     
    16101601    protected function setup_legacy_properties() {
    16111602
    1612         // Only run this one time
     1603        // Only run this one time.
    16131604        if ( ! empty( $this->legacy_properties ) ) {
    16141605            return;
     
    16371628                    break;
    16381629
    1639                 // Note: 'admin' becomes 'edit' to distinguish from Dashboard 'admin'
     1630                // Note: 'admin' becomes 'edit' to distinguish from Dashboard 'admin'.
    16401631                case 'admin_name' :
    16411632                    $lp['admin_name'] = $params['screens']['edit']['name'];
     
    16631654
    16641655                default :
    1665                     // All other items get moved over
     1656                    // All other items get moved over.
    16661657                    $lp[ $property ] = $params[ $property ];
    16671658
    1668                     // Also reapply to the object, for backpat
     1659                    // Also reapply to the object, for backpat.
    16691660                    $this->{$property} = $params[ $property ];
    16701661
     
    16781669 * Register a new Group Extension.
    16791670 *
    1680  * @param string Name of the Extension class.
     1671 * @param string $group_extension_class Name of the Extension class.
    16811672 * @return false|null Returns false on failure, otherwise null.
    16821673 */
Note: See TracChangeset for help on using the changeset viewer.