modules/notifications/API.txt

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()
1	Developer doocumentation for subscriptions framework.
2
3	[TO DO]
4
5	The notifications hook
6	----------------------
7	This hook must be implemented by modules defining event and subscription types
8
9	function hook_notifications($op, &$arg0 = NULL, $arg1 = NULL, $arg2 = NULL)
10
11	Depending on the first parameter, this function will have different parameters and return values
12
13	* 'names', Adds names to the subscriptions types for display
14	$arg1 will be a $subscriptions object.
15	It should populate the 'type_name' and the 'names' elements for subscriptions handled by the module
16	implementing it. A single subscription may join different conditions so we keep multiple names
17	in the 'names' element array.
18
19	Example:
20	$subs = &$arg0;
21	if ($subs->event_type == 'node') {
22	$subs->type_name = t('Content');
23	if (!empty($subs->fields['type'])) {
24	$subs->names['type'] = t('Content type: %type', array('%type' => node_get_types('name', $subs->fields['type'])));
25	}
26	if (!empty($subs->fields['author'])) {
27	$author = user_load(array('uid' => $subs->fields['author']));
28	$subs->names['author'] = t('Author: %name', array('%name' => $author->name));
29	}
30	}
31
32	* 'subscription types', Defines subscription types provided by this module
33	The return value will be an array of elements with the form:
34	'type name' => array(
35	'event_type' => type of event,
36	'title' => Name to display to the user,
37	'access' => Permission for using this subscription type,
38	'page' => Callback to display the user subscriptions page,
39	'fields' => Array of fields that define this subscription type. I.e. for node subscriptions,
40	)
41
42	Example:
43	$types['thread'] = array(
44	'event_type' => 'node',
45	'title' => t('Threads'),
46	'access' => 'subscribe to content',
47	'page' => 'notifications_content_page_thread',
48	'fields' => array('nid'),
49	);
50
51	* 'query', Returns query conditions for finding subscribed users
52
53	Example:
54	$query[] = array(
55	'fields' => array(
56	'nid' => $node->nid,
57	'type' => $node->type,
58	'author' => $node->uid,
59	),
60	);
61
62	- 'event types', Event types supported by this module
63	- 'event load', Add objects to the event for message composing
64	- 'node options', Returns subscriptions status and options for a node object
65	See
66	- notifications_content_notifications()
67	- notifications_taxonomy_notifications()