modules/subscriptions/README.txt


README.txt for Subscriptions 6.x-1.x


>>>> Please feel free to suggest improvements and additions to this file! <<<<


Acknowledgements
----------------

Subscriptions 5.x-2.0 has been rewritten from scratch by chx and salvis.
Ported to Drupal 6 and continuously enhanced by salvis.
Doxygen documentation by develCuy, sponsored by www.transit.york.ac.uk.

http://api.drupal-contrib.org/api/subscriptions provides on-line developer documentation.

Initial Translations:
- German:               salvis
- Hebrew:               yhager
- Italian:              peterpoe
- Spanish:              develCuy
- French:               matkeane
- Japanese:             PineRay
- Danish:               wulff / Anders Lund
- Brazilian Portuguese: Márcio Moreira
- Hungarian:            muczy

Contributed Modules:
- moderate_content_notifications:  written and maintained by beginner.

Known independent add-on modules:
- subscriptions_author:  by develCuy, sponsored by www.transit.york.ac.uk.
- subscriptions_og:      by develCuy, sponsored by www.transit.york.ac.uk.

The Organic Groups Subscriptions module has been developed independently.
Special care was taken to document the Subscriptions APIs that need to be
implemented and used for a non-trivial add-on module. As such it is an
example for building other add-on modules.


Modules
-------

For standard Subscriptions functionality you need to enable the following modules:
 * Subscriptions UI
 * Subscriptions Mail
 * Content Subscriptions
 * Taxonomy Subscriptions (e.g. forums!)

