Skip to content

Commit

Permalink
Item14378: Documentation fixes, prepare for release.
Browse files Browse the repository at this point in the history
  • Loading branch information
@gac410
gac410 committed Apr 30, 2017
1 parent 14c5456 commit 3d7b490
Show file tree
Hide file tree
Showing 2 changed files with 58 additions and 22 deletions.
56 changes: 46 additions & 10 deletions data/System/NotificationPlugin.txt
View file
@@ -1,4 +1,4 @@
%META:TOPICINFO{author="ProjectContributor" date="1493436293" format="1.1" version="1"}%
%META:TOPICINFO{author="ProjectContributor" date="1493512901" format="1.1" version="1"}%
---+!! <nop>%TOPIC%
<!--
* Set SHORTDESCRIPTION = %$SHORTDESCRIPTION%
Expand All @@ -14,12 +14,12 @@ Allows you to specify to kinds of notifications - immediate and regular. Immedia
There are two types of notifications - Immediate and Normal.

---+++ Immediate notifications
This type of notifications is send immediatly after user change watched topic. This type of notification is send even if the user checks the (deprecated) 'Don't notify' checkbox.
This means that you can see ANY change which is made in selected topics or webs. But, on the other hand, this is also the best way to be spammed with many mails if you set immediate
This type of notification is send immediately after a user changes a watched topic. This type of notification is send even if the user uses _Quiet Save_ or checks the (deprecated) 'Don't notify' checkbox.
This means that you will be notified for ANY change which is made in selected topics or webs. But, on the other hand, this is also the best way to be spammed with many mails if you set immediate
notification on whole webs if topics in this web are often changed. You have to decide when to use this type of notification.

---+++ Regular notifications
This type of notifications is similar to the default Foswiki notification system, but it also ignores the "Don't notify" checkbox. This notificaiton type requires a cron-job to
This type of notifications is similar to the default Foswiki notification system - MailerContrib, but it also ignores the "Don't notify" checkbox. This notificaiton type requires a cron-job to
run the mailnotify rest handler.

The site administrator can chose which types of notifications to allow, by
Expand All @@ -33,7 +33,7 @@ Current settings:

---++ Syntax Rules

You have to create topic *%Your_user_name%NotifyList* in *Main* web from template Main.NotificationPluginListTemplate. Fill it with desired topics, webs and regexps and enjoy...
You can create a topic *%Your_user_name%NotifyList* in *Main* web from template Main.NotificationPluginListTemplate. Fill it with desired topics, webs and regexps and enjoy...

