====== Email Subscriptions ======

FIXME

DokuWiki allows individual users to "subscribe" to page changes. When a page is changed by a user all other users who have subscribed to that page will receive an email describing the changes. The email shows the changes in [[wp>Diff#Unified_format|unified diff format]], a sample email is shown at the bottom of this page.

The subscription facility is controlled using the [[config:subscribers|subscribers configuration setting]].  It is turned off by default.

**Note for wiki admins**

Be careful in switching this facility on.  In a busy wiki, with both frequent changes and many subscribers, emailing the changes to those subscribers can put a heavy strain on the webserver.  In a public wiki it may also provide unscrupulous people with a way to send spam to your wiki's users.

[[syndication|RSS Feeds]] provide an alternative (and lighter) mechanism for receiving details of updates to the wiki.

===== .mlist files =====

Using the Subscriptions will create files with the extension .mlist in the ~/data/meta/ folders and subfolders. In each .mlist file are the subscribed usernames.

If you have stored the Wiki on a Windows system, you can use the following command to have a look to all files and entries:

  findstr /s "." *.mlist

You can likewise use the following command on a Linux system:

  grep -rH ".*" *.mlist

In either case, be sure to change to your data/meta directory first.

===== Issues =====

  * <del>The changes will also be sent to the original author of the change if he/she is subscribed to the page. There is currently no way to prevent your OWN changes from being emailed to you if you are subscribed. You may however find a tip [[tips:subscription|here]]</del> :!: This is now included in version 2009-02-14
  * Every save to a page generates an email to the subscribers. So if an editor tends to save and re-save several times during editing, the subscribers will get a large volume of emails. It may be desired to modify this plugin to send a daily digest of changes or something similar.
  * <del>When enabled, this displays 2 buttons. "Subscribe Page Changes" and "Subscribe Namespace Changes". Although you can disable Namespace Change subscription in Admin > Configuration Settings under Authentication Settings, it would be good if when disabling Namespace Changes Subscription, that it also hides the button.</del> :!: This is now included in version 2009-02-14
    * **Solution for hiding buttons when action is disabled: **(for DokuWiki 2008-05-05)\\ Edit the file //inc/template.php//. Find the function //tpl_button($type)//. Find //case 'subscription'//:\\ Replace:<code php>
          if($INFO['subscribed']){
            print html_btn('unsubscribe',$ID,'',array('do' => 'unsubscribe',));
          } else {
            print html_btn('subscribe',$ID,'',array('do' => 'subscribe',));
          }
          if($INFO['subscribedns']){
            print html_btn('unsubscribens',$ID,'',array('do' => 'unsubscribens',));
          } else {
            print html_btn('subscribens',$ID,'',array('do' => 'subscribens',));
          }
</code>With this:<code php>
    if(actionOK('subscribe')){
          if($INFO['subscribed']){
            print html_btn('unsubscribe',$ID,'',array('do' => 'unsubscribe',));
          } else {
            print html_btn('subscribe',$ID,'',array('do' => 'subscribe',));
          }
    }

    if(actionOK('subscribens')){
          if($INFO['subscribedns']){
            print html_btn('unsubscribens',$ID,'',array('do' => 'unsubscribens',));
          } else {
            print html_btn('subscribens',$ID,'',array('do' => 'subscribens',));
          }
    }
</code>


  * <del>It would be nice if the email also said //who// made the changes (either the logged-in username, or the IP address) - especially useful for non-public wikis. * Aha! I did some digging, and found that I simply need to include the string **@USER@** in the file inc/lang/en/subscribermail.txt - sweet!</del> :!: This is now included by default in version 2009-02-14
  * It would be useful if the SuperUser could add arbitrary additional email addresses to a subscription. This would be useful in a situation where LDAP is being used for authentication and the superuser would like to subscribe a distribution group to page changes, rather than an individual user.  
  * It would be useful for the SuperUser to be able to select the default behavior of subscription. this way there would be one configuration when subscribers receive an email **Unless** the editor marks the change as trivial, versus another when the subscriptions receive an email **only** when the editor marks it as important.
===== Example email =====

<file>
Hello!

The page sample_page in the Wiki Name wiki changed.
Here are the changes:

--------------------------------------------------------
@@ -3,18 +3,18 @@
  
  ===== Section Title =====
 
- (This is some example text)
+ (This is some different example text.)
  

--------------------------------------------------------

Date        : 2009/12/25 11:19
User        : sampleuser
Edit Summary: sample edit summary
Old Revision: http://www.example.com/doku.php?id=sample_page?rev=1246611477
New Revision: http://www.example.com/doku.php?id=sample_page

To cancel the page notifications, log into the wiki at
http://www.example.com/ then visit
http://www.example.com/doku.php?id=sample_page
and unsubscribe page and/or namespace changes.

--
This mail was generated by DokuWiki at
http://www.example.com/
</file>