Mail Editor (http://drupal.org/project/mail_edit) allows you to customize the
notification messages sent by Subscriptions Mail.

SMTP Authentication (http://drupal.org/project/smtp) may be useful for sending
out emails, if your provider imposes limits on what you can do with PHP mail.


Upgrading from 5.x-1.x
----------------------

Subscriptions D6 is designed to smoothly upgrade and convert a 1.x 
installation. If you currently have 1.x installed, we recommend to put
your site in maintenance mode, remove the 1.x files (if you only move
them to a different directory under the web root, Drupal will still find
them and cause trouble!!!), copy the 2.x files where you want them, and
run update.php (directly or from Administer|Modules) as usual.

Subscriptions 1.x does not have an uninstall function. If you want to
remove it in order to start with a clean slate, then you need to disable
it, remove its database tables, and remove its row from the {system} table
(be careful!!!). Then you can do a fresh install of Subscriptions 2.0.


Permissions
-----------

Don't forget to set the permissions!

Subscriptions does not support anonymous users -- there's no use in
giving them any subscribe permissions.


Subscribe links
---------------

http://example.com/subscriptions/add/node/1234
http://example.com/subscriptions/add/type/blog
http://example.com/subscriptions/add/type/blog/12
http://example.com/subscriptions/add/type/forum
http://example.com/subscriptions/add/type/forum/12
http://example.com/subscriptions/add/taxa/123
http://example.com/subscriptions/add/taxa/123/12

You can combine these with a log-in link as follows:

http://example.com/user/login?destination=subscriptions/add/taxa/123


There are also corresponding

http://example.com/subscriptions/del/...

links with the same parameters, which can be used by the administrator to
provide unsubscribe links to a user. These unsubscribe links require the
user to be logged in. By default, Subscriptions sends out encrypted 
unsubscribe links with each notification, and those latter unsubscribe
links work even without logging in, but they cannot be generated by hand.


Send Intervals
--------------

Choose (and possibly adapt the strings) for the Send Intervals at 
admin/settings/subscriptions/intervals to your site! 
Specifically, "As soon as possible" means at the next cron run,
which of course primarily depends on how often you run cron...

Notifications are governed by the following rules:
1. They are only sent out when cron runs. 
2. Each user's first notification is sent at the very next cron run.
3. Whenever a notification is sent, the current timestamp is stored 
   as that user's last_sent entry in the {subscriptions_user} table.
4. Whenever a new notification is queued, the queue entry gets the
   last_sent timestamp and the send_interval for the subscription
   stored along with other information.
5. When cron runs, it considers only queue entries for which
   last_sent+send_interval is in the past.
6. When a notification is sent, possible duplicates for the same
   node are removed, so that no duplicate notifications are sent,
   even if multiple notifications are queued, e.g. because the user
   entered overlapping subscriptions or the node was updated or
   commented. 
   Obviously, in the case of overlapping subscriptions, the one with 
   the lowest Send Interval wins.
7. If digests are enabled, then a digest is sent whenever at least
   one notification is ready to be sent, and it includes all the
   notifications that are ready.


Cron Job
--------

The subscriptions_mail submodule uses cron to send notifications by email. 
You may want to adjust the list and descriptions of the Send Intervals.

We recommend that you keep the cron summary watchdog message enabled.
It gives you valuable information about the load of your cron job and your 
mail server.

Note: On a busy site it is normal that the queue does not become empty, 
but it should not keep growing indefinitely; if it does, you should run 
cron more frequently. 

Note: Subscriptions tries not to use up all the available time, because 
other modules may come after it; if it uses too much or too little, 
you can decrease or increase the subscriptions_cron_percent variable 
(the default is 50).


Mail Templates
--------------

Go to admin/build/mail_edit to edit the mail templates.

Some of the variables are only available if you save the templates, 
and not at all in digest mode.

However, as long as you DON'T save the templates, they are automatically
translated to the recipient's language. Like other user-modifiable strings, 
when you edit and save them, they stop getting localized. For multi-language
customization, you need to edit the subscriptions_mail.templates.inc file.

You can use conditional text in the templates. The syntax is

   {{!varname==value?then_text:else_text}} or
   {{!varname!=value?then_text:else_text}}

!varname can be the any variable and will be replaced;
value is a string that doesn't contain a '?';
then_text is a string that doesn't contain a ':' and
else_text doesn't have that limitation.

Both then_text and else_text can contain newlines and variables.

Example:
This {{!has_new_comments==1?has:doesn't have any}} new comments.

Undefined variables are replaced by themselves, i.e. they remain as !varname.
Example:
{{!sender_name==!sender_name?Sender is undefined:Sender: !sender_name}}

Variables can be defined and empty. Example:
{{!sender_name==?Sender is empty:Sender is either undefined or non-empty}}

Note: All the URL variables are built by calling the url() core function.
You may be able to influence the return value of url() by setting $base_url 
in settings.php. In any case, if you don't get what you expect, it's not 
an issue of Subscriptions.


Attached files
--------------
With a conditional expression like

{{!has_files==0?:| Files:
!files}}

you can send links to attached files along with the node in question.
We like showing the ugly login block only where needed, like on nodes
that aren't accessible without logging in and also when trying to download
an attached file through a direct link (if the Download method is Private).
To achieve that goal, you need to set the Login block to show only on 
the following URLs:

node/*
system/files/*


Unpublished Nodes/Comments
--------------------------

Subscriptions does not send notifications for unpublished nodes/comments 
except to users who have the 'administer nodes' / 'administer comments'
permissions. The
   !is_unpublished
   !comment_is_unpublished
variables let you mark unpublished nodes/comments, as demonstrated
in the default templates.

Publishing a node/comment will cause a notification to be sent to all 
subscribers.


1
2	README.txt for Subscriptions 6.x-1.x
3
4
5
6	>>>> Please feel free to suggest improvements and additions to this file! <<<<
7
8
9
10
11	Acknowledgements
12	----------------
13
14	Subscriptions 5.x-2.0 has been rewritten from scratch by chx and salvis.
15	Ported to Drupal 6 and continuously enhanced by salvis.
16	Doxygen documentation by develCuy, sponsored by www.transit.york.ac.uk.
17
18	http://api.drupal-contrib.org/api/subscriptions provides on-line developer documentation.
19
20	Initial Translations:
21	- German: salvis
22	- Hebrew: yhager
23	- Italian: peterpoe
24	- Spanish: develCuy
25	- French: matkeane
26	- Japanese: PineRay
27	- Danish: wulff / Anders Lund
28	- Brazilian Portuguese: Márcio Moreira
29	- Hungarian: muczy
30
31	Contributed Modules:
32	- moderate_content_notifications: written and maintained by beginner.
33
34	Known independent add-on modules:
35	- subscriptions_author: by develCuy, sponsored by www.transit.york.ac.uk.
36	- subscriptions_og: by develCuy, sponsored by www.transit.york.ac.uk.
37
38	The Organic Groups Subscriptions module has been developed independently.
39	Special care was taken to document the Subscriptions APIs that need to be
40	implemented and used for a non-trivial add-on module. As such it is an
41	example for building other add-on modules.
42
43
44
45
46	Modules
47	-------
48
49	For standard Subscriptions functionality you need to enable the following modules:
50	* Subscriptions UI
51	* Subscriptions Mail
52	* Content Subscriptions
53	* Taxonomy Subscriptions (e.g. forums!)
54
55	Mail Editor (http://drupal.org/project/mail_edit) allows you to customize the
56	notification messages sent by Subscriptions Mail.
57
58	SMTP Authentication (http://drupal.org/project/smtp) may be useful for sending
59	out emails, if your provider imposes limits on what you can do with PHP mail.
60
61
62
63
64
65	Upgrading from 5.x-1.x
66	----------------------
67
68	Subscriptions D6 is designed to smoothly upgrade and convert a 1.x
69	installation. If you currently have 1.x installed, we recommend to put
70	your site in maintenance mode, remove the 1.x files (if you only move
71	them to a different directory under the web root, Drupal will still find
72	them and cause trouble!!!), copy the 2.x files where you want them, and
73	run update.php (directly or from Administer\|Modules) as usual.
74
75	Subscriptions 1.x does not have an uninstall function. If you want to
76	remove it in order to start with a clean slate, then you need to disable
77	it, remove its database tables, and remove its row from the {system} table
78	(be careful!!!). Then you can do a fresh install of Subscriptions 2.0.
79
80
81
82
83
84
85	Permissions
86	-----------
87
88	Don't forget to set the permissions!
89
90	Subscriptions does not support anonymous users -- there's no use in
91	giving them any subscribe permissions.
92
93
94
95
96
97
98	Subscribe links
99	---------------
100
101	http://example.com/subscriptions/add/node/1234
102	http://example.com/subscriptions/add/type/blog
103	http://example.com/subscriptions/add/type/blog/12
104	http://example.com/subscriptions/add/type/forum
105	http://example.com/subscriptions/add/type/forum/12
106	http://example.com/subscriptions/add/taxa/123
107	http://example.com/subscriptions/add/taxa/123/12
108
109	You can combine these with a log-in link as follows:
110
111	http://example.com/user/login?destination=subscriptions/add/taxa/123
112
113
114	There are also corresponding
115
116	http://example.com/subscriptions/del/...
117
118	links with the same parameters, which can be used by the administrator to
119	provide unsubscribe links to a user. These unsubscribe links require the
120	user to be logged in. By default, Subscriptions sends out encrypted
121	unsubscribe links with each notification, and those latter unsubscribe
122	links work even without logging in, but they cannot be generated by hand.
123
124
125
126
127	Send Intervals
128	--------------
129
130	Choose (and possibly adapt the strings) for the Send Intervals at
131	admin/settings/subscriptions/intervals to your site!
132	Specifically, "As soon as possible" means at the next cron run,
133	which of course primarily depends on how often you run cron...
134
135	Notifications are governed by the following rules:
136	1. They are only sent out when cron runs.
137	2. Each user's first notification is sent at the very next cron run.
138	3. Whenever a notification is sent, the current timestamp is stored
139	as that user's last_sent entry in the {subscriptions_user} table.
140	4. Whenever a new notification is queued, the queue entry gets the
141	last_sent timestamp and the send_interval for the subscription
142	stored along with other information.
143	5. When cron runs, it considers only queue entries for which
144	last_sent+send_interval is in the past.
145	6. When a notification is sent, possible duplicates for the same
146	node are removed, so that no duplicate notifications are sent,
147	even if multiple notifications are queued, e.g. because the user
148	entered overlapping subscriptions or the node was updated or
149	commented.
150	Obviously, in the case of overlapping subscriptions, the one with
151	the lowest Send Interval wins.
152	7. If digests are enabled, then a digest is sent whenever at least
153	one notification is ready to be sent, and it includes all the
154	notifications that are ready.
155
156
157
158
159
160
161	Cron Job
162	--------
163
164	The subscriptions_mail submodule uses cron to send notifications by email.
165	You may want to adjust the list and descriptions of the Send Intervals.
166
167	We recommend that you keep the cron summary watchdog message enabled.
168	It gives you valuable information about the load of your cron job and your
169	mail server.
170
171	Note: On a busy site it is normal that the queue does not become empty,
172	but it should not keep growing indefinitely; if it does, you should run
173	cron more frequently.
174
175	Note: Subscriptions tries not to use up all the available time, because
176	other modules may come after it; if it uses too much or too little,
177	you can decrease or increase the subscriptions_cron_percent variable
178	(the default is 50).
179
180
181
182
183
184	Mail Templates
185	--------------
186
187	Go to admin/build/mail_edit to edit the mail templates.
188
189	Some of the variables are only available if you save the templates,
190	and not at all in digest mode.
191
192	However, as long as you DON'T save the templates, they are automatically
193	translated to the recipient's language. Like other user-modifiable strings,
194	when you edit and save them, they stop getting localized. For multi-language
195	customization, you need to edit the subscriptions_mail.templates.inc file.
196
197	You can use conditional text in the templates. The syntax is
198
199	{{!varname==value?then_text:else_text}} or
200	{{!varname!=value?then_text:else_text}}
201
202	!varname can be the any variable and will be replaced;
203	value is a string that doesn't contain a '?';
204	then_text is a string that doesn't contain a ':' and
205	else_text doesn't have that limitation.
206
207	Both then_text and else_text can contain newlines and variables.
208
209	Example:
210	This {{!has_new_comments==1?has:doesn't have any}} new comments.
211
212	Undefined variables are replaced by themselves, i.e. they remain as !varname.
213	Example:
214	{{!sender_name==!sender_name?Sender is undefined:Sender: !sender_name}}
215
216	Variables can be defined and empty. Example:
217	{{!sender_name==?Sender is empty:Sender is either undefined or non-empty}}
218
219	Note: All the URL variables are built by calling the url() core function.
220	You may be able to influence the return value of url() by setting $base_url
221	in settings.php. In any case, if you don't get what you expect, it's not
222	an issue of Subscriptions.
223
224
225
226
227	Attached files
228	--------------
229	With a conditional expression like
230
231	{{!has_files==0?:\| Files:
232	!files}}
233
234	you can send links to attached files along with the node in question.
235	We like showing the ugly login block only where needed, like on nodes
236	that aren't accessible without logging in and also when trying to download
237	an attached file through a direct link (if the Download method is Private).
238	To achieve that goal, you need to set the Login block to show only on
239	the following URLs:
240
241	node/*
242	system/files/*
243
244
245
246
247	Unpublished Nodes/Comments
248	--------------------------
249
250	Subscriptions does not send notifications for unpublished nodes/comments
251	except to users who have the 'administer nodes' / 'administer comments'
252	permissions. The
253	!is_unpublished
254	!comment_is_unpublished
255	variables let you mark unpublished nodes/comments, as demonstrated
256	in the default templates.
257
258	Publishing a node/comment will cause a notification to be sent to all
259	subscribers.
260
261
262