modules/activitystream/DEVELOPERS.txt

The Activity Stream API allows you to bring a user's creations from third party sites into Drupal and insert them into a Drupal user's lifestream. Each item can be themed by you and by the site owner. 

You can add fields to the Activity Stream admin settings page, allowing the site administrator to add API keys or global settings for your module. You can also add fields to the user's profile page, allowing them to enter their usernames, passwords, or feed URLs for the site your module supports.

Each third party site should be it's own module. Don't mix multiple sites into a single module.

Hooks
======

streamapi
----------

Your module's streamapi hook is run when Activity Stream is updating the users' streams (usually from cron).

The API passes in a $user object that contains four properties:
 * uid 
 * userid 
 * password
 * feed
 
These properties contain the account information entered into the user's settings page, along with the uid of their Drupal account.

Your streamapi function will return an array. Each item in the array will be an array of stream items with the following keys:

 * guid - [REQUIRED] a unique id for each item from your module. This will allow Activity Streams to know if this is a new item or an update to an existing one.
 
 * title - [REQUIRED] The title of the item. This will be used in the stream and as the title for the Drupal node.
 
 * body - [optional] The contents of the item. This is not shown on the strea, but will be the body of the Drupal node.
 
 * link - [optional] A url for the original item on the third party site. The permalink to a blog entry, the photo page on Flickr, etc.
 
 * timestamp - [REQUIRED] A unix timestamp with the original item's date and time.
 
 * data - [optional] Any additional data that your module wants to store. Store complex data types by serializing first

If the site you are integrating provides an RSS feed for the user's activity, you might find it easiest to use the activitystream_feed module to do all your streamapi work. Simply construct the feed URL for your user and add it to the feed property of the user object. Then send that user object to activitystream_feed_streamapi and return what it returns.

For example, the Digg module does this...

function activitystream_digg_streamapi($user) {
	// This user doesn't have a digg ID entered
	if (!$user->userid) {
		return;
	}
	
	// Use the activitystream_feed module to pull in the user's
	// history. 
	$user->feed = 'http://digg.com/users/'.$user->userid . '/history.rss';
	$items = activitystream_feed_streamapi($user);
	return $items;
}

activitystream_admin
--------------------

This hook fetches any form fields you need to add to admin/settings/activitystream. The most common example of this would be an API key for the site you are integrating.

Modules should build a form using an array that mirrors the Drupal form API. activitystream.module will add the form elements to the admin settings page. To avoid collisions with other activitystream module's forms use your module's name as the form array's key. Your function should return the form array.

Example: 

function activitystream_flickr_activitystream_admin() {
	$form['activitystream_flickr'] = array(
		'#type' => 'fieldset',
		'#title' => t("Flickr"),
		'#description' => t("Flickr API settings."),
		'#weight' => 1,
		'#collapsible' => TRUE,
		'#collapsed' => TRUE
	);
	$form['activitystream_flickr']['activitystream_flickr_key'] = array(
		'#type' => 'textfield',
		'#title' => t("API Key"),
		'#description' => t("Your Flickr API Key"),
		'#default_value' => variable_get('activitystream_flickr_key', ''),
		'#required' => FALSE
	);
	return $form;
}

activitystream_settings
-----------------------

Implement a user settings form hook. Modules should build a form using an array that mirrors the Drupal form API. activitystream.module will add the form elements to a tab called Activity Streams on the user's Profile Edit page. Fields should be named yourmodulename_fieldname. For instance, to store the user ID for  Flickr, the field name is activitystream_flickr_userid 

To avoid collisions with other activitystream module's forms use your module's name as the form array's key. 

Return the form array.

Example:

function activitystream_flickr_activitystream_settings() {
	$form['activitystream_flickr'] = array(
      '#type' => 'fieldset',
      '#title' => t('Flickr settings'));
  $form['activitystream_flickr']['activitystream_flickr_userid'] = array(
    '#type' => 'textfield',
    '#title' => t('Username'),
    '#default_value' => $edit['activitystream_flickr_userid'],
    '#description' => t('The username for your Flickr account'));
  return $form;	
}

