modules/subscription/CONTRIBUTE.txt


Contribute
------------------------------------------------------------------------------
1. How do you register subscription about a new content type?

Create a new module function, which invokes subscription_store.

Example:
<code>
function watchdognotify_subscribe(){
  global $user;
  $condition = array('severity' => 2);
  subscription_store('watchdog', $condition);
  drupal_goto('user/'.$user->uid.'/subscriptions'); 
}
</code>

Use hook_subscription to display a link to your new subscription type.
<code>
function watchdognotify_subscription($op, $arg1 = null, $arg2 = null) {
  if ($op == 'special') {
      return l("Subscribe to site errors", 'subscription/add/watchdog'); 
  }   
}
</code>

2. How do you notify users about new content?

A.) call subscription_trigger when the new content is created  

OR

B.) check frequently for new content via hook_subscription() with cron op:

Example:
<code>
function watchdognotify_subscription($op, $arg1 = null, $arg2 = null) {
  if ($op == 'cron') {
    $events = array();
    $result = db_query("SELECT * FROM watchdog WHERE timestamp>%d AND timestamp<=%d", $arg1, $arg2);
     while ($event = db_fetch_array($result)) {
      $events[] = $event;
    }  
    return array(array('watchdog'=>$events));
  }
}
</code>

If necessary you can return more than one type of content:
<code>
return array(array('watchdog'=>array(...),'error'=>array(....)))
</code>

If it is possible to implement both methods A and B from above, implement both, and choose which one to use:

Use method A when
<code> 
if (variable_get('subscription_instant_mode', 0)) {
  // use method B
}
else {
  // use method A
}
</code>

3. How will the content be displayed in existing channels?

Register a formatter via hook_subscription():

<code>
function watchdognotify_subscription($op, $arg1 = null, $arg2 = null) {
// [...]
  if ($op == 'formatter') {
    $formatters = array();
    $formatters[] = array('name' => 'Watchdog formatter', 'object' => 'watchdog', 'channel' => '*', 'weight' => 20, 'handler' => 'watchdognotify_formatter');
    return $formatters;
  }   
}
</code>

Then implement a handler:
<code>
function watchdognotify_formatter($object, $type) { 
 return wordwrap('['.format_date($object['timestamp'], 'small').']['.$object['hostname'].']ERROR: '. $object['message']."\n",72);
}
</code>


4. How do you create new channels?
Register the channel via hook_subscriptions:
<code>
function ftpchannel_subscription($op, $arg1 = null, $arg2 = null) {
  if ($op == 'channel') {
    $channels = array();
    $channels[] = array('name' => 'Simple FTP channel', 'id' => 'ftpchannel', 'handler' => 'ftpchannel_urlchannel');
    return $channels;
  }
}
</code>

And implement handler function (notify op):
<code>
function ftpchannel_urlchannel($op, $objects) {
  if ($op == 'notify') {
    foreach ($objects as $uid => $group) {
    $url = variable_get('ftpchannel_url', '').'.'.$uid.'.drupal';
      _ftpchannel_ftpremove($url);
      $handle = fopen($url, "w");
      fwrite($handle, ftpchannel_format($objects));
      fclose($handle);
    }
  }
}
</code>
1
2	Contribute
3	------------------------------------------------------------------------------
4	1. How do you register subscription about a new content type?
5
6	Create a new module function, which invokes subscription_store.
7
8	Example:
9	<code>
10	function watchdognotify_subscribe(){
11	global $user;
12	$condition = array('severity' => 2);
13	subscription_store('watchdog', $condition);
14	drupal_goto('user/'.$user->uid.'/subscriptions');
15	}
16	</code>
17
18	Use hook_subscription to display a link to your new subscription type.
19	<code>
20	function watchdognotify_subscription($op, $arg1 = null, $arg2 = null) {
21	if ($op == 'special') {
22	return l("Subscribe to site errors", 'subscription/add/watchdog');
23	}
24	}
25	</code>
26
27	2. How do you notify users about new content?
28
29	A.) call subscription_trigger when the new content is created
30
31	OR
32
33	B.) check frequently for new content via hook_subscription() with cron op:
34
35	Example:
36	<code>
37	function watchdognotify_subscription($op, $arg1 = null, $arg2 = null) {
38	if ($op == 'cron') {
39	$events = array();
40	$result = db_query("SELECT * FROM watchdog WHERE timestamp>%d AND timestamp<=%d", $arg1, $arg2);
41	while ($event = db_fetch_array($result)) {
42	$events[] = $event;
43	}
44	return array(array('watchdog'=>$events));
45	}
46	}
47	</code>
48
49	If necessary you can return more than one type of content:
50	<code>
51	return array(array('watchdog'=>array(...),'error'=>array(....)))
52	</code>
53
54	If it is possible to implement both methods A and B from above, implement both, and choose which one to use:
55
56	Use method A when
57	<code>
58	if (variable_get('subscription_instant_mode', 0)) {
59	// use method B
60	}
61	else {
62	// use method A
63	}
64	</code>
65
66	3. How will the content be displayed in existing channels?
67
68	Register a formatter via hook_subscription():
69
70	<code>
71	function watchdognotify_subscription($op, $arg1 = null, $arg2 = null) {
72	// [...]
73	if ($op == 'formatter') {
74	$formatters = array();
75	$formatters[] = array('name' => 'Watchdog formatter', 'object' => 'watchdog', 'channel' => '*', 'weight' => 20, 'handler' => 'watchdognotify_formatter');
76	return $formatters;
77	}
78	}
79	</code>
80
81	Then implement a handler:
82	<code>
83	function watchdognotify_formatter($object, $type) {
84	return wordwrap('['.format_date($object['timestamp'], 'small').']['.$object['hostname'].']ERROR: '. $object['message']."\n",72);
85	}
86	</code>
87
88
89	4. How do you create new channels?
90	Register the channel via hook_subscriptions:
91	<code>
92	function ftpchannel_subscription($op, $arg1 = null, $arg2 = null) {
93	if ($op == 'channel') {
94	$channels = array();
95	$channels[] = array('name' => 'Simple FTP channel', 'id' => 'ftpchannel', 'handler' => 'ftpchannel_urlchannel');
96	return $channels;
97	}
98	}
99	</code>
100
101	And implement handler function (notify op):
102	<code>
103	function ftpchannel_urlchannel($op, $objects) {
104	if ($op == 'notify') {
105	foreach ($objects as $uid => $group) {
106	$url = variable_get('ftpchannel_url', '').'.'.$uid.'.drupal';
107	_ftpchannel_ftpremove($url);
108	$handle = fopen($url, "w");
109	fwrite($handle, ftpchannel_format($objects));
110	fclose($handle);
111	}
112	}
113	}
114	</code>