%META:TOPICINFO{author="ProjectContributor" comment="" date="1512791273" format="1.1" version="1"}%
%META:TOPICPARENT{name="Plugins"}%
<img src="%ATTACHURL%/logo.gif" class="foswikiRight" />
---+ Subscribe Plugin

<!--
   * Set SHORTDESCRIPTION = This is a companion plugin to the MailerContrib. It allows you to trivially add a "Subscribe me" link to topics to get subscribed to changes.
-->
%SHORTDESCRIPTION%

Example (only works if plugin is installed, and you are logged in - you are: %WIKIUSERNAME% - and you are not %USERSWEB%.WikiGuest): %SUBSCRIBE%

%X% This version is designed for use with Foswiki 2.0 and later. While it will work with Foswiki 1.1.x, it is *not* recommended that you install it there.

---++ Usage
%INCLUDE{"VarSUBSCRIBE" section="subscribe_attributes"}%

%X%Note: This subscribe macro is for adding and removing individual subscriptions.  It is not aware of subscriptions due to membership in a subscribed group.  If a user is subscribed to a topic due to group membership,  the subscribe link will show the user as subscribed,
but clicking it will *not* unsubscribe the individual user.  If a user wishes to unsubscribe as an exception, manually add a "negative subscription" to the WebNotify topic.  Ex:  If !JoeUser is a member of !SomeGroup,
then the user can unsubscribe manually:
<noautolink>
   * %USERSWEB%.SomeGroup : *
   * %USERSWEB%.JoeUser : - UndesiredTopic
</noautolink>

---++ Access Controls
The guest user is not allowed to subscribe for notification.

You don't need =VIEW= access to the WebNotify topic in order to subscribe to changes in a web, but you must have =CHANGE= access. If you want users to be able to subscribe or unsubscribe, but you don't want them to be able to modify their subscription or otherwise edit the WebNotify topic, you can restrict =VIEW= access to WebNotify. This will make it uneditable from the browser (but will not block =save= urls, so is not fully secure).

%X% Note that permissions on individual topics are *not* checked when subscription mails are sent out, so be very careful about who you allow to subscribe.

---++ Configuration

If you wish to limit the plugin to one or more webs, specifiy the list of Active Webs in one of the following ways.   This list is a comma-separates list of Web names.  A "Regular-expression" style wildcard can be used.  For
example: =%USERSWEB%,%SANDBOXWEB%.*= would permit the %USERSWEB% web, %SANDBOXWEB%, including subwebs of %SANDBOXWEB%, or any web prefixed with %SANDBOXWEB%.

   * [[%SCRIPTURL{"configure"}%][configure -> =Extensions= tab -> =SubscribePlugin= sub-tab]]
      * ={Plugins}{SubscribePlugin}{ActiveWebs} = "%USERSWEB%,%SANDBOXWEB%.*=
   * As a standard preference setting, set in %LOCALSITEPREFS% or individual %WEBPREFSTOPIC% topics.
      * =Set SUBSCRIBEPLUGIN_ACTIVEWEBS = %USERSWEB%,%SANDBOXWEB%.*=

The configure setting takes precedence over the topic based preference setting.

Templates for all forms and strings used by the plugin are specified in =templates/subscribe.tmpl=, which can be overridden using the standard [[Skins][Foswiki skins]] mechanisms.

---++ REST handler

The plugin uses a REST handler to perform the actual subscription. This handler
is also available for other clients wishing to use the subscription service.

=.../rest/SubscribePlugin/subscribe=

Parameters:
   * =subscribe_topic= topic to subscribe to/unsubscribe from. Value of =topic= parameter is used if missing. Use Web.Topic format to specify a web.
   * =subscribe_subscriber= WikiName of user to subscribe/unsubscribe. Current user is used if missing.
   * =subscribe_remove= true to unsubscribe. Default is to subscribe.
Note that the calling user *must* be authenticated, and *must* have write permission for the !WebNotify topic in the relevant web.

