MEMBERS HOOK API DOCUMENTATION


It is possible to integrate modules that don't have a direct interface
with the members module via a hook_members function.
This allows the module to present it's own custom fields to members module
for searching, sorting and listing of it's own types.

This is achieved by

- your hook_members returning a set of new fields to add, these fields are
  added to the pager table
  
- the members.module iterating over these new fields and creating a LEFT JOIN
  mechanism to join subsequent data to the user table, it is recommended
  that these LEFT JOIN tables are integer only columns for speed.
  The members.module assumed the name of these tables, your module should
  CREATE TEMPORARY TABLE, members.module will LEFT JOIN onto your table based
  on the 'uid' column

- all hook_members that 'return true' in their 'process' $op call will have their
  temporary left join table added to the query by the members.module, this is
  handy becuase you can null return if it turned out that it was not worth
  adding this table ($c was empty etc)

- the query is run as per usual and the rest of the table is displayed

function hook_members(...) -

  $op - operation string will be one of 'fields' or 'process'

  $op == 'fields'
     return an assoc. array of fields similar to drupal form API
	'title' Title of the field
	'type' One of 'bool', 'selection', 'textfield'
	'bool' = gives a "yes" or "any" select field
	'selection' = gives a single selection based on 'options'
	'textfield' = gives a textfield
	'searchable' return true or false if this field can be searchable
	'#autocomplete_path' = 

  $op == 'process'
     members.module requests this module prepare the temporary left join tables for processing
     $a = name of the temporary table it is expecting
     $b = the name of the field in the table it is expecting
     $c = the value for this field in the search fieldset (if any)
		 
- finally each field is themeable via a theme('$modulename'.'_field') call, where
  $modulename is the name of the module responsible for these fields
      
      

Example: buddylist integration




function membersbuddylist_members($op, $a='', $b='', $c='') {
  global $user;
    
  switch($op) {
    // return array of what fields we can define for members module
    case 'fields':
      // this module only has one field of use
      $fields['ismybuddy'] = array ('title'=> 'Is a buddy', 'type' => 'bool','searchable'=>true);
      return $fields;
    break;
    
    case 'process':
      // create a temporary table with our results of who is the current users buddy
      // members module will be expecting this table ($b) todo a LEFT JOIN on to gather more information
      if($a == 'ismybuddy' && $c == 'yes') {
        db_query("CREATE TEMPORARY TABLE {%s} (uid int, %s int, INDEX (uid))",$b,$a);
        db_query("INSERT INTO {%s} SELECT buddy,buddy FROM buddylist where uid=%d and received=1 ",$b,$user->uid);
        return true;
       }
       
    break;
  }
}

/**
 * hook_theme
 *
 * @param $user row from table join
 * @param field_id
 * @param $row_value value of the join in the current members row
 * @return string with better representation of the row
 */
function theme_membersbuddylist_field($user, $field_id, $row_value) {
  if($row_value->ismybuddy) {
    return "Yes";
  } else {
    return "No";
  }
}

