Changeset 10373 for trunk/src/bp-groups/bp-groups-admin.php

Timestamp:

11/22/2015 04:58:34 AM (9 years ago)

Author:

tw2113

Message:

More docs cleanup for BP-Groups component.

See #6401.

File:

• trunk/src/bp-groups/bp-groups-admin.php (modified) (58 diffs)

trunk/src/bp-groups/bp-groups-admin.php

@@ -18 +18 @@
 if ( !class_exists( 'WP_List_Table' ) ) require( ABSPATH . 'wp-admin/includes/class-wp-list-table.php' );
 
-// per_page screen option. Has to be hooked in extremely early.
+// The per_page screen option. Has to be hooked in extremely early.
 if ( is_admin() && ! empty( $_REQUEST['page'] ) && 'bp-groups' == $_REQUEST['page'] )
     add_filter( 'set-screen-option', 'bp_groups_admin_screen_options', 10, 3 );
@@ -29 +29 @@
 function bp_groups_add_admin_menu() {
 
-    // Add our screen
+    // Add our screen.
     $hook = add_menu_page(
         _x( 'Groups', 'Admin Groups page title', 'buddypress' ),
@@ -53 +53 @@
  *
  * @param array $custom_menus Array of BP top-level menu items.
- *
  * @return array Menu item array, with Groups added.
  */
@@ -76 +75 @@
     global $bp_groups_list_table;
 
-    // Build redirection URL
+    // Build redirection URL.
     $redirect_to = remove_query_arg( array( 'action', 'action2', 'gid', 'deleted', 'error', 'updated', 'success_new', 'error_new', 'success_modified', 'error_modified' ), $_SERVER['REQUEST_URI'] );
 
-    // Decide whether to load the dev version of the CSS and JavaScript
+    // Decide whether to load the dev version of the CSS and JavaScript.
     $min = defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ? '' : 'min.';
 
@@ -93 +92 @@
     do_action( 'bp_groups_admin_load', $doaction );
 
-    // Edit screen
+    // Edit screen.
     if ( 'do_delete' == $doaction && ! empty( $_GET['gid'] ) ) {
 
@@ -112 +111 @@
 
     } elseif ( 'edit' == $doaction && ! empty( $_GET['gid'] ) ) {
-        // columns screen option
+        // Columns screen option.
         add_screen_option( 'layout_columns', array( 'default' => 2, 'max' => 2, ) );
 
@@ -123 +122 @@
         ) );
 
-        // Help panel - sidebar links
+        // Help panel - sidebar links.
         get_current_screen()->set_help_sidebar(
             '<p><strong>' . __( 'For more information:', 'buddypress' ) . '</strong></p>' .
@@ -142 +141 @@
         do_action( 'bp_groups_admin_meta_boxes' );
 
-        // Enqueue JavaScript files
+        // Enqueue JavaScript files.
         wp_enqueue_script( 'postbox' );
         wp_enqueue_script( 'dashboard' );
 
-    // Index screen
+    // Index screen.
     } else {
-        // Create the Groups screen list table
+        // Create the Groups screen list table.
         $bp_groups_list_table = new BP_Groups_List_Table();
 
-        // per_page screen option
+        // The per_page screen option.
         add_screen_option( 'per_page', array( 'label' => _x( 'Groups', 'Groups per page (screen options)', 'buddypress' )) );
 
-        // Help panel - overview text
+        // Help panel - overview text.
         get_current_screen()->add_help_tab( array(
             'id'      => 'bp-groups-overview',
@@ -171 +170 @@
         ) );
 
-        // Help panel - sidebar links
+        // Help panel - sidebar links.
         get_current_screen()->set_help_sidebar(
             '<p><strong>' . __( 'For more information:', 'buddypress' ) . '</strong></p>' .
@@ -180 +179 @@
     $bp = buddypress();
 
-    // Enqueue CSS and JavaScript
+    // Enqueue CSS and JavaScript.
     wp_enqueue_script( 'bp_groups_admin_js', $bp->plugin_url . "bp-groups/admin/js/admin.{$min}js", array( 'jquery', 'wp-ajax-response', 'jquery-ui-autocomplete' ), bp_get_version(), true );
     wp_localize_script( 'bp_groups_admin_js', 'BP_Group_Admin', array(
@@ -195 +194 @@
 
     if ( $doaction && 'save' == $doaction ) {
-        // Get group ID
+        // Get group ID.
         $group_id = isset( $_REQUEST['gid'] ) ? (int) $_REQUEST['gid'] : '';
 
@@ -203 +202 @@
         ), $redirect_to );
 
-        // Check this is a valid form submission
+        // Check this is a valid form submission.
         check_admin_referer( 'edit-group_' . $group_id );
 
-        // Get the group from the database
+        // Get the group from the database.
         $group = groups_get_group( 'group_id=' . $group_id );
 
-        // If the group doesn't exist, just redirect back to the index
+        // If the group doesn't exist, just redirect back to the index.
         if ( empty( $group->slug ) ) {
             wp_redirect( $redirect_to );
@@ -215 +214 @@
         }
 
-        // Check the form for the updated properties
-
-        // Store errors
+        // Check the form for the updated properties.
+        // Store errors.
         $error = 0;
         $success_new = $error_new = $success_modified = $error_modified = array();
 
         // Group name and description are handled with
-        // groups_edit_base_group_details()
+        // groups_edit_base_group_details().
         if ( !groups_edit_base_group_details( $group_id, $_POST['bp-groups-name'], $_POST['bp-groups-description'], 0 ) ) {
             $error = $group_id;
 
-            // using negative integers for different error messages... eek!
+            // Using negative integers for different error messages... eek!
             if ( empty( $_POST['bp-groups-name'] ) && empty( $_POST['bp-groups-description'] ) ) {
                 $error = -3;
@@ -236 +234 @@
         }
 
-        // Enable discussion forum
+        // Enable discussion forum.
         $enable_forum   = ( isset( $_POST['group-show-forum'] ) ) ? 1 : 0;
 
@@ -263 +261 @@
         }
 
-        // Process new members
+        // Process new members.
         $user_names = array();
 
@@ -276 +274 @@
 
                 // Make sure the user exists before attempting
-                // to add to the group
+                // to add to the group.
                 $user = get_user_by( 'slug', $un );
 
@@ -291 +289 @@
         }
 
-        // Process member role changes
+        // Process member role changes.
         if ( ! empty( $_POST['bp-groups-role'] ) && ! empty( $_POST['bp-groups-existing-role'] ) ) {
 
             // Before processing anything, make sure you're not
-            // attempting to remove the all user admins
+            // attempting to remove the all user admins.
             $admin_count = 0;
             foreach ( (array) $_POST['bp-groups-role'] as $new_role ) {
@@ -311 +309 @@
             } else {
 
-                // Process only those users who have had their roles changed
+                // Process only those users who have had their roles changed.
                 foreach ( (array) $_POST['bp-groups-role'] as $user_id => $new_role ) {
 
@@ -321 +319 @@
                             case 'mod' :
                                 // Admin to mod is a demotion. Demote to
-                                // member, then fall through
+                                // member, then fall through.
                                 if ( 'admin' == $existing_role ) {
                                     groups_demote_member( $user_id, $group_id );
@@ -328 +326 @@
                             case 'admin' :
                                 // If the user was banned, we must
-                                // unban first
+                                // unban first.
                                 if ( 'banned' == $existing_role ) {
                                     groups_unban_member( $user_id, $group_id );
@@ -334 +332 @@
 
                                 // At this point, each existing_role
-                                // is a member, so promote
+                                // is a member, so promote.
                                 $result = groups_promote_member( $user_id, $group_id, $new_role );
 
@@ -362 +360 @@
                         }
 
-                        // Store the success or failure
+                        // Store the success or failure.
                         if ( $result ) {
                             $success_modified[] = $user_id;
@@ -382 +380 @@
         do_action( 'bp_group_admin_edit_after', $group_id );
 
-        // Create the redirect URL
-
+        // Create the redirect URL.
         if ( $error ) {
-            // This means there was an error updating group details
+            // This means there was an error updating group details.
             $redirect_to = add_query_arg( 'error', (int) $error, $redirect_to );
         } else {
-            // Group details were update successfully
+            // Group details were update successfully.
             $redirect_to = add_query_arg( 'updated', 1, $redirect_to );
         }
@@ -438 +435 @@
  * @param string $option    Screen option name.
  * @param string $new_value Screen option form value.
- *
  * @return string Option value. False to abandon update.
  */
@@ -445 +441 @@
         return $value;
 
-    // Per page
+    // Per page.
     $new_value = (int) $new_value;
     if ( $new_value < 1 || $new_value > 999 )
@@ -459 +455 @@
  */
 function bp_groups_admin() {
-    // Decide whether to load the index or edit screen
+    // Decide whether to load the index or edit screen.
     $doaction = bp_admin_list_table_current_bulk_action();
 
-    // Display the single group edit screen
+    // Display the single group edit screen.
     if ( 'edit' == $doaction && ! empty( $_GET['gid'] ) ) {
         bp_groups_admin_edit();
 
-    // Display the group deletion confirmation screen
+    // Display the group deletion confirmation screen.
     } elseif ( 'delete' == $doaction && ! empty( $_GET['gid'] ) ) {
         bp_groups_admin_delete();
 
-    // Otherwise, display the groups index screen
+    // Otherwise, display the groups index screen.
     } else {
         bp_groups_admin_index();
@@ -488 +484 @@
     $messages = array();
 
-    // If the user has just made a change to a group, build status messages
+    // If the user has just made a change to a group, build status messages.
     if ( !empty( $_REQUEST['no_admins'] ) || ! empty( $_REQUEST['error'] ) || ! empty( $_REQUEST['updated'] ) || ! empty( $_REQUEST['error_new'] ) || ! empty( $_REQUEST['success_new'] ) || ! empty( $_REQUEST['error_modified'] ) || ! empty( $_REQUEST['success_modified'] ) ) {
         $no_admins        = ! empty( $_REQUEST['no_admins']        ) ? 1                                             : 0;
@@ -546 +542 @@
     $is_error = ! empty( $no_admins ) || ! empty( $errors ) || ! empty( $error_new ) || ! empty( $error_modified );
 
-    // Get the group from the database
+    // Get the group from the database.
     $group      = groups_get_group( 'group_id=' . $_GET['gid'] );
 
@@ -552 +548 @@
     $group_name = isset( $group->name ) ? apply_filters( 'bp_get_group_name', $group->name ) : '';
 
-    // Construct URL for form
+    // Construct URL for form.
     $form_url = remove_query_arg( array( 'action', 'deleted', 'no_admins', 'error', 'error_new', 'success_new', 'error_modified', 'success_modified' ), $_SERVER['REQUEST_URI'] );
     $form_url = add_query_arg( 'action', 'save', $form_url );
@@ -576 +572 @@
         </h1>
 
-        <?php // If the user has just made a change to an group, display the status messages ?>
+        <?php // If the user has just made a change to an group, display the status messages. ?>
         <?php if ( !empty( $messages ) ) : ?>
             <div id="moderated" class="<?php echo ( $is_error ) ? 'error' : 'updated'; ?>"><p><?php echo implode( "</p><p>", $messages ); ?></p></div>
@@ -652 +648 @@
         'include'     => $group_ids,
         'show_hidden' => true,
-        'per_page'    => null, // Return all results
+        'per_page'    => null, // Return all results.
     ) );
 
-    // Create a new list of group ids, based on those that actually exist
+    // Create a new list of group ids, based on those that actually exist.
     $gids = array();
     foreach ( $groups['groups'] as $group ) {
@@ -697 +693 @@
     $messages = array();
 
-    // If the user has just made a change to a group, build status messages
+    // If the user has just made a change to a group, build status messages.
     if ( ! empty( $_REQUEST['deleted'] ) ) {
         $deleted  = ! empty( $_REQUEST['deleted'] ) ? (int) $_REQUEST['deleted'] : 0;
@@ -706 +702 @@
     }
 
-    // Prepare the group items for display
+    // Prepare the group items for display.
     $bp_groups_list_table->prepare_items();
 
@@ -733 +729 @@
         </h1>
 
-        <?php // If the user has just made a change to an group, display the status messages ?>
+        <?php // If the user has just made a change to an group, display the status messages. ?>
         <?php if ( !empty( $messages ) ) : ?>
             <div id="moderated" class="<?php echo ( ! empty( $_REQUEST['error'] ) ) ? 'error' : 'updated'; ?>"><p><?php echo implode( "<br/>\n", $messages ); ?></p></div>
         <?php endif; ?>
 
-        <?php // Display each group on its own row ?>
+        <?php // Display each group on its own row. ?>
         <?php $bp_groups_list_table->views(); ?>
 
@@ -800 +796 @@
  *
  * @since 1.7.0
+ *
+ * @param BP_Groups_Group $item The BP_Groups_Group object for the current group.
  */
 function bp_groups_admin_edit_metabox_add_new_members( $item ) {
@@ -821 +819 @@
     // Pull up a list of group members, so we can separate out the types
     // We'll also keep track of group members here to place them into a
-    // JavaScript variable, which will help with group member autocomplete
+    // JavaScript variable, which will help with group member autocomplete.
     $members = array(
         'admin'  => array(),
@@ -851 +849 @@
     }
 
-    // Echo out the JavaScript variable
+    // Echo out the JavaScript variable.
     echo '<script type="text/javascript">var group_id = "' . esc_js( $item->id ) . '";</script>';
 
-    // Loop through each member type
+    // Loop through each member type.
     foreach ( $members as $member_type => $type_users ) : ?>
 
@@ -1008 +1006 @@
  * @param BP_Group_Member_Query $query       A BP_Group_Member_Query object.
  * @param string                $member_type member|mod|admin|banned.
- *
  * @return string Pagination links HTML.
  */
@@ -1018 +1015 @@
     }
 
-    // The key used to paginate this member type in the $_GET global
+    // The key used to paginate this member type in the $_GET global.
     $qs_key = $member_type . '_page';
     $url_base = remove_query_arg( array( $qs_key, 'updated', 'success_modified' ), $_SERVER['REQUEST_URI'] );
@@ -1025 +1022 @@
     $per_page = 10; // @todo Make this customizable?
 
-    // Don't show anything if there's no pagination
+    // Don't show anything if there's no pagination.
     if ( 1 === $page && $query->total_users <= $per_page ) {
         return $pagination;
@@ -1065 +1062 @@
  *
  * @param array $user_ids Array of user IDs.
- *
  * @return array Array of user_logins corresponding to $user_ids.
  */
@@ -1087 +1083 @@
 function bp_groups_admin_autocomplete_handler() {
 
-    // Bail if user user shouldn't be here, or is a large network
+    // Bail if user user shouldn't be here, or is a large network.
     if ( ! current_user_can( 'bp_moderate' ) || ( is_multisite() && wp_is_large_network( 'users' ) ) ) {
         wp_die( -1 );
@@ -1112 +1108 @@
 
             $matches[] = array(
-                // translators: 1: user_login, 2: user_email
+                // Translators: 1: user_login, 2: user_email.
                 'label' => sprintf( __( '%1$s (%2$s)', 'buddypress' ), $user->name, $user->ID ),
                 'value' => $user->ID,
@@ -1133 +1129 @@
      * The type of view currently being displayed.
      *
-     * e.g. "All", "Pending", "Approved", "Spam"...
+     * E.g. "All", "Pending", "Approved", "Spam"...
      *
      * @since 1.7.0
@@ -1186 +1182 @@
         $screen = get_current_screen();
 
-        // Option defaults
+        // Option defaults.
         $include_id   = false;
         $search_terms = false;
 
-        // Set current page
+        // Set current page.
         $page = $this->get_pagenum();
 
-        // Set per page from the screen options
+        // Set per page from the screen options.
         $per_page = $this->get_items_per_page( str_replace( '-', '_', "{$screen->id}_per_page" ) );
 
@@ -1202 +1198 @@
         }
 
-        // Order by - default to newest
+        // Order by - default to newest.
         $orderby = 'last_activity';
         if ( ! empty( $_REQUEST['orderby'] ) ) {
@@ -1229 +1225 @@
             $include_id = (int) $_REQUEST['gid'];
 
-        // Set the current view
+        // Set the current view.
         if ( isset( $_GET['group_status'] ) && in_array( $_GET['group_status'], array( 'public', 'private', 'hidden' ) ) ) {
             $this->view = $_GET['group_status'];
         }
 
-        // We'll use the ids of group types for the 'include' param
+        // We'll use the ids of group types for the 'include' param.
         $this->group_type_ids = BP_Groups_Group::get_group_type_ids();
 
-        // Pass a dummy array if there are no groups of this type
+        // Pass a dummy array if there are no groups of this type.
         $include = false;
         if ( 'all' != $this->view && isset( $this->group_type_ids[ $this->view ] ) ) {
@@ -1243 +1239 @@
         }
 
-        // Get group type counts for display in the filter tabs
+        // Get group type counts for display in the filter tabs.
         $this->group_counts = array();
         foreach ( $this->group_type_ids as $group_type => $group_ids ) {
@@ -1270 +1266 @@
         }
 
-        // Set raw data to display
+        // Set raw data to display.
         $this->items = $groups;
 
-        // Store information needed for handling table pagination
+        // Store information needed for handling table pagination.
         $this->set_pagination_args( array(
             'per_page'    => $per_page,
@@ -1307 +1303 @@
      */
     protected function get_default_primary_column_name() {
-        // comment column is mapped to Group's name
+        // Comment column is mapped to Group's name.
         return 'comment';
     }
@@ -1324 +1320 @@
      *
      * @since 1.7.0
-    */
+     */
     public function display() {
         $this->display_tablenav( 'top' ); ?>
@@ -1498 +1494 @@
      * @since 2.3.4 Visibility set to public for compatibility with WP < 4.0.0.
      *
-     * @param array $actions The list of actions
-     * @param bool $always_visible Whether the actions should be always visible
+     * @param array $actions        The list of actions.
+     * @param bool  $always_visible Whether the actions should be always visible.
      * @return string
      */
@@ -1559 +1555 @@
     public function column_comment( $item = array() ) {
 
-        // Preorder items: Edit | Delete | View
+        // Preorder items: Edit | Delete | View.
         $actions = array(
             'edit'   => '',
@@ -1566 +1562 @@
         );
 
-        // We need the group object for some BP functions
+        // We need the group object for some BP functions.
         $item_obj = (object) $item;
 
-        // Build actions URLs
+        // Build actions URLs.
         $base_url   = bp_get_admin_url( 'admin.php?page=bp-groups&amp;gid=' . $item['id'] );
         $delete_url = wp_nonce_url( $base_url . "&amp;action=delete", 'bp-groups-delete' );
@@ -1585 +1581 @@
         $group_name = apply_filters_ref_array( 'bp_get_group_name', array( $item['name'] ), $item );
 
-        // Rollover actions
-
-        // Edit
+        // Rollover actions.
+        // Edit.
         $actions['edit']   = sprintf( '<a href="%s">%s</a>', esc_url( $edit_url   ), __( 'Edit',   'buddypress' ) );
 
-        // Delete
+        // Delete.
         $actions['delete'] = sprintf( '<a href="%s">%s</a>', esc_url( $delete_url ), __( 'Delete', 'buddypress' ) );
 
-        // Visit
+        // Visit.
         $actions['view']   = sprintf( '<a href="%s">%s</a>', esc_url( $view_url   ), __( 'View',   'buddypress' ) );
 
@@ -1606 +1601 @@
         $actions = apply_filters( 'bp_groups_admin_comment_row_actions', array_filter( $actions ), $item );
 
-        // Get group name and avatar
+        // Get group name and avatar.
         $avatar = '';
 
@@ -1659 +1654 @@
 
         // @todo This should be abstracted out somewhere for the whole
-        // Groups component
+        // Groups component.
         switch ( $status ) {
             case 'public' :
@@ -1732 +1727 @@
      * @param array  $item        Information about the current row.
      * @param string $column_name The column name.
-     *
      * @return string
      */