Differences

This shows you the differences between two versions of the page.

--- subscription [2013-01-11 13:13] – [.mlist files] 82.95.74.27
+++ subscription [2023-09-25 20:15] (current) – Klap-in
@@ Line 1: / Line 1: @@
 ====== 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 user changing the page will not receive an email.
-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.
+Only [[: login |logged in]] users have access to the "Manage Subscriptions" [[:main_window#page_tools |page tool]] (see screenshot below), it is not possible for anonymous / not [[:user registration |registered]] users to subscribe. Note that DokuWiki's email subscriptions are meant as a [[wp>collaboration tool]], not as newsletter - for anonymous / newsletter-like change information supply DokuWiki offers an RSS feed, see [[:syndication |XML Syndication]].
-**Note for wiki admins**
+===== Enabling Subscriptions =====
+The subscription facility is controlled using the [[config:subscribers|subscribers setting]].  It is turned **off by default**. You can turn it on in the configuration page of your wiki. Also, make sure to uncheck 'Subscribe/Unsubscribe' of disableactions in the authentication section of the configuration. The sender address is set by [[config:mailfrom|mailfrom setting]].
 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.
+Please also note that the subscribe feature is different from the [[config:notify|notify]] setting. The latter works even when subscriptions are turned off.
 [[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.
+===== Manage Subscriptions=====
-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:
+You can display the Subscription Management for the current page via the ''Manage Subscriptions'' button of the pagetool.
-  findstr /s "." *.mlist
+To subscribe you choose between two kind of subscriptions:{{ :subcriptionmanagement.png?400|}}
+  * The **current page**\\ Where you can set notification frequency to:
+    * email on every change
+    * digest email of changes for each page (every 1.00 days)
+  * The **whole current namespace**\\ Where you can set notification frequency to:
+    * email on every change
+    * digest email of changes for each page (every 1.00 days)
+    * list of changed pages since last email (every 1.00 days)
-You can likewise use the following command on a Linux system:
+When you are subscribed to the page or namespace it will show up in the overview of current subscriptions. A namespace subscription appears on the management page of all pages within it.
-  grep -rH ".*" *.mlist
+The frequency of digest and list mails can be set through the [[config:subscribe_time|subscribe_time]] setting.
-On a Mac (but I presume on a Linux system as well) the following statement works much better:
-  egrep -r --include="*.mlist" every\|digest .
+==== Unsubscribing ====
-(every=notify on any change, digest=digest changes)
+To unsubscribe you have to go the subscribed page or namespace, open the Subscription Management as described above and click on unsubscribe next to the subscription you want to remove.
-In either case, be sure to change to your data/meta directory first.
+To ease finding the correct entry point for unsubscribing you will find the link at the bottom of every subscription mail you receive.
-===== Issues =====
+===== Customizing =====
-  * <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
+==== Subscription emails ====
-  * 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')){
+The subscriptions emails are in the folder ''inc/lang/en'' with names beginning with ''subscr_''. When you like to modify them, please copy first to ''conf/lang/en'' to prevent overwriting at upgrading. See [[localization#changing_localized_texts_in_your_installation|changing localized texts]] for more information.
-          if($INFO['subscribedns']){
-            print html_btn('unsubscribens',$ID,'',array('do' => 'unsubscribens',));
-          } else {
-            print html_btn('subscribens',$ID,'',array('do' => 'subscribens',));
-          }
-    }
-</code>
+==== .mlist files ====
-  * <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
+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.
-  * 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>
+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:
-Hello!
-The page sample_page in the Wiki Name wiki changed.
+  findstr /s "." *.mlist
-Here are the changes:
---------------------------------------------------------
+You can likewise use the following commands on a Linux system:
-@@ -3,18 +3,18 @@
+  grep -r ".*\.mlist$"
+  find . -name "*.mlist"
+  ls *.mlist
-  ===== Section Title =====
-- (This is some example text)
-+ (This is some different example text.)
+On a Mac (but I presume on a Linux system as well) the following statement works much better:
+  egrep -r --include="*.mlist" every\|digest\|list .
+(every=notify on any change, digest=digest changes, list=list of pages)
+Searching for all subscriptions of a particular user on [[https://openbsd.org|OpenBSD]] or similar UNIX platforms, where grep does not support the ''%%--include%%'' option, can be done like this (for the user with the short name ''//user//''):
+  find . -name '*.mlist' -exec egrep -n '^user ' {} +
---------------------------------------------------------
+In any case, be sure to change to your ''[wiki directory]/data/meta'' directory first.
-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>