Skip to content

Commit

Permalink
Item9551: Docs and improve prefs
Browse files Browse the repository at this point in the history 
Change to use the Meta::getPreference method for processing the settings
for IMMEDIATENOTIFYMETHOD and IMMEDIATENOTIFY.  This is needed because:
 - The Func preferences API is cached and doesn't reflect changes in the
   current topic just saved.
 - The User topic is not necessarily readable by the user that triggers
   the notification.  The Func preferences API requires that the topic
   be readable by the user.
The Meta preferences API doesn't have either of these restrictions.

git-svn-id: http://svn.foswiki.org/trunk/ImmediateNotifyPlugin@12252 0b4bb1d4-4e5a-0410-9cc4-b2b747904278
  • Loading branch information
GeorgeClark authored and GeorgeClark committed Jul 30, 2011
1 parent 34682c5 commit cd5e064
Show file tree
Hide file tree
Showing 4 changed files with 204 additions and 59 deletions.
24 changes: 16 additions & 8 deletions data/System/ImmediateNotifyPlugin.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,11 @@ Unlike MailerContrib, this extension will perform an __immediate__ notification
* Need for immediate notification
* Need for notification using XMPP (Jabber) or other non-standard channels.

%X% Note that this extension is less efficient than the MailerContrib, and adds a small delay during save while the notifications are sent.
<blockquote class="foswikiHelp">%X% Note that this extension is less efficient than the MailerContrib, and adds a small delay during save while the notifications are sent.</blockquote>

The notifications are triggerd from two sources:
* Web based notifications are set in the WebImmediateNotify topic. Users listed in that topic will be notified of any changes to the web.
* Web based notifications are set in the <nop>WebImmediateNotify topic. Users listed in that topic will be notified of any changes to the web.
* Note: Unlike MailerContrib, this topic is a simple list of users to notify. There is no ability to specified the desired topics.
* Topic based notifications are set in the individual topics that will be tracked for notification.

---++ Important Changes in this release
Expand All @@ -22,8 +23,13 @@ This version makes significant changes in the configuration of the plugin:
* Sensitive server user/password information is moved into the Foswiki configuration
* Methods must be made available by enabling in the configuration
* The syntax of the jabber user to be notified has been changed. The line ="Jabber:user@server"= is replaced. user@server is now a parameter of the IMMEDIATENOTIFYMETHOD.
* Jabber has been renamed to XMPP in line with the current protocol definition.

