Changeset 8125 for trunk/bp-activity/bp-activity-functions.php

Timestamp:

03/13/2014 06:34:06 PM (11 years ago)

Author:

boonebgorges

Message:

Generate activity actions dynamically, instead of using static values stored in the database

Activity actions - like 'Joe became a registered member' - have always been
stored as static strings in the activity table. This has been a perennial thorn
in the side of BP site administrators. For one thing, static strings cannot be
translated for multilingual audiences (without unreasonable workarounds).
For another, information in these static strings becomes out of date as users
change their display names, groups change their names, and so on.

This changeset makes it possible for activity types to be registered with a
new $format_callback function, passed to bp_activity_set_action(), which BP
will use to generate the action dynamically when building the activity loop.
This makes the activity stream fully localizable, continually up-to-date, and
generally the bomb dot com.

Existing plugins that do not register format_callback functions will continue
to have their actions pulled directly from the database. Likewise, since a copy
of the static string is saved in the activity table, static strings can be
served if the given component is disabled at any point (and thus the callback
is no longer available).

The original argument for caching the action strings was that generating them
inline was too resource intensive; it often requires pulling up display names,
user permalinks, group links, blog post names, and so forth. To address this
problem, each component can now prefetch required data at the beginning of an
activity loop by hooking to bp_activity_prefetch_object_data, and loading any
relevant data into the cache. The Activity, Friends, Groups, and Blogs
component now do this natively. It's likely that this prefetching will have
other performance benefits, as plugin authors will now be able to access user
data etc inline without performance penalties.

The case of the Blogs component is a special one; it's not practical to
prefetch data from multiple blogs at the beginning of a loop, due to the
resources required by switch_to_blog(). For this reason, the format_callback
functions in the blog component cache some relevant data (like the post name)
in blogmeta, where it's readily accessible within the loop.

Fixes #3856

File:

• trunk/bp-activity/bp-activity-functions.php (modified) (9 diffs)

trunk/bp-activity/bp-activity-functions.php

@@ -257 +257 @@
 
 /**
- * Set the current action for a given activity stream location.
- *
- * @since BuddyPress (1.1)
- *
- * @global object $bp BuddyPress global settings
- * @uses apply_filters() To call the 'bp_activity_set_action' hook
+ * Register an activity 'type' and its action description/callback.
+ *
+ * Activity actions are strings used to describe items in the activity stream,
+ * such as 'Joe became a registered member' or 'Bill and Susie are now
+ * friends'. Each activity type (such as 'new_member' or 'friendship_created')
+ * used by a component should be registered using this function.
+ *
+ * While it's possible to post items to the activity stream whose types are
+ * not registered using bp_activity_set_action(), it is not recommended;
+ * unregistered types will not be displayed properly in the activity admin
+ * panel, and dynamic action generation (which is essential for multilingual
+ * sites, etc) will not work.
+ *
+ * @since BuddyPress (1.1.0)
  *
  * @param string $component_id The unique string ID of the component.
- * @param string $key The action key.
- * @param string $value The action value.
+ * @param string $type The action type.
+ * @param string $description The action description.
+ * @param callable $format_callback Callback for formatting the action string.
  * @return bool False if any param is empty, otherwise true.
  */