Theme Functions
===============

icon
----

Return an image used to identify the activity. Most themes expect this is a 16x16 image so you should stick with that. Return the full <img> tag for the image.

Example:

function theme_activitystream_flickr_icon() {
	return theme_image(drupal_get_path('module', 'activitystream_flickr') . '/flickr.png', 'Flickr');
}


item
----

Return the fully formatted activity stream item. 

@param
  $action
  Object with properties:
    nid - node id of Drupal node
    link - link to the original item
    data - Custom data your module stored
    
The item date and username should be run through the activitystream_date and activitystream_username themes, respectively, before displaying them. This allows site owners to create a unified date and username format for their stream. Likewise, if you provide an icon, you should provide it through the icon theme hook, giving theme designers the ability to replace your icon with one of their choice.

It is recommended that your item theme follow the HTML conventions shown in the example. This will allow theme designers to style stream items using only CSS.

Example:

function theme_activitystream_flickr_item($action) {
	$node = node_load($action->nid);
	$date = theme('activitystream_date',$node->created);
	$user = user_load(array('uid' => $node->uid));
	$name = theme('activitystream_username',$user);
	return '<span class="activitystream-item">' . theme('activitystream_flickr_icon') . " <span>$name posted " . l($node->title, $action->link) . " <span class=\"activitystream-created\">$date</span></span> " . l('#', 'node/' . $node->nid, array('class' => 'permalink')) . '</span>';
}

Helper Functions
================

activitystream_user_load
------------------------

Because user_load is called often, this provides a cache, ensuring that a given uid will only be loaded once. Call it instead of user_load.

@param
  $uid
    The Drupal UID for the user.

@returns
  $user
    A Drupal user object

Example:

