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. 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.