PmWiki | Cookbook / Bulletin (original) (raw)

Summary: Notify with rich text emails

Version: 2025-11-14

Prerequisites: PmWiki 2.4.5, PHP 7.2+

Status: Experimental

License: GPL

This recipe allows the sending of email notifications for recent wiki changes in rich text (HTML), by configuring PageLists.

Description

Notify with rich text emails.

Installation

This requires PHP 7.2 or more recent and PmWiki 2.4.5 or more recent.

Place bulletin.php Δ in your pmwiki/cookbook folder.
Add to config.php the following:
include_once("$FarmD/cookbook/bulletin.php");

Configuration

$Bulletin['authfunction'] = 'BulletinAuthPage';
You may want to enable this if your wiki has password-protected sections that are included in notifications, otherwise the page variables and inclusions may return blank strings.

Internationalization

The following strings can be translated in an XLPage:

Usage

Lists of recipients

Create a page SiteAdmin.BulletinList with such content:

!! Recipient group settings bulletin=#group1 delay=15m squelch=3h group=Main subject="[Wiki Bulletin] Recent posts" fmt=#titlesummary bulletin=#daily delay=1h squelch=1d group=Main subject="Daily Wiki Bulletin" bulletin=#biweekly delay=1h squelch=2w group=Main subject="Wiki Bulletin"

!! User group "group1" [[#group1]] user1@example.com user2@example.com [[#group1end]]

!! User group "daily" [[#daily]] user3@example.com user4@example.com [[#dailyend]]

!! User group "biweekly" [[#biweekly]] user5@example.com user6@example.com [[#biweeklyend]]

The anchor names like #biweekly can be anything, these correspond to the bulletin= lines above.
The arguments delay and squelch work the same way as PmWiki.Notify.
The argument subject allows you to set the subject to the email.
The argument group restricts the notifications to a specific wikigroup.
The arguments fmt=#titlesummary group=Main order=-time work like in PageLists.
The emails are parsed from the text between the anchors [[#daily]]...[[#dailyend]] and can be on different lines or separated by spaces, commas, semicolons. Only the addresses are matched, anything else is ignored.

Message templates

You can configure custom PageList templates in Site.LocalTemplates with the format you need, for example:

[[#bulletin-short]] (:template defaults order=time:) (:template first:) cid:pub/skins/pmwiki/pmwiki-32.gif Please find below links to pages that have been recently modified.

(:template each:) !!!![[{=$FullName}|+]] {=$:Summary}

(:template last:) To unsubscribe, email mailto:manager@example.com. (:template none:) No recently modified pages. (This should not normally be sent.) [[#bulletin-shortend]]

[[#bulletin-full]] (:template first:) Please find below pages that have been recently modified.

(:template each:) ! [[{=$FullName}|+]] ''Last modified: {=$LastModified}''

(:include {=$FullName} basepage={=$FullName}:)

(:template last:) To unsubscribe, email mailto:manager@example.com. [[#bulletin-fullend]]

Then in the bulletin= line you can add fmt=#bulletin-short for the email to use that template.

How to add a logo to the email

You could add the logo in the pagelist template, either in 'template first' or 'template last', with the normal markup Attach:Group.Page/logo.png or https://example.com/path/to/logo.png however many email clients will block the picture from displaying.

You can attach the logo picture to the email, and it should appear in the page. To do this, add the following to the pagelist template:

cid:pub/skins/pmwiki/pmwiki-32.gif

or:

cid:uploads/Main/logo.png"Alt text e.g. Logo"

It starts with the "cid:" prefix followed by the path relative to index.php as shown above, or the absolute path to the file starting with "/".

Only files with extensions JPG, JPEG, PNG, or GIF (also lowercase) are compatible with many email clients and webmails.

Notes

Unlike PmWiki.Notify which lists all changes to watched pages, Bulletin only shows the latest versions of the modified pages.

To do / some day / maybe

Convert to Extension.

Change log / Release notes

2025-11-14: The subject line can now include the variables {$$titles}, {$$tags}, or {$$count}. The subject is now correctly encoded.
2025-06-02a: Allow for bulletin= definitions to be on multiple lines ending with backslash. Add $Bulletin['cancelsendpatterns'].
2025-05-22: Allowed for the same email to appear in different sections.
2025-04-10: First public release, ready to be tested.

Contributors

Written, documented, and maintained by Petko

Comments

See discussion at Bulletin-Talk

User notes : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.