-function bp_activity_set_action( $component_id, $key, $value ) {
-    global $bp;
+function bp_activity_set_action( $component_id, $type, $description, $format_callback = false ) {
+    $bp = buddypress();
 
     // Return false if any of the above values are not set
-    if ( empty( $component_id ) || empty( $key ) || empty( $value ) )
-        return false;
+    if ( empty( $component_id ) || empty( $type ) || empty( $description ) ) {
+        return false;
+    }
 
     // Set activity action
-    if ( !isset( $bp->activity->actions ) || !is_object( $bp->activity->actions ) ) {
+    if ( ! isset( $bp->activity->actions ) || ! is_object( $bp->activity->actions ) ) {
         $bp->activity->actions = new stdClass;
     }
 
-    if ( !isset( $bp->activity->actions->{$component_id} ) || !is_object( $bp->activity->actions->{$component_id} ) ) {
+    // Verify callback
+    if ( ! is_callable( $format_callback ) ) {
+        $format_callback = '';
+    }
+
+    if ( ! isset( $bp->activity->actions->{$component_id} ) || ! is_object( $bp->activity->actions->{$component_id} ) ) {
         $bp->activity->actions->{$component_id} = new stdClass;
     }
 
-    $bp->activity->actions->{$component_id}->{$key} = apply_filters( 'bp_activity_set_action', array(
-        'key'   => $key,
-        'value' => $value
-    ), $component_id, $key, $value );
+    $bp->activity->actions->{$component_id}->{$type} = apply_filters( 'bp_activity_set_action', array(
+        'key'             => $type,
+        'value'           => $description,
+        'format_callback' => $format_callback,
+    ), $component_id, $type, $description, $format_callback );
 
     return true;
@@ -858 +874 @@
     global $bp;
 
-    bp_activity_set_action( $bp->activity->id, 'activity_update', __( 'Posted a status update', 'buddypress' ) );
-    bp_activity_set_action( $bp->activity->id, 'activity_comment', __( 'Replied to a status update', 'buddypress' ) );
+    bp_activity_set_action(
+        $bp->activity->id,
+        'activity_update',
+        __( 'Posted a status update', 'buddypress' ),
+        'bp_activity_format_activity_action_activity_update'
+    );
+
+    bp_activity_set_action(
+        $bp->activity->id,
+        'activity_comment',
+        __( 'Replied to a status update', 'buddypress' ),
+        'bp_activity_format_activity_action_activity_comment'
+    );
 
     do_action( 'bp_activity_register_activity_actions' );
@@ -867 +894 @@
 }
 add_action( 'bp_register_activity_actions', 'bp_activity_register_activity_actions' );
+
+/**
+ * Generate an activity action string for an activity item.
+ *
+ * @param object $activity Activity data object.
+ * @return string|bool Returns false if no callback is found, otherwise returns
+ *         the formatted action string.
+ */
+function bp_activity_generate_action_string( $activity ) {
+    // Check for valid input
+    if ( empty( $activity->component ) || empty( $activity->type ) ) {
+        return false;
+    }
+
+    // Check for registered format callback
+    if ( empty( buddypress()->activity->actions->{$activity->component}->{$activity->type}['format_callback'] ) ) {
+        return false;
+    }
+
+    return call_user_func( buddypress()->activity->actions->{$activity->component}->{$activity->type}['format_callback'], $activity );
+}
+
+/**
+ * Format 'activity_update' activity actions.
+ *
+ * @since BuddyPress (2.0.0)
+ *
+ * @param object $activity Activity data object.
+ * @return string
+ */
+function bp_activity_format_activity_action_activity_update( $activity ) {
+    $action = sprintf( __( '%s posted an update', 'buddypress' ), bp_core_get_userlink( $activity->user_id ) );
+    return apply_filters( 'bp_activity_new_update_action', $action, $activity );
+}
+
+/**
+ * Format 'activity_comment' activity actions.
+ *
+ * @since BuddyPress (2.0.0)
+ *
+ * @param object $activity Activity data object.
+ * @return string
+ */
+function bp_activity_format_activity_action_activity_comment( $activity ) {
+    $action = sprintf( __( '%s posted a new activity comment', 'buddypress' ), bp_core_get_userlink( $activity->user_id ) );
+    return apply_filters( 'bp_activity_comment_action', $action, $activity );
+}
 
 /******************************************************************************
@@ -1032 +1106 @@
  *           false to create a new item. Default: false.
  *     @type string $action Optional. The activity action/description, typically
- *           something like "Joe posted an update".
+ *           something like "Joe posted an update". Values passed to this param
+ *           will be stored in the database and used as a fallback for when the
+ *           activity item's format_callback cannot be found (eg, when the
+ *           component is disabled). As long as you have registered a
+ *           format_callback for your $type, it is unnecessary to include this
+ *           argument - BP will generate it automatically.
+ *           See {@link bp_activity_set_action()}.
  *     @type string $content Optional. The content of the activity item.
  *     @type string $component The unique name of the component associated with
@@ -1088 +1168 @@
     $activity->component         = $component;
     $activity->type              = $type;
-    $activity->action            = $action;
     $activity->content           = $content;
     $activity->primary_link      = $primary_link;
@@ -1096 +1175 @@
     $activity->hide_sitewide     = $hide_sitewide;
     $activity->is_spam           = $is_spam;
+    $activity->action            = ! empty( $action ) ? $action : bp_activity_generate_action_string( $activity );
 
     if ( !$activity->save() )
@@ -1151 +1231 @@
     // Record this on the user's profile
     $from_user_link   = bp_core_get_userlink( $user_id );
-    $activity_action  = sprintf( __( '%s posted an update', 'buddypress' ), $from_user_link );
     $activity_content = $content;
     $primary_link     = bp_core_get_userlink( $user_id, false, true );
@@ -1158 +1237 @@
     $activity_id = bp_activity_add( array(
         'user_id'      => $user_id,
-        'action'       => apply_filters( 'bp_activity_new_update_action', $activity_action ),
         'content'      => apply_filters( 'bp_activity_new_update_content', $activity_content ),
         'primary_link' => apply_filters( 'bp_activity_new_update_primary_link', $primary_link ),
         'component'    => $bp->activity->id,
-        'type'         => 'activity_update'
+        'type'         => 'activity_update',
     ) );
 
@@ -1231 +1309 @@
     $comment_id = bp_activity_add( array(
         'id'                => $id,
-        'action'            => apply_filters( 'bp_activity_comment_action', sprintf( __( '%s posted a new activity comment', 'buddypress' ), bp_core_get_userlink( $user_id ) ) ),
         'content'           => apply_filters( 'bp_activity_comment_content', $content ),
         'component'         => buddypress()->activity->id,