// $Id: API.txt,v 1.1.2.1 2008-04-13 10:33:04 jareyero Exp $

Developer doocumentation for subscriptions framework.

[TO DO]

The notifications hook
----------------------
This hook must be implemented by modules defining event and subscription types

  function hook_notifications($op, &$arg0 = NULL, $arg1 = NULL, $arg2 = NULL)

Depending on the first parameter, this function will have different parameters and return values

* 'names', Adds names to the subscriptions types for display
   $arg1 will be a $subscriptions object.
   It should populate the 'type_name' and the 'names' elements for subscriptions handled by the module
   implementing it. A single subscription may join different conditions so we keep multiple names
   in the 'names' element array.
   
	Example:
  $subs = &$arg0;
  if ($subs->event_type == 'node') {
    $subs->type_name = t('Content');
    if (!empty($subs->fields['type'])) {
      $subs->names['type'] = t('Content type: %type', array('%type' => node_get_types('name', $subs->fields['type'])));
    }
    if (!empty($subs->fields['author'])) {
      $author = user_load(array('uid' => $subs->fields['author']));
      $subs->names['author'] = t('Author: %name', array('%name' => $author->name));
    }
  }

* 'subscription types', Defines subscription types provided by this module
  The return value will be an array of elements with the form:
  'type name' => array(
     'event_type' => type of event,
     'title' => Name to display to the user,
     'access' => Permission for using this subscription type,
     'page' => Callback to display the user subscriptions page,
     'fields' => Array of fields that define this subscription type. I.e. for node subscriptions, 
  )
  
  Example:
     $types['thread'] = array(
        'event_type' => 'node',
        'title' => t('Threads'),
        'access' => 'subscribe to content',
        'page' => 'notifications_content_page_thread',
        'fields' => array('nid'),
      );

* 'query', Returns query conditions for finding subscribed users

	Example:
	$query[] = array(
	  'fields' => array(
	    'nid' => $node->nid,
	    'type' => $node->type,
	    'author' => $node->uid,
	  ),
	);
  
- 'event types', Event types supported by this module
- 'event load', Add objects to the event for message composing
- 'node options', Returns subscriptions status and options for a node object 
See 
- notifications_content_notifications()
- notifications_taxonomy_notifications()