%IF{"istopic '%USERSWEB%.%WIKINAME%NotifyList'"
then="%ICON{edittopic}% <a href='%SCRIPTURLPATH{"edit"}%/%WIKIUSERNAME%NotifyList'><strong>Edit existing <nop>%WIKIUSERNAME%NotifyList now!</strong></a>"
Expand All @@ -43,17 +43,20 @@ You have to create topic *%Your_user_name%NotifyList* in *Main* web from templat
<div class="foswikiHelp">%T% The headings in the topic are important. If the headings are missing, the
notifications will not be performed.</div>

If the topic is missing, and you use one of the buttons provided by the =NTF=
macro, it will be automatically created.

---+++ NTF Macro
For adding _fast switching_ to notifications you can use =%<nop>NTF{}%= variable:
For adding _fast switching_ to notifications you can use =%<nop>NTF{}%= macro:

%INCLUDE{"VarNTF" section="ntf_attributes"}%

---++++ NTF examples
---++++ NTF examples (if installed)
* =%<nop>NTF{}%= - displays all four buttons
* %NTF%
* =%<nop>NTF{win="off" wn="off"}%= - displays only buttons for topic immediate notification and regular topic notification
* %NTF{win="off" wn="off"}%
* =%<nop>NTF{popup="on"}%= - Displays a button to open the Update Notifications dialog.
* =%<nop>NTF{popup="on"}%= - Displays a link or button to open the Update Notifications dialog.
* %NTF{popup="on"}%

---+++ Description of <nop>NotifyList topics
Expand All @@ -74,7 +77,7 @@ If you want to set immediate notifications on all topics in web Test and topics
* Add child notifications (setting an topic and get notifications of all its children)

---++ NTF Popup
This block is displayed into a JQDialog pop-up when the NOtifications button
This block is displayed into a JQDialog pop-up when the Notifications button / link
generated by the =%<nop>NTF{popup="on"}%= macro is pressed.
<verbatim class="tml">
%STARTSECTION{"notification"}%
Expand All @@ -100,7 +103,7 @@ generated by the =%<nop>NTF{popup="on"}%= macro is pressed.
%ENDSECTION{"notification"}%
</verbatim>

---++ Running "Normal" notifications.
---++ Sending "Normal" notifications.

<div class="foswikiHelp">%T% Note that normal notifications are disabled in
bin/configure by default.</div>
Expand All @@ -113,6 +116,18 @@ to run it with the web server userid, to prevent file ownership changes.
| =-q=1= | Quiet mode. No output is printed. Basic information logged to the Foswiki debug log. |
| =-n=1= | Dry-run. No email will be sent. The run timestamps are not changed. |

---+++ Sample crontab entry:
The following entry would run an offline notification every 8 hours at 15
minutes past the hour.
<verbatim>
15 */8 * * * cd /path/to/website/bin/bin && perl ./rest /NotificationPlugin/mailnotify -q=1
</verbatim>

---+++ Run a normal notification now:

An administrator can also run the notifications now by sending a POST to the
rest handler:

<form name="mailnotify" action="%SCRIPTURLPATH{rest}%/NotificationPlugin/mailnotify" method="post">
<input type="checkbox" name="q" /> Quiet mode, no results printed.<br/>
<input type="checkbox" name="n" checked /> Dry run - no email sent<br/>
Expand All @@ -125,6 +140,16 @@ Some unusual files are installed that are worthy of mention:
| ==templates/htmlchanges.tmpl== | Template for generating HTML mails with notifications |
| ==templates/view.notify.tmpl== | Template overrides the SubscribePlugin's "subscribe" link with a link to "Update Notifications" dialog. |

If you want a "Notifications" button to be automatically provided on every
page, enable the override to the Skin by the "notify" skin template:

* <nop>Set SKIN = notify,natedit,pattern

Note that a number of template files no longer ship with this extension. The
did not appear to be used. Please [[https://foswiki.org/Tasks][open a task]]
if they are required. The templates are =changes-*.tmpl= and
=mailnotify-*.tmpl=

---++ Info
Original version sponsored by [[http://www.systinet.com][Systinet]] ;-)

Expand All @@ -150,3 +175,14 @@ Original version sponsored by [[http://www.systinet.com][Systinet]] ;-)
| 26 Apr 2004 (1.01) | Version 1.1 - new functions; added support for fast setting notifications |
| 14 Jan 2004 | Initial version |

%META:FORM{name="PackageForm"}%
%META:FIELD{name="Author" title="Author" value="Foswiki:Main.RichardBaar Foswiki:Main.ProjectContributors"}%
%META:FIELD{name="Description" title="Description" value="Send fine grained notifications of changes to topics you are interested in."}%
%META:FIELD{name="Version" title="Version" value="%25$VERSION%25"}%
%META:FIELD{name="Release" title="Release" value="%25$RELEASE%25"}%
%META:FIELD{name="Repository" title="Repository" value="https://github.com/foswiki/NotificationPlugin"}%
%META:FIELD{name="Copyright" title="Copyright" value="&copy; 2004, Foswiki:Main.RichardBaar<br />&copy; 2004-2010 Foswiki:%25SYSTEMWEB%25.ProjectContributor"}%
%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/NotificationPlugin"}%
%META:FIELD{name="Support" title="Support" value="http://foswiki.org/Support/NotificationPlugin"}%

24 changes: 12 additions & 12 deletions lib/Foswiki/Plugins/NotificationPlugin/MANIFEST
View file
Expand Up @@ -4,17 +4,17 @@ data/System/VarNTF.txt 0644
lib/Foswiki/Plugins/NotificationPlugin.pm 0644
lib/Foswiki/Plugins/NotificationPlugin/Config.spec 0755
lib/Foswiki/Plugins/NotificationPlugin/DEPENDENCIES 0644
templates/changes-multi-text.tmpl 0644
templates/changes-single-html.tmpl 0644
templates/changes-single-text.tmpl 0644
templates/changes-srg-html.pattern.tmpl 0644
templates/changes-srg-html.tmpl 0644
templates/changes-srg-text.tmpl 0644
#templates/changes-multi-text.tmpl 0644
#templates/changes-single-html.tmpl 0644
#templates/changes-single-text.tmpl 0644
#templates/changes-srg-html.pattern.tmpl 0644
#templates/changes-srg-html.tmpl 0644
#templates/changes-srg-text.tmpl 0644
templates/htmlchanges.tmpl 0644
templates/mailnotify-multi-html.tmpl 0644
templates/mailnotify-multi-text.tmpl 0644
templates/mailnotify-single-html.tmpl 0644
templates/mailnotify-single-text.tmpl 0644
templates/mailnotify-srg-html.tmpl 0644
templates/mailnotify-srg-text.tmpl 0644
#templates/mailnotify-multi-html.tmpl 0644
#templates/mailnotify-multi-text.tmpl 0644
#templates/mailnotify-single-html.tmpl 0644
#templates/mailnotify-single-text.tmpl 0644
#templates/mailnotify-srg-html.tmpl 0644
#templates/mailnotify-srg-text.tmpl 0644
templates/view.notify.tmpl 0644

0 comments on commit 3d7b490

Please sign in to comment.