README.txt in Subscriptions 7

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



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




Overview
--------

Subscriptions enables users to subscribe to be notified of changes to nodes
or taxonomies, such as new comments in specific forums, or additions to some
category of blog. Once enabled, all nodes will have an additional link that
allows the user to change their subscriptions. Users have tab on their user
screen to manage their own subscriptions. Users can also set an auto-subscribe
function which notifies the user if anyone comments on posts they have made.
Admins can turn this on by default.




Requirements
------------

For sending mail using Subscriptions Mail the following modules are needed:
  - Mail Editor     http://drupal.org/project/mail_edit
  - Token           http://drupal.org/project/token




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.
Ported to Drupal 7 by salvis.

http://drupalcontrib.org/drupal-7-modules 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
- Arabic:               N2H




Modules
-------

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

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.

HTML Mail (http://drupal.org/project/htmlmail) provides a way to send themed
HTML mails.





Upgrading from 6.x-1.x
----------------------

Subscriptions D7 is designed to smoothly upgrade a 6.x-1.5 installation.
Upgrading later D6 versions should work as well.

The proprietary !variables in the D6 Mail Editor have been replaced with the
core [tokens]. Subscriptions attempts to update your templates, but you must
review each one to verify that it produces the desired result. The tokens
as well as other advancements in Drupal and in Mail Editor provide more
sophisticated functionality. Some of this is displayed by the new default
templates, so you may want to have a look at these, too.




Upgrading from 5.x-2.x to 6.x-1.5
---------------------------------

Subscriptions 6.x-1.5 is designed to smoothly upgrade and convert a 5.x-2.6
installation.




Upgrading from 5.x-1.x to 5.x-2.6
---------------------------------

Subscriptions 5.x-2.6 is designed to smoothly upgrade and convert a 1.9
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
(where 1234 is a nid, 123 a tid, and 12 a uid)

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/config/system/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,
as soon as 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 and even loops in the templates. The syntax is
explained in the fieldset on the edit pages. We strongly recommend that you
start with outputting the token text into a notification before you try to
use it as a condition or in another complex context.

Digest mail template: Each digest item is formatted using the content type 
of the item.

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

The default templates add a list of attached files, based on the assumption
that the files field is named 'field_files'.

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 default templates demonstrate how you can distinguish
and highlight unpublished nodes/comments.

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





Blocking sending of email notifications
---------------------------------------

The Subscriptions module can be configured to discard all notification emails
by adding a kill-switch in your settings.php file. This is often useful during
development and testing when you have a database of real users subscribed to
receive notifications, but you do not wish to send these notifications from a
development or staging server.

Add a single line at the end of the settings.php file like this:

  $conf['subscriptions_mail_trash_silently'] = TRUE;

Note that by default, this variable is set to FALSE, unless you specifically
override it. Although it cannot be configured directly from the settings page
in the administration interface, you will receive an error message on that
page to remind you that this kill-switch has been enabled from the code.

Also see the MailLog module for site-wide control that allows blocking of all
email messages.




Support/Customizations
----------------------

Support by volunteers is available on

   http://drupal.org/project/issues/subscriptions?status=All&version=7.x

Please consider helping others as a way to give something back to the community
that provides Drupal and the contributed modules to you free of charge.


For paid support and customizations of this module or other Drupal work
contact the maintainer through his contact form:

   http://drupal.org/user/82964