$user = activitystream_user_load($node->uid);
1	The Activity Stream API allows you to bring a user's creations from third party sites into Drupal and insert them into a Drupal user's lifestream. Each item can be themed by you and by the site owner.
2
3	You can add fields to the Activity Stream admin settings page, allowing the site administrator to add API keys or global settings for your module. You can also add fields to the user's profile page, allowing them to enter their usernames, passwords, or feed URLs for the site your module supports.
4
5	Each third party site should be it's own module. Don't mix multiple sites into a single module.
6
7	Hooks
8	======
9
10	streamapi
11	----------
12
13	Your module's streamapi hook is run when Activity Stream is updating the users' streams (usually from cron).
14
15	The API passes in a $user object that contains four properties:
16	* uid
17	* userid
18	* password
19	* feed
20
21	These properties contain the account information entered into the user's settings page, along with the uid of their Drupal account.
22
23	Your streamapi function will return an array. Each item in the array will be an array of stream items with the following keys:
24
25	* guid - [REQUIRED] a unique id for each item from your module. This will allow Activity Streams to know if this is a new item or an update to an existing one.
26
27	* title - [REQUIRED] The title of the item. This will be used in the stream and as the title for the Drupal node.
28
29	* body - [optional] The contents of the item. This is not shown on the strea, but will be the body of the Drupal node.
30
31	* link - [optional] A url for the original item on the third party site. The permalink to a blog entry, the photo page on Flickr, etc.
32
33	* timestamp - [REQUIRED] A unix timestamp with the original item's date and time.
34
35	* data - [optional] Any additional data that your module wants to store. Store complex data types by serializing first
36
37	If the site you are integrating provides an RSS feed for the user's activity, you might find it easiest to use the activitystream_feed module to do all your streamapi work. Simply construct the feed URL for your user and add it to the feed property of the user object. Then send that user object to activitystream_feed_streamapi and return what it returns.
38
39	For example, the Digg module does this...
40
41	function activitystream_digg_streamapi($user) {
42	// This user doesn't have a digg ID entered
43	if (!$user->userid) {
44	return;
45	}
46
47	// Use the activitystream_feed module to pull in the user's
48	// history.
49	$user->feed = 'http://digg.com/users/'.$user->userid . '/history.rss';
50	$items = activitystream_feed_streamapi($user);
51	return $items;
52	}
53
54	activitystream_admin
55	--------------------
56
57	This hook fetches any form fields you need to add to admin/settings/activitystream. The most common example of this would be an API key for the site you are integrating.
58
59	Modules should build a form using an array that mirrors the Drupal form API. activitystream.module will add the form elements to the admin settings page. To avoid collisions with other activitystream module's forms use your module's name as the form array's key. Your function should return the form array.
60
61	Example:
62
63	function activitystream_flickr_activitystream_admin() {
64	$form['activitystream_flickr'] = array(
65	'#type' => 'fieldset',
66	'#title' => t("Flickr"),
67	'#description' => t("Flickr API settings."),
68	'#weight' => 1,
69	'#collapsible' => TRUE,
70	'#collapsed' => TRUE
71	);
72	$form['activitystream_flickr']['activitystream_flickr_key'] = array(
73	'#type' => 'textfield',
74	'#title' => t("API Key"),
75	'#description' => t("Your Flickr API Key"),
76	'#default_value' => variable_get('activitystream_flickr_key', ''),
77	'#required' => FALSE
78	);
79	return $form;
80	}
81
82	activitystream_settings
83	-----------------------
84
85	Implement a user settings form hook. Modules should build a form using an array that mirrors the Drupal form API. activitystream.module will add the form elements to a tab called Activity Streams on the user's Profile Edit page. Fields should be named yourmodulename_fieldname. For instance, to store the user ID for Flickr, the field name is activitystream_flickr_userid
86
87	To avoid collisions with other activitystream module's forms use your module's name as the form array's key.
88
89	Return the form array.
90
91	Example:
92
93	function activitystream_flickr_activitystream_settings() {
94	$form['activitystream_flickr'] = array(
95	'#type' => 'fieldset',
96	'#title' => t('Flickr settings'));
97	$form['activitystream_flickr']['activitystream_flickr_userid'] = array(
98	'#type' => 'textfield',
99	'#title' => t('Username'),
100	'#default_value' => $edit['activitystream_flickr_userid'],
101	'#description' => t('The username for your Flickr account'));
102	return $form;
103	}
104
105	Theme Functions
106	===============
107
108	icon
109	----
110
111	Return an image used to identify the activity. Most themes expect this is a 16x16 image so you should stick with that. Return the full <img> tag for the image.
112
113	Example:
114
115	function theme_activitystream_flickr_icon() {
116	return theme_image(drupal_get_path('module', 'activitystream_flickr') . '/flickr.png', 'Flickr');
117	}
118
119
120	item
121	----
122
123	Return the fully formatted activity stream item.
124
125	@param
126	$action
127	Object with properties:
128	nid - node id of Drupal node
129	link - link to the original item
130	data - Custom data your module stored
131
132	The item date and username should be run through the activitystream_date and activitystream_username themes, respectively, before displaying them. This allows site owners to create a unified date and username format for their stream. Likewise, if you provide an icon, you should provide it through the icon theme hook, giving theme designers the ability to replace your icon with one of their choice.
133
134	It is recommended that your item theme follow the HTML conventions shown in the example. This will allow theme designers to style stream items using only CSS.
135
136	Example:
137
138	function theme_activitystream_flickr_item($action) {
139	$node = node_load($action->nid);
140	$date = theme('activitystream_date',$node->created);
141	$user = user_load(array('uid' => $node->uid));
142	$name = theme('activitystream_username',$user);
143	return '<span class="activitystream-item">' . theme('activitystream_flickr_icon') . " <span>$name posted " . l($node->title, $action->link) . " <span class=\"activitystream-created\">$date</span></span> " . l('#', 'node/' . $node->nid, array('class' => 'permalink')) . '</span>';
144	}
145
146	Helper Functions
147	================
148
149	activitystream_user_load
150	------------------------
151
152	Because user_load is called often, this provides a cache, ensuring that a given uid will only be loaded once. Call it instead of user_load.
153
154	@param
155	$uid
156	The Drupal UID for the user.
157
158	@returns
159	$user
160	A Drupal user object
161
162	Example:
163
164	$user = activitystream_user_load($node->uid);