Last updated October 30, 2012. Created by gustav on December 7, 2008.
Edited by salvis, peterx, lelizondo, hapydoyzer. Log in to edit this page.

The subscriptions module enables users to subscribe to be notified of new or updated nodes or of comments. Users can subscribe to individual nodes, all nodes of a particular content type or all nodes tagged with a particular taxonomy term, for example all topics in a particular forum or entries in a particular blog.

The subscriptions module provides a flexible framework that allows other modules to provide additional subscription types, for example by author or organic group.

Once enabled, all nodes can have an additional link that allows the user to change their subscriptions. In addition, users have a tab on their user screen from where they can manage all of their subscriptions. Users can also set an auto subscribe function which notifies them if anyone comments on or updates posts they have made. Admins can set this on by default.

Users can choose the frequency of notification emails and can also choose to have them delivered in digest form. The admin can customise the notification emails using mail templates.

For each subscription the user can choose whether to be notified only of new nodes, or also of updates, or also of comments. The admin has fine control of which of the many subscription options to make available to the user. The subscription user interface can hence be as simple or as complex as the admin likes.

The subscription module is similar to the notifications module. Both are rewrites of the old 5.x-1 subscriptions module. Both modules provide extensible frameworks. However the two modules differ in the details of the types of options and functionality they provide.

This page is work in progress. Please contribute.

Table of Contents:


Installation

Installation is standard: just download the latest release, put it into your modules folder and then enable the modules under Administration -> Site building -> Modules.

Modules

For standard Subscriptions functionality you need to enable the following modules:

  • Subscriptions The basic Subscriptions framework.
  • Subscriptions UI Provides the user interface to allow users to subscribe and to manage their subscriptions.
  • Subscriptions Mail Does the actual mailing out.
  • Content Subscriptions Allows users to subscribe to nodes.

You will usually want to also enable one or more of the following modules that are included in the subscriptions download package:

  • Taxonomy Subscriptions Allows users to subscribe to taxonomy terms (e.g. forums!)
  • Blog Subscriptions UI Provides a separate blogs subscriptions page.
  • Subscriptions CCK fields Allows you to include CCK fields in your notification emails if you also use the mail_edit module.
  • Moderate Content Notifications Spam deterrent: make sure no spam is sent from our web site.

Subscriptions 2.x is a modular framework, designed to be extensible in many directions. A number of add-ons are already available:

  • Author Subscriptions: subscribe to all posts by one author, also serves as an example of a simple third-party add-on.
  • Event Subscriptions: include start and end dates/times from the Event 5.x-2.x module in your notifications.
  • Organic Groups Subscriptions: fully-featured integration with OG; an ambitious third-party add-on.
  • Reduce Content Queue (experimental): suppress queueing of certain notifications until the user visits the site again.

Other related third-party modules that you may want to install include:

  • Mail Editor allows you to customize the notification messages sent by Subscriptions Mail.
  • SMTP Authentication may be useful for sending out emails if your provider imposes limits on what you can do with PHP mail.

Permissions

Don't forget to set the permissions by going to Administration -> User management -> Permissions. The set of permissions that you can grant will depend on which modules you have enabled. They may include:

subscribe to content
This is the main permission. Without this a user can not subscirbe to any notifications.
subscribe to content types
Allows a user to subscribe to all nodes of a particular type at once, for example to all blog entries on the site or to all forum posts, etc. The admin can select which content types should be available for subscription to users with this permission.
subscribe to all content types
The admin restrict which content types are available for subscription. The "subscribe to all content types" permission grants normal access to such unlisted and blocked content types. This is intended as an administrative function. The content types will be marked with a ¤ symbol (and appear in red in the case of blocked types).
subscribe to blogs
Allows a user to subscribe to all entries in a particular user's blog.
subscribe to taxonomy terms
Allows a user to subscribe to all nodes that are tagged with a particular taxonomy term.
Administer user subscriptions
Allows user to administer settings for other users. Users with "subscribe to content" permission can always administer their own subscriptions.

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

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.


Configuration

On the Subscriptions settings page at admin/settings/subscriptions you will find three tabs:

which we will now describe in turn.

Site settings


The site settings page has a varying number of field sets, depending on which subscription modules you have enabled.

Links

This is just a list of convenient links to other administration pages.

Content settings

This section is available if you have "Content subscriptions" module enabled (which you most certainly should). Among other things it provides you options to restrict the available subscription types.

Taxonomy settings

This fieldset is present if you have the "Taxonomy subscriptions" module enabled and allows you to restrict which vocabularies should be available for subscriptions and whether all terms in those vocabularies should be listed on the user's subscriptions page or only those that the user has subscribed to.

Display settings

Mail settings


User defaults


This allows the admin to set defaults for all users' settings. Each user has a similar subscriptions settings page available via a tab on their profile page and can change most of these defaults. However for some settings it is even possible to hide them from the users so that they can not change them away from the defaults.


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:

  • They are only sent out when cron runs.
  • Each user's first notification is sent at the very next cron run.
  • Whenever a notification is sent, the current timestamp is stored as that user's last_sent entry in the {subscriptions_user} table.
  • 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.
  • When cron runs, it considers only queue entries for which last_sent+send_interval is in the past.
  • 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.
  • 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

If you have installed and enabled the mail_edit module then you can go to admin/build/mail_edit to edit the mail templates.

You will find that the subscriptions module is providing a range of templates. Which template is used for a particular notification depends on the kind of subscription that is triggering it. So for example a notification that is sent because the user has subscribed to a taxonomy term will use the subscriptions_taxonomy_node-tid template. Notifications that are sent because the user has subscribed to a content type will use the content type specific template, for example subscriptions_content_node-type-blog for a subscription to all blogs. Similarly, a notification that is sent because the user has subscribed to a specific node will usually use the subscriptions_content_node-nid template.

However, there is an exception to the above rule: notifications of updated nodes that are sent because of a node subscription will nevertheless use the content-type-specific template, but only for those content types that the user could subscribe to. Note that this exception is only used for subscriptions to individual nodes, NOT to any other subscription type. So, for example, if a notification is sent out about an updated book page because the user has subscribed to a particular taxonomy term that the book page is tagged with, then the notification will NOT use the book page template subscriptions_content_node-type-book but the generic subscriptions_content_node-nid template.

If the user has chosen to get the notifications in digest form then always the template subscriptions_mail_digest will be used.

A long list of available variables that you can use in your templates are listed on the template editing pages when you expand the "Replacement patterns" fieldsets. Some of the variables are only available after you have saved the template once. If you enable the subscriptions CCK field module then, in the content type specific templates, you will get extra variables for each CCK field that exists for the content type.

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.

Note that only variable names that appear on the left-hand side of an equation are replaced and only if the variable is not empty. You can use a condition like !sender_name==!sender_name. The left side of !sender_name==!sender_name is replaced if the sender name is set, but the right side isn't. Therefore the condition is true only when the variable is not set.

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.

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.


User Interface

To be written.


API

API Documentation

Some explanation of the API can be found in the wiki page "HOWTO build an add-on for Subscriptions module" at http://groups.drupal.org/node/9818

Code documentation is available at http://drupalcontrib.org/api/drupal/contributions--subscriptions--subscr...

You can put links on your site that bring your users to pages for subscribing to particular content:

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.


Other Information

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.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.