---++ Syntax Rules
There are 3 areas of configuration:
* *Who to notify:* This is set in the Web<nop>ImmediateNotifyTopic (Web based), or in individual topics (topic based).
* *How to notify them:* This is optionally set per user in the User's topic.
* *Notification methods:* Available and default methods, server acccess passwords, etc. These are set using [[%SCRIPTURL{"configure"}%#ImmediateNotifyPlugin$Extensions][configure]]
---+++ Web based notifications

Register for notification in the Web<nop>ImmediateNotify topic by adding their username as an entry in a bullet list.
Expand All @@ -32,18 +38,20 @@ Register for notification in the Web<nop>ImmediateNotify topic by adding their u
* MyTeamGroup
</verbatim>

<blockquote class="foswikiHelp">%X% Do not add any information beyond the user name desiring notification. There is no topic include/exclude filtering like in the MailerContrib.</blockquote>

---+++ Topic based notifications

Add a set statement to the topic. WikiNames (or groups) are listed in a comma separated list. The user web prefix is supported but not required.
Add a set statement to the topic, either directly inline, or using the "Topic Settings" editor. WikiNames (or groups) are listed in a comma separated list. The user web prefix is supported but not required.
<verbatim>
* Set IMMEDIATENOTIFY = JoeUser, MyTeamGroup
</verbatim>

---+++ User configuration

The user may optionally configure their desired notification method. Since SMTP and XMPP are currently the only available methods, this consists of:
The user may optionally configure their desired notification method. Since XMPP and SMTP are currently the only available methods, this consists of:

* Adding a line =" * Set IMMEDIATENOTIFYMETHOD = XMPP(userid)"= (or "SMTP", respectively) to their user topic.
* Adding a line =" * Set IMMEDIATENOTIFYMETHOD = XMPP(userid)"= (or "SMTP", respectively) to their user topic either inline, or using the "Topic Settings" editor.

If no notification method is selected, the user will be notified using SMTP.

Expand All @@ -53,14 +61,14 @@ If no notification method is selected, the user will be notified using SMTP.

---++ <nop>%TOPIC% Global Settings

%X% In this version of %TOPIC%, configuration settings are __not read from this topic__. System settings are configured in the %USERSWEB%.SitePreferences topic
In this version of %TOPIC%, configuration settings are __not read from this topic__. System settings are configured in the %USERSWEB%.SitePreferences topic.

* Debug plugin: (See output in =data/debug.txt=)
* Set IMMEDIATENOTIFYPLUGIN_DEBUG = 1

---++ <nop>%TOPIC% Configuration

%X% This version of the plugin must be configured in the Foswiki system configuration using the [[%SCRIPTURL{"configure"}%][configure script]].
This version of the plugin must be configured in the Foswiki system configuration using the [[%SCRIPTURL{"configure"}%#ImmediateNotifyPlugin$Extensions][configure script]].

* Enable the desired notification methods in the configuration. If a notification method is not enabled here, it will be unavailable for users to use.
* ={Plugins}{ImmediateNotifyPlugin}{SMTP}{Enabled}=
Expand Down Expand Up @@ -96,7 +104,7 @@ __Note:__ You do not need to install anything on the browser to use this plugin.
| Plugin Version: | %$VERSION% |
| Plugin Release: | %$RELEASE% |
| Change History: | <!-- specify latest version first --> |
| 26 Jun 2011 | Foswikitask:Item9551 - Major new release, significant config changes |
| 26 Jul 2011 | Foswikitask:Item9551 - Major new release, significant config changes |
| 26 Aug 2010 | Test release - Foswikitask:Item9551 |
| 05 Jan 2010 | Ported to Foswiki (Foswiki:Main.WillNoris) |
| 21 May 2007 | Bugs:Item3969 - 8bit email fix (Foswiki:Main.WillNorris) |
Expand Down
174 changes: 124 additions & 50 deletions lib/Foswiki/Plugins/ImmediateNotifyPlugin.pm
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,13 @@
# Immediate Notify Plugin for Foswiki - The Free and Open Source Wiki, http://foswiki.org/
#
# Copyright (C) 2003 Walter Mundt, emage@spamcop.net
# Copyright (C) 2003 Akkaya Consulting GmbH, jpabel@akkaya.de
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details, published at
# http://www.gnu.org/copyleft/gpl.html
#
# =========================
#
# This plugin supports immediate notification of topic saves.
#
# =========================
# See bottom of file for default license and copyright information

=begin TML
---+ package Foswiki::Plugins::ImmediateNotifyPlugin
This plugin supports immediate notification of topic saves.
=cut

package Foswiki::Plugins::ImmediateNotifyPlugin;
use strict;
use warnings;
Expand All @@ -36,20 +25,38 @@ my %methodAllowed; # Methods permitted by config.

# Regular expressions used in topic processing

my $NOTIFYREGEX =
qr/$Foswiki::regex{setRegex}(?:IMMEDIATENOTIFYPLUGIN_)?IMMEDIATENOTIFY\s*=\s*(.*?)$/sm;

my $METHODREGEX =
qr/$Foswiki::regex{setRegex}(?:IMMEDIATENOTIFYPLUGIN_)?IMMEDIATENOTIFYMETHOD\s*=\s*(.*?)(?:\((.*?)\))?\s*$/sm;

=begin TML
---+ debug ( $message )
Write debug messages if debug is enabled.
=cut

sub debug { Foswiki::Func::writeDebug(@_) if $debug; }

=begin TML
---+ warning ( $message )
Unconditionally write warning messages to debug log.
=cut

sub warning {
Foswiki::Func::writeWarning(@_);
debug( "WARNING" . $_[0], @_[ 1 .. $#_ ] );
}

# =========================
=begin TML
---+ initPlugin ( $topic, $web, $user)
=cut

sub initPlugin {
my ( $topic, $web, $user, $installWeb ) = @_;
my $methodCount = 0;
Expand All @@ -65,9 +72,11 @@ sub initPlugin {
$debug = Foswiki::Func::getPluginPreferencesFlag("DEBUG") || 0;

# Find any configured methods and make available.
foreach my $method ( keys %{$Foswiki::cfg{Plugins}{ImmediateNotifyPlugin}} ) {
next if ($method eq "Module" );
next if ($method eq "Enabled" );
foreach
my $method ( keys %{ $Foswiki::cfg{Plugins}{ImmediateNotifyPlugin} } )
{
next if ( $method eq "Module" );
next if ( $method eq "Enabled" );
if ( $Foswiki::cfg{Plugins}{ImmediateNotifyPlugin}{$method}{Enabled} ) {
debug("Allowing method $method");
$methodAllowed{$method} = 1;
Expand All @@ -88,6 +97,14 @@ sub initPlugin {
}
}

=begin TML
---+ finishPlugin ( )
Unload and disconnect any notifier methods with open connections.
=cut

sub finishPlugin {

debug("finishPlugin entered");
Expand All @@ -98,6 +115,14 @@ sub finishPlugin {
}
}

=begin TML
---+ _loadHandler ( $mehod )
Find and load the requested notifitcation method.
=cut

sub _loadHandler {
my $method = shift;
return 1 if $methodHandlers{$method}; # Already loaded
Expand Down Expand Up @@ -137,6 +162,18 @@ sub _loadHandler {
}
}

=begin TML
---+ processName ($name, $users, $groups)
* $name - User Name being processed
* $users - Hash of users on notification list
* $groups - Hash of groups on notification list
Parse names to be notified, expanding groups and reading settings for each user.
=cut

sub processName {
my ( $name, $users, $groups ) = @_;

Expand All @@ -155,22 +192,31 @@ sub processName {
}
else {

# SMELL: We can't use Preferences API to retrieve user topic information.
# API requires that topic be readable by current user, but we can't
# be sure of that - and user topics are often protected.
if (
Foswiki::Func::topicExists(
"$Foswiki::cfg{UsersWebName}", "$name"
)
)
{
my ( $topicObject, $text ) =
Foswiki::Func::readTopic( "$Foswiki::cfg{UsersWebName}",
"$name" );

my $methodString =
$topicObject->getPreference('IMMEDIATENOTIFYMETHOD');

my ( $meta, $text ) =
Foswiki::Func::readTopic( "$Foswiki::cfg{UsersWebName}", "$name" );
if ($text) {
$users->{$name}{TEXT} = $text;
debug(
"- ImmediateNotifyPlugin: method setting for $name found /$methodString/"
);

if ( $text =~ /$METHODREGEX/ ) {
my $parms = $3 || '';
if ($methodString) {
my ( $method, $parms ) =
$methodString =~ m/^(.*?)(?:\((.*?)\))?$/;
debug(
"- ImmediateNotifyPlugin: processName: User $name found method ($2) parms ($parms) "
"- ImmediateNotifyPlugin: processName: User $name found method ($method) parms ($parms) "
);
$users->{$name}{METHOD} = $2;
$users->{$name}{PARMS} = $parms;
$users->{$name}{METHOD} = $method || 'SMTP';
$users->{$name}{PARMS} = $parms || '';
}
else {
$users->{$name}{METHOD} = 'SMTP';
Expand All @@ -187,7 +233,14 @@ sub processName {
}
}

# =========================
=begin TML
---+ afterSaveHandler
Procesas the saved topic peforming any requested notifications
=cut

sub afterSaveHandler {
my ( $text, $topic, $web, $error, $topicObject ) = @_;
my $user = Foswiki::Func::getWikiName();
Expand All @@ -206,22 +259,21 @@ sub afterSaveHandler {
return;
}

# SMELL: We should not have to parse out topic text. But the old preferences
# cache is still loaded in the afterSaveHandler. So we would miss changes made
# to the IMMEDIATENOTIFY setting in this save.
#my $nameString = Foswiki::Func::getPreferencesValue('IMMEDIATENOTIFY') || '';

my @names;

# NOTE: in this case we DO want to use the Meta::getPreference() function. If the normal
# preferences API is used, settings are cached and don't reflect changes just saved in this
# transaction. The Meta function uses the raw topic data and not the cached settings.

# Check if the topic contains an IMMEDIATENOTIFY setting and extract names if present
if ( $text =~ /$NOTIFYREGEX/ ) {
debug("- ImmediateNotifyPlugin: Found ($2) ");
my $nameString = $2;
my $nameString = $topicObject->getPreference('IMMEDIATENOTIFY');
if ($nameString) {
debug("- ImmediateNotifyPlugin: Found ($nameString) ");
chomp $nameString;
@names = split /[\s,]+/, $nameString;
foreach my $n (@names) {
debug(
"- ImmediateNotifyPlugin: ($n) found in IMMEDIATENOTIFY in topic text"
"- ImmediateNotifyPlugin: ($n) found in IMMEDIATENOTIFY setting"
);
}
}
Expand Down Expand Up @@ -292,3 +344,25 @@ sub afterSaveHandler {
}

1;

__END__
Foswiki - The Free and Open Source Wiki, http://foswiki.org/
Copyright (C) 2008-2011 Foswiki Contributors. Foswiki Contributors
are listed in the AUTHORS file in the root of this distribution.
Copyright (C) 2010-2011 George Clark
Copyright (C) 2003 Walter Mundt, emage@spamcop.net
Copyright (C) 2003 Akkaya Consulting GmbH, jpabel@akkaya.de
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version. For
more details read LICENSE in the root of this distribution.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
As per the GPL, removal of this notice is prohibited.
32 changes: 32 additions & 0 deletions lib/Foswiki/Plugins/ImmediateNotifyPlugin/SMTP.pm
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,13 @@
# See bottom of file for default license and copyright information

=begin TML
---+ package Foswiki::Plugins::ImmediateNotifyPlugin::SMTP
This plugin module supports immediate notification of topic saves using the XMPP (Jabber) protocol.
.
=cut

package Foswiki::Plugins::ImmediateNotifyPlugin::SMTP;

use strict;
Expand Down Expand Up @@ -76,3 +86,25 @@ sub disconnect {
}

1;

__END__
Foswiki - The Free and Open Source Wiki, http://foswiki.org/
Copyright (C) 2008-2011 Foswiki Contributors. Foswiki Contributors
are listed in the AUTHORS file in the root of this distribution.
Copyright (C) 2010-2011 George Clark
Copyright (C) 2003 Walter Mundt, emage@spamcop.net
Copyright (C) 2003 Akkaya Consulting GmbH, jpabel@akkaya.de
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version. For
more details read LICENSE in the root of this distribution.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
As per the GPL, removal of this notice is prohibited.
Loading

0 comments on commit cd5e064

Please sign in to comment.