---++ Plugin Installation Instructions
You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -&gt; "Install, Update or Remove extensions" Tab.  Click the "Search for Extensions" button.  
Enter part of the extension name or description and press search.   Select the desired extension(s) and click install. If an extension is already installed, it will *not* show up in the
search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)
<verbatim>
cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install
</verbatim>

If you have any problems, or if the extension isn't available in =configure=, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.


A word of warning; if you used !SubscribePlugin before version 3.1, please note that the use of GET requests for subscriptions is no longer supported. That means that Javascript *must* to be available in the browser..

---++ Plugin Info

Another great Foswiki extension from the <img src="%ATTACHURLPATH%/wikiringlogo20x20.png" alt="WikiRing" /> *WikiRing* - working together to improve your wiki experience!

|  Dependencies: | <table border="1" class="foswikiTable"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">Foswiki::Contrib::MailerContrib</td><td align="left">&gt;=0</td><td align="left">Foswiki mailer module</td></tr><tr><td align="left">JSON</td><td align="left">&gt;0</td><td align="left">Required. Available from the CPAN archive.</td></tr></table> |
|  Change&nbsp;History: | <!-- versions below in reverse order -->&nbsp; |
|  3.6 (08 Dec 2017) | Foswikitask:Item14554: remove link to unused wikiring.com domain. |
|  3.5 (06 Nov 2015) | Foswikitask:Item13519: Add dependency on URI due to MailerContrib dependency. |
|  3.4 (27 Jul 2015) | Foswikitask:Item13450: Fix support for FamFamFam skin.  |
|  3.3 (04 May 2015) | Foswikitask:Item13393: simplified implementation |
|  3.2 (24 Nov 2014) | Foswikitask:Item12926: removed requirement for an HTML form wrapping the button |
|  3.1 (28 Apr 2014) | Foswikitask:Item12872: Add CSRF validation support |
|  3.0 (14 Mar 2013) | Foswikitask:Item2258: added template support. Foswikitask:Item2450: Fix subscription to subweb topics. Foswikitask:Item11015: Improve docs. Foswikitask:Item8095: Analyse and fix load failures. Foswikitask:Item11543: Add unit tests. Foswikitask:Item10045: Support non-ascii topic names. Foswikitask:Item11595: Use REST handler for post with strikeone. |
|  2.0 (03 Mar 2012) | GeorgeClark - Foswikitask:Item11594 - Add ActiveWebs configuration. |
|  1.0 (03 Dec 2008) | Released for Foswiki |


%META:FORM{name="PackageForm"}%
%META:FIELD{name="Author" title="Author" value="[[http://c-dot.co.uk][Crawford Currie]]"}%
%META:FIELD{name="Version" title="Version" value="3.6"}%
%META:FIELD{name="Compatibility" title="Compatibility" value="2.0"}%
%META:FIELD{name="Release" title="Release" value="08 Dec 2017"}%
%META:FIELD{name="Repository" title="Repository" value="https://github.com/foswiki/distro"}%
%META:FIELD{name="Copyright" title="Copyright" value="&copy; 2007-2014, Crawford Currie http://c-dot.co.uk %25BR%25 &copy; 2008-2014 Foswiki Contributors"}%
%META:FIELD{name="License" title="License" value="GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]])"}%
%META:FIELD{name="Home" title="Home" value="http://foswiki.org/Extensions/SubscribePlugin"}%
%META:FIELD{name="Support" title="Support" value="http://foswiki.org/Support/SubscribePlugin"}%
%META:FILEATTACHMENT{name="subscribe_plugin.js" attr="h" comment="" date="1512791273" size="713" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="subscribe_plugin.uncompressed.js" attr="h" comment="" date="1512791273" size="2378" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="logo.gif" attr="h" comment="" date="1512791273" size="21246" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="wikiringlogo20x20.png" attr="h" comment="" date="1512791273" size="1343" user="ProjectContributor" version="1"}%
