DEVELOPER.txt

   1  /\  __|_.  ._|_
   2 /~~\(_ | |\/| |\/
   3                /
   4 Development specifications and integration
   5 ==========================================
   6  *for more details please see the handbook at http://drupal.org/node/328429
   7
   8 _Hooks:
   9 ------------------------------------------
  10 hook_activity_info()
  11   Register a module to work with Activity's hook_action_info() implementation. All properties
  12   marked with * are required
  13
  14   Properties:
  15     api*         - specifies the version of Activity you are registering with
  16     name*        - the name of the module
  17     object_type  - the object type that is used in token replacement.
  18                    @see activity_record(). This is needed because the $object
  19                    parameter is not available, so we need a key name in order to
  20                    reference the object from within the $context parameter.
  21     eid_field    - the field of the object_type that identifies this activity.
  22                    For instance, comment module uses this as 'cid' so that all
  23                    activities dealing with that comment can be retrieved or deleted.
  24     objects      - corresponds to the objects that are passed as properties of
  25                    the $context array within a module's hook_trigger_name(). @see
  26                    the example in flag_friend.module - compare it's
  27                    hook_trigger_name() and hook_activity_info(). The key/s to
  28                    this array are used as the labels fo rthe form elements.
  29     hooks        - a list of available hook that this action should operate upon.
  30                    @see activity_action_info(). This allows other modules to
  31                    extend the scope of what can be recorded by the activity
  32                    action.
  33     type_options - an array keyed (value => english name) for types. For instance,
  34                    node_activity_info() returns something like
  35                    array('page' => 'Page'). These types are to be used in conjuction
  36                    with hook_activity_type_check().
  37     realms       - a structured array, keyed by realm_id that points to a human
  38                    readable name (note don't use t())
  39                    ex: realm_id => 'My Human Readable name'
  40
  41   Return value:
  42     An object with the above properties.
  43
  44   Example:
  45     /**
  46      * Implementation of hook_activity_info().
  47      */
  48     function flag_friend_activity_info() {
  49       $info = new stdClass();
  50       $info->api = 2;
  51       $info->name = 'flag_friend';
  52       $info->object_type = 'flag_friend';
  53       $info->objects = array('requestor' => 'user', 'requestee' => 'flag_friend'); // array keys are the labels
  54       $info->hooks = array('flag_friend' => array('approve', 'request', 'deny', 'remove'));
  55       $info->realms = array('flag_friend' => 'Flag Friend');
  56       $info->type_options = array();
  57       return $info;
  58     }
  59 ------------------------------------------
  60 hook_activity_grants($activity)
  61   Provides a means to record what should have access to any particular message.
  62
  63   Parameters:
  64     $activity - an object that holds a full activity record from the database.
  65
  66   Return value:
  67     A list of keyed by reaml of ids to be stored into the access_table with the above properties.
  68
  69   Example:
  70     For instance, flag_friend returns a one element array of the creator of the
  71     activity. For OG, it would return all the groups that the node belongs in
  72     for instance.
  73
  74     /**
  75      * Implementation of hook_activity_grants().
  76      */
  77     function flag_friend_activity_grants($activity) {
  78       return array(
  79         'flag_friend' => array($activity->uid), // the module_id that will be used
  80       );
  81     }
  82 ------------------------------------------
  83 hook_activity_access_grants($account)
  84   Provide a means for other modules to determine who can have access to any
  85   given activity message.
  86
  87   Parameters:
  88     $account - the account of the message that we're determining access for.
  89
  90   Return value:
  91     The an array keyed by realm of Ids for the module that the user will have access too.
  92
  93   Example:
  94     /**
  95      * Implementation of hook_activity_access_grants().
  96      */
  97     function flag_friend_activity_access_grants($acccount) {
  98       $friends = flag_friend_get_friends($account->uid);
  99       $realm_ids = array();
 100       if (!empty($friends)) {
 101         foreach ($friends as $friend) {
 102           $realm_ids['flag_friend'][] = $friend;
 103         }
 104       }
 105       return $realm_ids;
 106     }
 107 ------------------------------------------
 108 hook_activity_record_alter(&$record, $context)
 109   Provide a means to alter an activity record before it is inserted into the db.
 110
 111   Parameters:
 112     $record  - the record for insertion, containing uid, op, type,
 113                author_message, everyone_message, nid, and created.
 114     $context - the context from the trigger, containing hook, op, object,
 115                author-pattern, and everyone-pattern.
 116
 117   Return value:
 118     $record is passed by reference in order to make changes to it before insert
 119
 120   Example:
 121     /**
 122      * Implementation of hook_activity_records_alter().
 123      */
 124     function example_activity_records_alter(&$record, $context) {
 125       // If we have a story node rather than another type, we can change the
 126       // token pattern.
 127       if ($object->type == 'story') {
 128         $author_pattern = $context['author-pattern'] .' - [node-type]';
 129         $record->author_message = token_replace($author_pattern, $record->type, $context[$record->type]);
 130       }
 131     }
 132 ------------------------------------------
 133 hook_activity_messages_alter(&$messages, $type)
 134   Provides a means to alter the activity messages before they are inserted.
 135
 136   Parameters:
 137     $messages - the translated messages keyed by uid which have already had
 138                 their tokens replaced.
 139     $type     - the type of activity message as defined by the implementing
 140                 module.
 141
 142   Example:
 143     /**
 144      * Implementation of hook_activity_messages_alter().
 145      */
 146     function example_activity_messages_alter(&$messages, $type) {
 147       if ($type == 'nodeapi') {
 148         // You should probably never do this, but it illustrates the $message
 149         // structure. Do no record Anonymous messages.
 150         unset($messages[0]);
 151         // Most use cases will actually be string replacement methods on the
 152         // $messages[$uid] so that you can target a specific message that will
 153         // show up for a particular user.
 154       }
 155     }
 156 ------------------------------------------
 157 hook_activity_message_recorded($record, $context)
 158   Provides a means to do something with a record after it has been saved.
 159
 160   Parameters:
 161     These are the same as hook_activity_record_alter() except that since the
 162     $record has been saved, it now has a $record->amid.
 163
 164   Example:
 165     /**
 166      * Implementation of hook_activity_message_recorded().
 167      */
 168     function activity_user_status_activity_message_recorded($record) {
 169       // After a message has been recorded with activity, we then save it's id so
 170       // that we can reference it as a foreign key.
 171       if ($record->type == 'activity_user_status') {
 172         db_query("UPDATE {activity_user_status} SET amid = %d WHERE uid = %d", $record->amid, $record->uid);
 173       }
 174     }
 175 ------------------------------------------
 176 hook_activity_access_records_alter(&$grants)
 177   Provides a mean to alter the grants that are recorded to the activity_access
 178   table.
 179
 180   Parameters:
 181     $grants  - these are the grants that come back from other modules whom have
 182                implemented hook_activity_grants().
 183     $record  - This is the activity record in the database
 184
 185   Example:
 186     /**
 187      * Implementation of hook_activity_access_records_alter().
 188      * This example removes any access records except og. Prevents friend
 189      * modules from providing access.
 190      */
 191     function example_activity_access_records_alter(&$grants, $record) {
 192       foreach ($grants as $realm => $value) {
 193          if ($realm != 'og') {
 194              unset($grants[$module]);
 195          }
 196       }
 197     }
 198 -------------------------------------------
 199 hook_activity_type_check($token_objects, $types)
 200   This hook is called when a module implements hook_activity_info() and provides configurable
 201   types. These types need to be checked against the objects loaded up for this activity.
 202
 203   Parameters
 204     $token_objects  - This array of objects are objects that will be used during token_replace.
 205                       These objects generally match those defined in $info->objects
 206
 207     $types          - These are the types selected from the options provided in $info->types.
 208                       For instance, when the activity template is created, the users chooses
 209                       for node insert activity, type of page and story. Then the $types array
 210                       will contain two elements, array('page', 'story').
 211
 212 Example:
 213 /**
 214  * Implementation of hook_activity_type_check().
 215  */
 216 function node_activity_type_check($token_objects, $types) {
 217   return (in_array($token_objects['node']->type, $types));
 218 }
 219 ---------------------------------------------
 220 hook_activity_objects_alter(&token_$objects, $activity_type)
 221   This hook is called for each activity record. It gives modules the
 222         oppurtunity to change the objects based on activity_type which
 223         corresponds to the type column in the activity table.
 224
 225   Parameters
 226     $token_objects - This arrya of objects will be used during
 227     token_replace.
 228
 229    $activity_type  - The type of activity being recorded. i.e. 'node',
 230    'comment', 'user'
 231
 232 Example:
 233 /**
 234  * Implementation of hook_activity_objects_alter().
 235  */
 236 function comment_activity_objects_alter(&$token_objects, $activity_type) {
 237   if ($type == 'comment') {
 238     $objects['node'] = node_load($objects['comment']->nid);
 239     $objects['user'] = $GLOBALS['user'];
 240
 241     // If the comment and the node are the same, provide an object for it.
 242     if (isset($objects['comment']) && $objects['node']->uid == $objects['comment']->uid) {
 243       $objects['node_comment_author'] = $objects['comment'];
 244     }
 245   }
 246 }