internal package Foswiki::Contrib::MailerContrib::WebNotify

See Published API for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

Child packagesChild packages

internal package Foswiki::Contrib::MailerContrib::WebNotify

Object that represents the contents of a Web Notify topic in a Foswiki web.

Note that $Foswiki::Plugins::SESSION is used to find the Foswiki session, and must be set up before this class is used.

ClassMethod new($web, $topic)

• $web - web name
• $topic - topic name
• $noexpandgroups - True will prevent expansion of group subscriptions (False is best for checking subscriptions, but True is best for writing results back to $topic)

Create a new object by parsing the content of the given topic in the given web. This is the normal way to load a Web Notify topic. If the topic does not exist, it will create an empty object.

ObjectMethod writeWebNotify()

Write the object to the Web Notify topic it was read from. If there is a problem writing the topic (e.g. it is locked), or the current user is not authorised to write it, then the method will throw an exception.

ObjectMethod getSubscriber($name, $noAdd)

• $name - Name of subscriber (wikiname with no web or email address)
• $noAdd - If false or undef, a new subscriber will be created for this name

Get a subscriber from the list of subscribers, and return a reference to the Subscriber object. If $noAdd is true, and the subscriber is not found, undef will be returned. Otherwise a new Subscriber object will be added if necessary.

ObjectMethod getSubscribers()

Get a list of all subscriber names (unsorted)

ObjectMethod subscribe($name, $topics, $depth, $options)

• $name - Name of subscriber (wikiname with no web or email address)
• $topics - wildcard expression giving topics to subscribe to
• $depth - Child depth to scan (default 0)
• $options - Bitmap of Mailer::Const options

Add a subscription, adding the subscriber if necessary.

ObjectMethod unsubscribe($name, $topics, $depth)

• $name - Name of subscriber (wikiname with no web or email address)
• $topics - wildcard expression giving topics to subscribe to
• $depth - Child depth to scan (default 0)

Add an unsubscription, adding the subscriber if necessary. An unsubscription is a specific request to ignore notifications for a topic for this particular subscriber.

ObjectMethod stringify([$subscribersOnly]) → string

Return a string representation of this object, in Web Notify format.

Optional $subscribersOnly parameter to only print the parsed subscription list. Used when running a mailnotify, where printing out the entire Web Notify topic is confusing, as it's different from the actual topic contents, but doesn't inform the user why.

ObjectMethod processChange($change, $db, $changeSet, $seenSet, $allSet)

• $change - ref of a Foswiki::Contrib::Mailer::Change
• $db - Foswiki::Contrib::MailerContrib::UpData database of parent references
• $changeSet - ref of a hash mapping name&emails to sets of changes
• $seenSet - ref of a hash recording indices of topics already seen for each name&email addressee
• $allSet - ref of a hash that maps topics to name&email ids for news subscriptions

Find all subscribers that are interested in the given change. Only the most recent change to each topic listed in the .changes file is retained. This method does not change this object.

ObjectMethod processCompulsory($topic, $db, \%allSet)

• $topic - topic name
• $db - Foswiki::Contrib::MailerContrib::UpData database of parent references
• \%allSet - ref of a hash that maps topics to name&email addresses for news subscriptions

ObjectMethod isEmpty() → boolean

Return true if there are no subscribers

ObjectMethod parsePageSubscriptions($who, $spec, $unsubscribe)

Parse a pages list for a single user (corresponding to one line in Web Notify), adding subscriptions for user $who as appropriate If $unsubscribe is set to '-' by Subscribe Plugin to force a '-' operation